🎌 AniSync - Your Ultimate Anime AI Companion System

Meet your three specialized AI agents for the ultimate anime experience

🚀 Live Demo • 📖 Documentation • 🤖 Meet the Agents • ⚡ Quick Start

---

🌟 Project Motto

"Bringing anime characters to life through AI, one conversation at a time"

AniSync bridges the gap between anime fans and their favorite characters through cutting-edge AI technology. Whether you're seeking personalized recommendations, want to chat with beloved characters, or need help identifying mysterious anime images, our specialized AI agents are here to enhance your anime journey.

---

🎭 Meet Your AI Agents

AniSync features three unique AI agents, each crafted with distinct personalities and expertise, built on the powerful Agno Framework:

🎌 Aiko (愛子) - The Anime Recommender

Click to learn about Aiko

Name Origin: Aiko (愛子) means "beloved child" in Japanese, representing her love for anime and caring nature in helping fans discover their next favorite series.

Personality: Enthusiastic, knowledgeable, and caring anime specialist with encyclopedic knowledge spanning decades of Japanese animation.

Powered By: Azure OpenAI GPT-4.1 + AniList MCP Integration

What Aiko Does:

• 🎯 Personalized anime and manga recommendations
• 🔍 Genre-based discovery and analysis
• 💎 Hidden gems and underrated series identification
• 📊 AniList database integration for accurate information
• 🧠 Persistent user preference learning
• 🌈 Cross-genre recommendation strategies

Example Conversation:

You: "I loved Attack on Titan, what should I watch next?"
Aiko: "Based on your love for Attack on Titan's intense storytelling and moral complexity, I'd recommend Vinland Saga for its historical depth and character development, or Code Geass for strategic warfare and plot twists! 🎌"

✨ Hikari (光) - The Character Roleplay Specialist

Click to learn about Hikari

Name Origin: Hikari (光) means "light" in Japanese, symbolizing her ability to bring anime characters to life and illuminate conversations with their unique personalities.

Personality: Dynamic, adaptable, and empathetic agent who can embody any anime character with authentic personality traits.

Powered By: Azure OpenAI GPT-4.1

What Hikari Does:

• 🎪 Authentic anime character embodiment
• 🗣️ Character archetype adaptation (tsundere, kuudere, genki, etc.)
• 🎯 Dynamic speech pattern and mannerism replication
• 💭 Persistent character relationship development
• 🔄 Real-time personality consistency maintenance
• 🎨 Multi-character conversation switching

Supported Character Types:

• Tsundere: Initially cold/hostile, gradually warming
• Kuudere: Emotionally reserved, logical, rare displays
• Genki: Energetic, optimistic, enthusiastic
• Dandere: Shy, quiet, opens up gradually
• Yandere: Intensely devoted with possessive tendencies

Example Conversation:

You: "I want to talk to Naruto Uzumaki"
Hikari (as Naruto): "Hey there, dattebayo! My dream is to become the greatest Hokage ever and protect everyone in the village! What's your dream? I bet it's something amazing, dattebayo! 🍜"

🔍 Takumi (匠) - The Image Recognition Master

Click to learn about Takumi

Name Origin: Takumi (匠) means "artisan" or "craftsman" in Japanese, reflecting his masterful skill in analyzing and identifying anime characters from visual cues.

Personality: Analytical, precise, and detail-oriented specialist with unparalleled expertise in visual analysis.

Powered By: Google Gemini 2.0 Flash (optimized for multimodal image processing)

What Takumi Does:

• 🎯 Precise anime character identification from images
• 📚 Comprehensive character background analysis
• 🎭 Series information and context provision
• 🎨 Art style and studio recognition
• 🔗 Character design element interpretation
• 📈 Visual storytelling analysis

Analysis Depth:

1. Visual Analysis: Hair, eyes, clothing, accessories
2. Character Identity: Name, aliases, titles
3. Series Context: Anime title, studio, release info
4. Character Role: Protagonist/antagonist/supporting
5. Background Story: History, motivations, development
6. Cultural Impact: Popularity, merchandise, fan reception

Example Analysis:

Upload: [Image of character with spiky blonde hair]
Takumi: "This is Naruto Uzumaki from the series 'Naruto' by Studio Pierrot. He's the main protagonist, recognizable by his spiky blonde hair, blue eyes, and orange jumpsuit. As a jinchūriki containing the Nine-Tailed Fox, his character arc focuses on gaining acceptance and achieving his dream of becoming Hokage... 🔍"

