metadata

title: Visionary Verse
emoji: ✒️
colorFrom: green
colorTo: blue
sdk: docker
app_port: 8000
readiness_check:
  path: /health

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

Visionary Verse ✒️

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.

Live Demo

You can try the live application hosted on Hugging Face Spaces:

➡️ https://ekocak-visionary-verse.hf.space/docs

(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.)

Features

Multi-Modal Input: Takes an image as input.
Image Understanding: Leverages a pre-trained Vision-Transformer model (microsoft/git-large-coco) to generate a descriptive caption for the image.
Creative Text Generation: Uses the caption as a prompt for a generative language model (gpt2) to create a unique short story.
API-First Design: A robust backend built with FastAPI, serving the AI model through a clean REST API.
Containerized & Reproducible: The entire application and its dependencies are containerized with Docker, ensuring it runs consistently in any environment.
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.

Tech Stack & Architecture

AI & Machine Learning: PyTorch, Transformers (Hugging Face)
Backend: Python 3.9, FastAPI, Uvicorn
DevOps & Deployment: Docker, GitHub Actions (CI), Hugging Face Spaces (CD)

How to Run Locally

To run this project on your local machine, ensure you have Docker installed.

Clone the repository:

git clone [https://github.com/ekocak02/visionary-verse.git](https://github.com/ekocak02/visionary-verse.git)
cd visionary-verse

Build the Docker image:
```
docker build -t visionary-verse .
```

Run the Docker container:

# To run on CPU
docker run --rm -p 8000:8000 visionary-verse

# To run with NVIDIA GPU access (if available)
# docker run --rm -p 8000:8000 --gpus all visionary-verse

Access the API:
- Open your web browser and go to http://127.0.0.1:8000/docs.
- Use the interactive Swagger UI to upload an image and test the /generate endpoint.

API Endpoint

`POST /generate`

Description: Uploads an image and returns a generated story.
Request Body: multipart/form-data containing the image file.

Successful Response (200 OK):

{
  "input_image_filename": "example.jpg",
  "generated_caption": "a cat sitting on a mountain top",
  "generated_story": "A fantasy adventure set in a land that once was a cat sitting on a mountain top: The feline, known as..."
}