visionary-verse / README.md
Ekocak's picture
Update Readme.md
142e216 verified
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 ✒️

Hugging Face Spaces Python 3.9 Docker FastAPI

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.

  1. Clone the repository:

    git clone [https://github.com/ekocak02/visionary-verse.git](https://github.com/ekocak02/visionary-verse.git)
    cd visionary-verse
    
  2. Build the Docker image:

    docker build -t visionary-verse .
    
  3. 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
    
  4. 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..."
    }