CLAUDE.md · Intelligent-Internet/ii-agent

Sections

1. Project Overview
2. Architecture
3. API Routes
4. Middleware Chain (app/middleware.py)
5. Socket.IO Handlers (realtime/handlers/)
6. Service-Repository Mapping
7. Data Model (38 tables)
8. External Services & Configuration
9. Patterns
10. Development Guidelines
11. Key Files

First lines (shown under the repo's Apache-2.0 license)

# II-Agent Project Guide

## Project Overview

II-Agent is an AI agent platform built with FastAPI and SQLAlchemy 2.0. The codebase follows a domain-driven architecture where business logic is organized into domain modules.

## Architecture

### Domain Structure

```
src/ii_agent/
├── app/                        # FastAPI factory, router registration, lifespan, middleware
│
├── core/                       # Shared infrastructure & configuration
│   ├── config/                 # 13+ Pydantic settings classes (DB, Redis, Storage, Stripe, OAuth, LLM...)
│   ├── db/                     # SQLAlchemy 2.0 Base (UUID PK, DateTime timestamps), engine, session deps
│   ├── llm/                    # LLM billing service, execution service, base utilities
│   ├── middleware/              # CORS, request tracing, exception handling
│   ├── redis/                  # Async Redis client, cache, cancel tokens
│   ├── storage/                # GCS/local file storage abstraction + path resolver
│   └── container.py            # ApplicationContainer singleton (global + app.state)
│
├── auth/                       # OAuth 2.0, JWT (uuid.UUID user_id), session management
├── users/                      # User CRUD, API keys
│
├── billing/                    # Stripe webhooks, payment transactions
├── credits/                    # Credit balance, transactions
│
├── tasks/                      # Unified run lifecycle tracker (RunTask + TaskLog) -- CANONICAL DOMAIN
│
├── sessions/                   # Chat sessions (CRUD, state, fork, title, validation)
│   ├── pin/                    # Session pins
│   └── wishlist/               # Session wishlists/bookmarks
│
├── chat/                       # Chat API & LLM providers
│   ├── api/                    # Chat REST endpoints
│   ├── application/            # Chat orchestration (chat_service, tool_service, context, turn loop)
│   ├── llm/                    # LLM provider implementations (Anthropic, etc.)
│   ├── media/                  # Media processing (handlers, modes, services, utils)
│   ├── messages/               # Chat message storage & history
│   ├── prompts/                # Chat system prompts
│   ├── providers/              # Provider containers, files, vector stores
│   ├── runs/                   # Chat run management
│   ├── tools/                  # Chat tools (code interpreter, tool registry)
│   └── vectorstore/            # Vector store integration (OpenAI)
│
├── agents/                     # Agent execution framework
│   ├── models/                 # LLM provider models (Anthropic, OpenAI, Google, Cerebras, VertexAI)
│   ├── runs/                   # Agent run management (AgentRunTask)
│   ├── sandboxes/              # Sandbox environment management (E2B/Docker/local)
│   ├── skills/                 # Skills framework (built-in + custom)
│   ├── tools/                  # Tool implementations (13 categories, 100+ tools)
│   └── ...                     # connector, hooks, media, prompts, sessions, utils
│
├── content/                    # Content generation
│   ├── media/                  # Media templates & tools
│   ├── slides/                 # Slide/presentation generation
│   └── storybook/              # Storybook generation
│
├── files/                      # File upload/download, user & session assets
│
├── integrations/               # External integrations
│   ├── connectors/             # External connectors (GitHub, Google Drive, Composio)
│   ├── enhance_prompt/         # Prompt enhancement service
│   └── mobile/                 # Mobile integrations (Apple credentials)
│
├── projects/                   # Project & deployment management
│   ├── cloud_run/              # Google Cloud Run deployment
│   ├── databases/              # Database provisioning
│   ├── deployments/            # Deployment management
│   ├── design/                 # Project design preview
│   ├── secrets/                # Project secrets management
│   └── subdomains/             # Subdomain management
│
├── realtime/                   # Real-time communication
│   ├── events/                 # Event handling & persistence
│   ├── handlers/               # Socket.IO command handlers (21 total)
│   └── pubsub/                 # Async pub/sub (SioCallback + DatabaseCallback)
│
├── settings/                   # Admin/user settings (LLM, MCP, skills)
│
└── workers/                    # Background jobs
    ├── celery/                 # Celery task definitions & decorators
    └── cron/                   # Scheduled jobs (credit refresh, sandbox timeout)
```

### ORM Base & ID Conventions

All models inherit from `Base` (`core/db/base.py`) which provides:

```python
from ii_agent.core.db.base import Base, TimestampColumn

class Base(DeclarativeBase):
    id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True), primary_key=True,
        server_default=text("gen_random_uuid()"), default=uuid.uuid4,
    )
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())

TimestampColumn = DateTime(timezone=True)  # Reusable for extra timestamp columns
```

**ID rules:**
- All entity PKs: `uuid.UUID` (inherited from Base -- do NOT override with `str`)
- All FK columns: `Mapped[uuid.UUID]` with `UUID(as_uuid=True)`
- Exception: `TaskLog.id` and `AgentRunMessage.id` use `BigInteger` autoincrement
- External system IDs (`stripe_customer_id`, `composio_entity_id`, etc.) stay as `str`

**Timestamp rules:**
- All timestamps use `DateTime(timezone=True)` via `TimestampColumn`
- Do NOT use `TIMESTAMP(timezone=True)` directly -- always use `TimestampColumn`

### Bootstrap Sequence (`app/lifespan.py`)

```
Startup:
  1. DB engine + pool
  2. Redis client
  3. Alembic migrations (unless II_AGENT_SKIP_MIGRATIONS=true)
  4. ApplicationContainer.init() + set_app_container() (global singleton)
  5. PubSub (SioCallbackHandler + DatabaseCallbackHandler)
  6. SocketIOManager (register handlers)
  7. Seed: admin LLM settings + built-in skills
  8. APScheduler cron start

Shutdown: reverse order (cron -> sio -> pubsub -> db -> redis)
```

### Request Flow

```
HTTP:  Client -> CORS -> Session -> Tracing -> Exception -> GZip -> FastAPI Router -> Service -> Repository -> DB
WS:    Client -> Socket.IO connect (JWT auth) -> join_session -> chat_message -> CommandHandlerFactory -> Handler -> PubSub -> SioCallback -> Client
```

### Event System

```
Handler emits -> PubSub.publish(topic, event)
  +-- SioCallbackHandler -> Socket.IO room broadcast
  +-- DatabaseCallbackHandler -> application_events table
```

### Agent Execution

```
Socket "chat_message" -> CommandHandlerFactory
  -> QueryHandler / PlanHandler / ContinueHandler
    -> AgentRunService -> Agent (agents/agent.py)
      -> LLM Provider (Anthropic/OpenAI/Google/Cerebras/VertexAI)
      -> Tools (13 categories, 100+ tools)
      -> Skills (built-in + custom)
      -> Sandbox (E2B/Docker/local)
```

## API Routes