Spaces:
Running
Running
Update Readme.md
Browse files
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 |
+
[](https://ekocak-visionary-verse.hf.space)
|
19 |
+
[](https://www.python.org/downloads/release/python-390/)
|
20 |
+
[](https://www.docker.com/)
|
21 |
+
[](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 |
+
```
|