Skip to content

README.md

Latest commit

 

History

History
287 lines (220 loc) · 9.5 KB

README.md

File metadata and controls

287 lines (220 loc) · 9.5 KB

AI Character Chat Application

A role-playing chat application built with Next.js, TypeScript, Redux for the frontend and Django with Celery for the backend. The application uses Gemini 2.5 Flash API for AI responses and PostgreSQL for data storage.

Features

  • Two-column layout with chat window and character settings
  • Real-time chat with AI character
  • Character customization (name, description, personality, appearance)
  • Chat history stored in PostgreSQL database
  • Responsive design for mobile and desktop

Tech Stack

Frontend

  • Next.js 14 with TypeScript
  • Redux Toolkit for state management
  • Tailwind CSS for styling
  • Hybrid (REST for Chat Stream + GraphQL for Data Management)

Backend

  • Django 5.2 with Django REST Framework
  • PostgreSQL database
  • Celery for background tasks
  • Redis as message broker

Ecosystem & Related Repositories

This project is the core platform of a larger GenAI ecosystem. To ensure modularity and quality, specific components were decoupled:

End-to-End GenAI Character Platform (R&D MVP)

PROJECT STATUS: EXPERIMENTAL / WIP

This repository serves as an Architecture Proof-of-Concept for an end-to-end Generative AI platform. It focuses on System Design patterns (Microservices, Event-Driven Architecture) and Data Pipeline Validation, demonstrating how to decouple high-latency inference tasks from the main application loop.

Please view this as an Architecture Proof-of-Concept rather than production-ready code.

Engineering Decisions & Roadmap

I am currently refactoring several core components. If you run the code, please be aware of the following known limitations:

  • First-Turn UX (In Progress):

    • Issue: Currently, the initial role-play instruction is sent as a user message.
    • Roadmap: I am refactoring this to move instructions to the System Prompt layer and implementing a "Proactive Greeting" pattern to initiate the chat flow smoothly.

  • Context Management (V1):

    • Issue: The current version uses a simple "Structured Data Injection" for character personas.
    • Roadmap: V2 is designed to integrate a Vector Database (RAG) to handle long-term dynamic memory and overcome token limits.

  • Concurrency & Async Strategy:

    • Constraint: The system currently defaults to **Synchronous Execution (Direct Invocation).
    • Reasoning: The LLM provider (Gemini API Free Tier) enforces strict RPM quotas. Running tasks asynchronously triggered 429 errors. I am using synchronous execution as a natural Throttling Mechanism for this MVP.
    • Running Celery asynchronously triggered immediate HTTP 429 (Too Many Requests) errors from Gemini. I am using synchronous execution as a natural Throttling Mechanism to stay within API limits without implementing complex token-bucket rate limiters for this MVP.

Environment Security

This project uses environment templates to protect sensitive information:

  • backend/.env.template - Template for backend environment variables
  • frontend/.env.local.template - Template for frontend environment variables

Important Security Note:

  • Never commit actual environment files (.env, .env.local) to version control
  • Only commit the template files (.env.template, .env.local.template)
  • Copy templates to actual environment files and fill in your values: 
    # Backend
cp backend/.env.template backend/.env

# Frontend
cp frontend/.env.local.template frontend/.env.local

The project includes .gitignore files to prevent accidental commits of sensitive environment files.

Setup Instructions

Prerequisites

  • Node.js 18+
  • Python 3.10+
  • PostgreSQL
  • Redis
  • Google AI API key for Gemini 2.5 Pro

Docker Setup (Optional)

This project includes Docker support for easy deployment of Redis and other services. To use Docker:

  1. Start Redis using Docker

    docker-compose up -d redis

    This command will:

    • Pull the latest Redis Docker image
    • Start the Redis container named 'redis-server'
    • Map port 6379 from the container to your local machine
    • Configure the container to automatically restart unless stopped
    • Make Redis available at redis://localhost:6379/0

  2. Verify Redis is running

    docker ps

  3. Restart Redis if needed

    docker-compose restart redis

  4. Stop Redis

    docker-compose stop redis

Note: The docker-compose.yml file is already configured with Redis settings. You can customize the Redis configuration by modifying the docker-compose.yml file.

Redis Configuration

Backend Setup

  1. Navigate to the backend directory

    cd backend

  2. Create and activate a virtual environment

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install dependencies

    pip install -r requirements.txt

  4. Set up PostgreSQL database

    • Create a PostgreSQL database named ai_character_chat (Make sure your PostgreSQL server is running)

  5. Set up environment variables Copy the template file and create your .env file:

    cp backend/.env.template backend/.env

    Edit the backend/.env file with your actual values:

    SECRET_KEY=your-django-secret-key-here
DEBUG=True
GEMINI_API_KEY=your-gemini-api-key-here
DATABASE_URL=postgresql://user:password@localhost:5432/ai_character_chat
REDIS_URL=redis://localhost:6379/0

    Important: Never commit your actual .env file to version control. Only the template file .env.template should be committed.

  6. Run database migrations

    python manage.py migrate

  7. Create and apply chat app migrations

    python manage.py makemigrations chat
python manage.py migrate chat

  8. Verify all migrations are complete

    python manage.py showmigrations

  9. Create a superuser (optional)

    python manage.py createsuperuser

  10. Start the Django development server

    python manage.py runserver

Note: The backend server will be available at http://127.0.0.1:8000/ once started. All migrations should be applied without errors for the application to function properly.

  1. Start Celery worker (in a separate terminal) 
    celery -A ai_character_chat worker --loglevel=info

Frontend Setup

  1. Navigate to the frontend directory

    cd frontend

  2. Install dependencies

    npm install

  3. Set up environment variables Copy the template file and create your .env.local file:

    cp frontend/.env.local.template frontend/.env.local

    Edit the frontend/.env.local file with your actual values:

    NEXT_PUBLIC_API_URL=http://localhost:8000/api

    Important: Never commit your actual .env.local file to version control. Only the template file .env.local.template should be committed.

  4. Start the development server

    npm run dev

Usage

  1. Open your browser and navigate to http://localhost:3000
  2. Click on "Character Settings" to customize your AI character
  3. Start chatting with your character in the chat window
  4. Your conversations are automatically saved to the database

API Endpoints

Characters

  • GET /api/characters - List all characters
  • POST /api/characters - Create a new character
  • GET /api/characters/{id} - Get character details
  • PUT /api/characters/{id} - Update character

Chat Sessions

  • GET /api/sessions - List chat sessions
  • POST /api/sessions - Create a new chat session
  • GET /api/sessions/{id} - Get session details

Messages

  • GET /api/messages?chat_session_id={id} - Get messages for a session
  • POST /api/chat/send_message - Send a message and get AI response

Project Structure

AICharacterChat/
├── backend/                 # Django backend
│   ├── ai_character_chat/   # Django project settings
│   ├── chat/               # Chat app
│   │   ├── models.py       # Database models
│   │   ├── views.py        # API views
│   │   ├── serializers.py  # DRF serializers
│   │   └── tasks.py        # Celery tasks
│   └── requirements.txt    # Python dependencies
├── frontend/               # Next.js frontend
│   ├── src/
│   │   ├── app/           # Next.js app directory
│   │   ├── components/    # React components
│   │   ├── store/         # Redux store
│   │   ├── types/         # TypeScript types
│   │   └── utils/         # Utility functions
│   └── package.json       # Node.js dependencies
└── README.md

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

This project is licensed under the MIT License.