An intelligent, context-aware AI assistant that generates images, stories, and posters through natural language conversations. Features mood detection, intelligent clarifying questions, and multiple creative modes powered by Hugging Face Stable Diffusion XL.

Generate expressive artistic interpretations with intelligent mood detection

• Randomized art styles (impressionist, expressionist, abstract, surreal)
• Emotion-aware color palettes
• 768×768 high-quality output
• Fallback placeholders for reliability

Create professional poster backgrounds with optional text overlays

• Extract slogans from user input (quoted text or explicit patterns)
• Multiple poster aesthetics (minimalist, bold, elegant, modern)
• Web-ready image optimization
• Perfect for marketing materials

Generate 3-scene visual narratives with auto-generated story structures

• Cinematic, illustrated, and children's book styles
• Sequential scene-by-scene image generation
• Contextual mood preservation across scenes
• Story title generation included

Reimagine content in different artistic styles

• Oil painting, watercolor, sketch, cyberpunk styles
• Style-aware prompt engineering
• Maintains original intent while transforming aesthetic

Generate professional commercial visuals

• Clean, modern aesthetic optimized for corporate use
• Professional color palettes
• Premium quality settings
• Perfect for presentations and marketing

• Automatic detection of vague queries ("tell me about your day")
• Context-aware clarifying questions with mood detection
• Persistent user mood tracking across generation attempts
• Smart conversation state management

• Python 3.10+
• Node.js 18+
• RAM 4GB minimum (8GB+ recommended)
• Internet connection (for HuggingFace API)

# Navigate to backend directory
cd backend

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create .env file with HuggingFace token
echo "HF_API_TOKEN=your_hf_token_here" > .env

# Start backend server
uvicorn main:app --reload

Backend runs at http://localhost:8000

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

Frontend runs at http://localhost:5173

# In your browser
open http://localhost:5173

# Or manually test the API
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test-user",
    "message": "Create a peaceful landscape",
    "mode": "art"
  }'

# Link to Vercel
vercel link

# Deploy
vercel --prod

Environment variables needed:

• VITE_API_URL: Backend API endpoint

1. Create new Space on HuggingFace
2. Connect your GitHub repository
3. Add HF_API_TOKEN as a secret
4. Deploy automatically on push

1. Create new Web Service on Render
2. Connect GitHub repo
3. Configure environment variables
4. Deploy

Required environment variables:

HF_API_TOKEN=your_token_here

• Development: http://localhost:8000
• Production: https://your-backend-url.com

Main endpoint for all generation modes.

Request:

{
  "user_id": "unique-user-id",
  "message": "Create a peaceful landscape with mountains",
  "mode": "art",
  "conversation_id": "optional-conversation-id"
}

Response (Success):

{
  "type": "image",
  "content": {
    "images": ["base64_encoded_image_1", "base64_encoded_image_2"],
    "reasoning": "I interpreted 'peaceful landscape' through an impressionist lens...",
    "prompt_used": "peaceful landscape with mountains, impressionist style, artistic...",
    "mode": "art",
    "style": "impressionist",
    "metadata": {
      "generation_time": 18.5,
      "mood": "vibrant"
    }
  }
}

Response (Clarifying Question):

{
  "type": "question",
  "content": {
    "text": "Could you tell me more about how your day was?"
  }
}

Mode Values:

• art - Creative artistic generation
• poster - Poster background with optional text
• story - 3-scene narrative with images
• transform - Style transformation
• business - Professional commercial visuals
• personal - Default mode with user context (default)

Reset conversation history and mood for a user.

Request:

{
  "user_id": "unique-user-id"
}

Response:

{
  "status": "ok"
}

Check if backend is operational.

Response:

{
  "status": "healthy",
  "hf_configured": true,
  "timestamp": 1708536000.123
}

Get API version and model information.

Response:

{
  "service": "Vizzy Chat API",
  "version": "1.0.0",
  "status": "operational",
  "model": "Stable Diffusion XL via Hugging Face",
  "hf_url": "https://model-url"
}