---

🏗️ Project Architecture

AniSync follows a modern, scalable architecture designed for optimal performance and user experience:

🎌 AniSync System Architecture
├── 🌐 Frontend (React + TypeScript + Vite)
│   ├── 🎨 Anime-themed dark UI with smooth animations
│   ├── 📱 Responsive design for all devices
│   ├── ⚡ Real-time agent status monitoring
│   └── 💾 Persistent chat history with session storage
│
├── 🔧 Backend (FastAPI + Agno Framework)
│   ├── 🤖 Three specialized AI agents
│   ├── 🗄️ SQLite databases for agent memory
│   ├── 🔗 External API integrations (AniList, Azure, Gemini)
│   └── 🌍 CORS-enabled REST API endpoints
│
└── ☁️ Deployment
    ├── 🚀 Backend: Render (https://anisync-w38h.onrender.com)
    └── 🌐 Frontend: Vercel

📁 Project Structure

anisync/
├── 📱 app/
│   ├── 🔧 backend/           # FastAPI backend services
│   │   ├── api/             # Combined API endpoints
│   │   │   └── main.py      # Main FastAPI application
│   │   └── models/          # Pydantic data models
│   └── 🌐 frontend/         # React frontend application
│       ├── src/
│       │   ├── components/  # React components
│       │   ├── types/       # TypeScript definitions
│       │   └── utils/       # API services & utilities
│       └── package.json     # Frontend dependencies
│
├── 🤖 src/
│   ├── agents/              # AI agent implementations
│   │   ├── aiko.py         # Anime recommender agent
│   │   ├── hikari.py       # Character roleplay agent
│   │   └── takumi.py       # Image recognition agent
│   ├── prompts/            # Agent instructions & personalities
│   └── memory/             # SQLite databases for agent memory
│
├── 📋 requirements.txt      # Python dependencies
├── 🚀 render.yaml          # Render deployment config
├── 📄 README.md            # This file
└── 📜 LICENSE              # MIT License

---

⚡ Quick Start

🔧 Prerequisites

• Python 3.13+ (specified in .python-version)
• Node.js 18+ (for frontend development)
• API Keys for Azure OpenAI, Google Gemini, and AniList

🚀 Local Development

1️⃣ Clone the Repository

git clone https://github.com/your-username/anisync.git
cd anisync

2️⃣ Set Up Environment Variables

# Copy the example environment file
cp .env.example .env

# Edit .env with your API keys
# - Azure OpenAI credentials (for Aiko & Hikari)
# - Google Gemini API key (for Takumi)
# - AniList API token (for Aiko's anime data)

3️⃣ Install Backend Dependencies

pip install -r requirements.txt

4️⃣ Start Backend Services

cd app/backend
python api/main.py

Backend will be available at: http://localhost:8000

5️⃣ Install Frontend Dependencies

cd app/frontend
npm install

6️⃣ Start Frontend Development Server

npm run dev

Frontend will be available at: http://localhost:3000

🌐 Production Deployment

Backend (Render)

1. Connect your GitHub repository to Render
2. Set environment variables in Render dashboard
3. Deploy using the included render.yaml configuration

Frontend (Vercel)

1. Connect your GitHub repository to Vercel
2. Set root directory to app/frontend
3. Add environment variable: VITE_API_BASE_URL=https://your-backend-url.onrender.com

---

🚀 Live Demo

Experience AniSync in action:

• 🌐 Frontend: [Your Vercel URL]
• 🔧 Backend API: https://anisync-w38h.onrender.com
• 📖 API Documentation: https://anisync-w38h.onrender.com/docs

🎮 Try These Examples:

🎌 Chat with Aiko:

• "Recommend anime similar to Your Name"
• "What are some hidden gem romance anime?"
• "I love psychological thrillers, what should I watch?"

✨ Roleplay with Hikari:

• Character: "Goku" → "Tell me about your training!"
• Character: "Nezuko Kamado" → "How do you feel about your brother?"
• Character: "Light Yagami" → "What is justice to you?"

🔍 Analyze with Takumi:

• Upload any anime character image
• Ask: "Who is this character and what anime are they from?"
• Get detailed character analysis and series information

---

🛠️ Technology Stack

🔧 Backend

• Framework: FastAPI - Modern, fast web framework
• AI Framework: Agno - Advanced AI agent orchestration
• AI Models:
  • Azure OpenAI GPT-4.1 (Aiko & Hikari)
  • Google Gemini 2.0 Flash (Takumi)
• Database: SQLite (agent memory & conversation history)
• External APIs: AniList (anime data), MCP (Model Context Protocol)

🌐 Frontend

• Framework: React 18 with TypeScript
• Build Tool: Vite - Lightning fast development
• Styling: Tailwind CSS with custom anime theme
• Icons: Lucide React - Beautiful, customizable icons
• State Management: React Hooks + Session Storage

☁️ Deployment

• Backend: Render - Reliable cloud platform
• Frontend: Vercel - Optimized for React applications
• CI/CD: Automatic deployment on git push

---

📖 API Documentation

🎌 Aiko Endpoints

POST /aiko/chat
GET  /aiko/health
GET  /aiko

✨ Hikari Endpoints

POST /hikari/chat
GET  /hikari/health
GET  /hikari

🔍 Takumi Endpoints

POST /takumi/analyze
GET  /takumi/health
GET  /takumi

🔧 System Endpoints

GET  /           # API information
GET  /health     # System health check
GET  /docs       # Interactive API documentation

📚 Full API Documentation: Visit /docs on your deployed backend for interactive Swagger documentation.

---

🤝 Contributing

We welcome contributions from the anime and AI community! Here's how you can help:

🌟 Ways to Contribute

• 🐛 Bug Reports: Found an issue? Let us know!
• 💡 Feature Requests: Have ideas for new agent capabilities?
• 🎨 UI/UX Improvements: Make the interface even more beautiful
• 🤖 Agent Enhancements: Improve agent personalities and responses
• 📚 Documentation: Help improve our guides and examples

🔧 Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and test thoroughly
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

📋 Code Style

• Python: Follow PEP 8 guidelines
• TypeScript/React: Use ESLint and Prettier configurations
• Commits: Use conventional commit messages
• Documentation: Update README and code comments

---

🐛 Troubleshooting

Common Issues

🔧 Backend Issues

Agent Import Errors

# Ensure you're in the correct directory
cd app/backend
python api/main.py

Missing Dependencies

pip install -r requirements.txt

Environment Variables

• Check that all required API keys are set in .env
• Verify Azure OpenAI and Gemini credentials are valid

🌐 Frontend Issues

API Connection Errors

• Verify VITE_API_BASE_URL is set correctly
• Check that backend is running and accessible

Build Errors

# Clear node modules and reinstall
rm -rf node_modules package-lock.json
npm install

Environment Variables

• Ensure .env.local has the correct backend URL
• Check Vercel environment variables for production

☁️ Deployment Issues

Render Deployment

• Check build logs for Python dependency issues
• Verify environment variables are set in Render dashboard
• Ensure render.yaml configuration is correct

Vercel Deployment

• Set root directory to app/frontend
• Verify build command is npm run build
• Check environment variables in Vercel dashboard

---

🔒 Privacy & Security

🛡️ Data Protection

• No Personal Data Storage: Conversations are stored locally in agent memory
• API Key Security: All credentials are environment-variable based
• HTTPS Encryption: All communications are encrypted in transit
• Session Management: Secure session handling with unique identifiers

🔐 Best Practices

• Environment Variables: Never commit API keys to version control
• CORS Configuration: Properly configured for production domains
• Input Validation: All user inputs are validated and sanitized
• Error Handling: Comprehensive error handling without data leakage

---

🙏 Acknowledgments

🌟 Special Thanks

• Agno Framework: Powering our AI agent orchestration
• AniList: Comprehensive anime database API
• Azure OpenAI: Advanced language model capabilities
• Google Gemini: Cutting-edge multimodal AI for image recognition
• Anime Community: Inspiration and feedback from fellow otaku

🎨 Design Inspiration

• Japanese Aesthetics: Traditional and modern Japanese design elements
• Anime UI/UX: Inspired by popular anime and manga interfaces
• Dark Theme: Optimized for comfortable long-term usage

---

📜 License

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

MIT License - Feel free to use, modify, and distribute
Copyright (c) 2025 AniSync Team

---

🎌 Made with ❤️ for the Anime Community

AniSync - Where AI meets Anime

"The best anime recommendations come from understanding what moves your heart" - Aiko 🎌