Hachimi

Hachimi is an Agent-First Roleplay Chatbot that goes beyond traditional chat interfaces. Unlike conventional ChatGPT-like experience, Hachimi treats AI agents as first-class concepts, enabling sophisticated multi-agent storytelling and roleplay experiences.

🎭 Core Concept: Agent-First Architecture

Hachimi defines three distinct types of agents, each with specialized responsibilities:

Character Agents

• Role: Embody individual character personas and states
• Tool: talk — generates in-character dialogue based on the character's identity, relationships, and current story context
• Context: Receives character-specific information including appearance, personality, abilities, background, and relationship rules

Plot Agents

• Role: Manage and update story progression
• Tool: update_story — executes story state modifications as command objects
• Operations: Add future plots, add/replace/delete current plots, update plot settings
• Triggers: Called periodically or when the Oracle determines a plot update is needed

Oracle Agents

• Role: High-level story direction and content generation
• Tools:
  • create_character_from_description — generates fully detailed character profiles from text descriptions
  • create_world_setting_from_description — generates complete world settings from descriptions
  • decide_plot_update — analyzes conversations and determines if plot updates are warranted
  • give_title — generates session titles based on conversation content

All agent tool calls yield Pydantic model command objects, enabling type-safe execution of story modifications.

🏗️ Architecture

Hachimi/
├── hachimi-server/          # Python/FastAPI backend
│   └── src/
│       ├── domain/          # Core domain models (StoryState, ChatSession, Message)
│       ├── application/     # Business logic (Agents, Services, Commands)
│       ├── infrastructure/  # External integrations (Google AI, SQLite, Caching)
│       └── interface_adapters/  # HTTP controllers
│
└── hachimi-client/          # React/TypeScript frontend
    └── src/
        ├── features/        # Feature modules (dashboard, session, create-world)
        ├── routes/          # TanStack Router file-based routes
        └── client/          # Auto-generated API client

Technology Stack

Backend:

• Python 3.12+
• FastAPI for REST API
• Google Gemini AI (2.5 Pro & Flash models)
• Pydantic for data validation and structured outputs
• SQLAlchemy with SQLite for persistence
• Clean Architecture pattern

Frontend:

• React 19 with TypeScript
• TanStack Router (file-based routing)
• TanStack Query for server state management
• Tailwind CSS for styling
• Auto-generated API client from OpenAPI spec

📦 Features

• Multi-Agent Roleplay: Characters maintain individual personalities, memories, and interaction rules
• Dynamic Plot Management: Three-tier plot system (past events, current situation, future hooks)
• World Building: Detailed world settings with locations, rules, and atmosphere
• Branching Conversations: Tree-structured message history supports story branching
• Intelligent Plot Updates: Oracle analyzes conversations for significant developments
• AI-Powered Content Generation: Create characters and worlds from natural language descriptions
• Session Management: Multiple concurrent roleplay sessions with persistence

🚀 Getting Started

Docker Deployment (Recommended)

The fastest way to get Hachimi running:

1. Clone and configure:

   git clone <repository-url>
   cd Hachimi
   cp docker.env.example .env

2. Set your API key in .env:

   GOOGLE_API_KEY=your_google_ai_api_key_here

3. Build and run:

   docker compose up --build

4. Access the application:

   • Frontend: http://localhost:80
   • Backend API: http://localhost:8000
   • API Docs: http://localhost:8000/docs

For production deployment with a public URL:

VITE_API_BASE_URL=https://api.yourdomain.com docker compose up --build -d

Local Development

Prerequisites

• Python 3.12+
• Node.js 18+
• uv (Python package manager)
• A Google AI API key

Server Setup

1. Navigate to the server directory:

   cd hachimi-server

2. Install dependencies:

   uv sync

3. Create a .env file with your API key:

   GOOGLE_API_KEY=your_google_ai_api_key_here

4. Start the development server:

   uv run fastapi dev src/main.py

   The API will be available at http://localhost:8000 with:

   • Swagger docs: http://localhost:8000/docs
   • ReDoc: http://localhost:8000/redoc

Client Setup

1. Navigate to the client directory:

   cd hachimi-client

2. Install dependencies:

   npm install

3. Create a .env file:

   VITE_API_BASE_URL=http://localhost:8000

4. Start the development server:

   npm run dev

   The frontend will be available at http://localhost:5173

Regenerating the API Client

When the server API changes, regenerate the TypeScript client:

cd hachimi-client
npm run generate-client

This script will:

1. Start the FastAPI server
2. Fetch the OpenAPI specification
3. Generate TypeScript types and SDK

📖 Story Configuration

Stories are configured with a rich state model:

StoryState {
  roleplay_config: { main_characters, user_character }
  world_setting: { basic_scenario, main_locations[] }
  characters[]: { name, gender, age, identity, appearance, 
                  personality, abilities, background, address_rules }
  core_story: string
  plot_settings: string[]      // Long-term facts about the world
  past_plot: Event[]           // Completed story events
  future_plots: string[]       // Planned future events
  current_plots: string[]      // Currently active situations
  special_notes: string[]      // Writer's notes and rules
}

See hachimi-server/src/story_config.toml for a complete example configuration.

🔧 Development

Project Structure

Server Domain Models:

• StoryState — Complete story configuration and state
• ChatSession — Session with tree-structured messages
• Character — Detailed character profiles
• WorldSetting — World configuration with locations

Server Services:

• StoryProgressionService — Manages chat sessions and character interactions
• StoryCreationService — AI-powered character and world generation

Client Routes:

• / — Dashboard with session list
• /sessions/$sessionId — Active roleplay session
• /create-world — World and character creation wizard

Code Style

Server: Python with Ruff formatting (line length 120)

Client: TypeScript with Prettier (tabs, width 4)

npm run format      # Format code
npm run lint        # Run ESLint

Docker Architecture

Hachimi/
├── docker-compose.yml          # Orchestration for both services
├── docker.env.example          # Environment template
├── hachimi-server/
│   ├── Dockerfile              # Multi-stage Python build with uv
│   └── .dockerignore
└── hachimi-client/
    ├── Dockerfile              # Multi-stage Node.js build → Nginx
    ├── nginx.conf              # SPA routing & compression
    └── .dockerignore

Services:

• hachimi-server — FastAPI backend on port 8000
• hachimi-client — Nginx serving React SPA on port 80

Volumes:

• hachimi-data — Persists SQLite database

Useful commands:

docker compose up --build       # Build and start
docker compose up -d            # Run in background
docker compose down             # Stop services
docker compose logs -f          # Follow logs
docker volume rm hachimi-data   # Reset database