User: "Draw my day"
↓
Vizzy: "Could you tell me more about how your day was?"
↓
User: "It was dull and I needed motivation"
↓
Vizzy: [Generates energetic abstract art with vibrant colors]

User (Art Mode): "A cyberpunk cityscape with neon lights at dusk"
↓
Vizzy: [Generates 2 impressionist/surreal interpretations]

User (Story Mode): "An adventure in an enchanted forest"
↓
Vizzy: 
  Scene 1: Opening image + description
  Scene 2: Middle image + description
  Scene 3: Conclusion image + description

User (Business Mode): "Professional office with modern furniture"
↓
Vizzy: [Generates corporate-ready product photography style images]

• No Persistent User Data: Conversation state is in-memory only
• CORS Protection: Configured for frontend URLs only
• Input Validation: All requests validated with Pydantic models
• Environment Secrets: API tokens stored securely in .env
• API Authentication: HuggingFace token required for model access
• No Tracking: No user analytics or telemetry

Error: HF_API_TOKEN not configured

# Solution: Create .env file in backend directory
cd backend
echo "HF_API_TOKEN=your_token_here" > .env

Error: Connection refused

• Ensure backend is running: uvicorn main:app --reload
• Check port 8000 is available
• Verify CORS is configured correctly

Error: Generation timeouts

• HuggingFace API may be slow or overloaded
• Check HuggingFace status page
• Fallback placeholders will be generated after 3 retries

Error: Failed to fetch from backend

• Ensure backend is running and accessible
• Check VITE_API_URL environment variable is set
• Verify CORS headers in backend response

Error: Images not displaying

• Clear browser cache
• Check base64 image encoding in response
• Verify image MIME types are correct

vizzy-chat/
├── backend/
│   ├── main.py              # FastAPI application with all endpoints
│   ├── memory.py            # User memory & preference management
│   ├── context.py           # Context tracking & mood detection
│   ├── story.py             # Story generation module
│   ├── intent.py            # Intent classification
│   ├── requirements.txt      # Python dependencies
│   └── .env                 # Environment variables (not in repo)
│
├── frontend/
│   ├── src/
│   │   ├── App.jsx          # Main React component
│   │   ├── Chat.js          # Chat UI component
│   │   ├── App.css          # Styling
│   │   └── main.jsx         # Entry point
│   ├── package.json         # Node dependencies
│   ├── vite.config.js       # Vite configuration
│   └── index.html           # HTML template
│
├── README.md                # This file
├── ARCHITECTURE.md          # Detailed system architecture
└── LICENSE                  # MIT License

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/AmazingFeature

3. Make your changes with clear, focused commits
4. Test thoroughly
5. Push to your branch

   git push origin feature/AmazingFeature

6. Open a Pull Request with a descriptive title

• Follow existing code style and conventions
• Add docstrings to functions explaining their purpose
• Test new features locally before submitting
• Keep commits atomic and well-documented
• Update README if adding new features

This project is licensed under the MIT License - see LICENSE file for details.

• Stable Diffusion XL - Model by Stability AI, licensed under OpenRAIL
• FastAPI - MIT License
• React - MIT License
• Vite - MIT License

• Stability AI for Stable Diffusion XL
• Hugging Face for model hosting and inference API
• FastAPI community for the amazing framework
• React & Vite communities for excellent tooling

• 📝 Issues: Report bugs and request features via GitHub Issues
• 💬 Discussions: Join conversations in GitHub Discussions
• 🐛 Bug Reports: Use the bug report template when creating issues
• ✨ Feature Requests: Describe the use case and expected behavior

• FastAPI Documentation
• React Documentation
• Stable Diffusion Guide
• Hugging Face API Docs

Future features under consideration:

• Image upscaling (4x resolution)
• Video generation support
• Fine-tuned model variants
• Persistent user preferences database
• Rate limiting and usage quotas
• Batch processing API
• WebSocket for real-time streaming
• User authentication system

Built with ❤️ by Dhruv Vashist

If you find this project useful, please consider giving it a ⭐ Star!

Last Updated: February 2026