Ekocak commited on
Commit
142e216
·
verified ·
1 Parent(s): 9a30172

Update Readme.md

Browse files
Files changed (1) hide show
  1. README.md +79 -0
README.md CHANGED
@@ -10,3 +10,82 @@ readiness_check:
10
  ---
11
 
12
  Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
10
  ---
11
 
12
  Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
13
+
14
+ ---
15
+
16
+ # Visionary Verse ✒️
17
+
18
+ [![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-yellow)](https://ekocak-visionary-verse.hf.space)
19
+ [![Python 3.9](https://img.shields.io/badge/python-3.9-blue.svg)](https://www.python.org/downloads/release/python-390/)
20
+ [![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge&logo=docker&logoColor=white)](https://www.docker.com/)
21
+ [![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=for-the-badge&logo=fastapi)](https://fastapi.tiangolo.com/)
22
+
23
+ An AI-powered service that generates creative fantasy stories inspired by an uploaded image. This project demonstrates an end-to-end MLOps workflow, from development and containerization to automated deployment.
24
+
25
+ ---
26
+
27
+ ### **Live Demo**
28
+
29
+ You can try the live application hosted on Hugging Face Spaces:
30
+
31
+ **➡️ [https://ekocak-visionary-verse.hf.space/docs](https://ekocak-visionary-verse.hf.space/docs)**
32
+
33
+ *(Note: The application is hosted on a free tier and may go to sleep. The first request might take a moment to wake it up and load the models.)*
34
+
35
+ ### **Features**
36
+
37
+ - **Multi-Modal Input:** Takes an image as input.
38
+ - **Image Understanding:** Leverages a pre-trained Vision-Transformer model (`microsoft/git-large-coco`) to generate a descriptive caption for the image.
39
+ - **Creative Text Generation:** Uses the caption as a prompt for a generative language model (`gpt2`) to create a unique short story.
40
+ - **API-First Design:** A robust backend built with FastAPI, serving the AI model through a clean REST API.
41
+ - **Containerized & Reproducible:** The entire application and its dependencies are containerized with Docker, ensuring it runs consistently in any environment.
42
+ - **Automated CI/CD:** A GitHub Actions workflow automates the process of building the Docker image and pushing it to a registry upon changes to the `main` branch.
43
+
44
+ ### **Tech Stack & Architecture**
45
+
46
+ - **AI & Machine Learning:** PyTorch, Transformers (Hugging Face)
47
+ - **Backend:** Python 3.9, FastAPI, Uvicorn
48
+ - **DevOps & Deployment:** Docker, GitHub Actions (CI), Hugging Face Spaces (CD)
49
+
50
+ ### **How to Run Locally**
51
+
52
+ To run this project on your local machine, ensure you have **Docker** installed.
53
+
54
+ 1. **Clone the repository:**
55
+ ```bash
56
+ git clone [https://github.com/ekocak02/visionary-verse.git](https://github.com/ekocak02/visionary-verse.git)
57
+ cd visionary-verse
58
+ ```
59
+
60
+ 2. **Build the Docker image:**
61
+ ```bash
62
+ docker build -t visionary-verse .
63
+ ```
64
+
65
+ 3. **Run the Docker container:**
66
+ ```bash
67
+ # To run on CPU
68
+ docker run --rm -p 8000:8000 visionary-verse
69
+
70
+ # To run with NVIDIA GPU access (if available)
71
+ # docker run --rm -p 8000:8000 --gpus all visionary-verse
72
+ ```
73
+
74
+ 4. **Access the API:**
75
+ - Open your web browser and go to **`http://127.0.0.1:8000/docs`**.
76
+ - Use the interactive Swagger UI to upload an image and test the `/generate` endpoint.
77
+
78
+ ### **API Endpoint**
79
+
80
+ #### `POST /generate`
81
+
82
+ - **Description:** Uploads an image and returns a generated story.
83
+ - **Request Body:** `multipart/form-data` containing the image file.
84
+ - **Successful Response (`200 OK`):**
85
+ ```json
86
+ {
87
+ "input_image_filename": "example.jpg",
88
+ "generated_caption": "a cat sitting on a mountain top",
89
+ "generated_story": "A fantasy adventure set in a land that once was a cat sitting on a mountain top: The feline, known as..."
90
+ }
91
+ ```