AGENTS.md · Intelligent-Internet/ii-agent

Sections

1. Quick Start
2. Repository Map
3. Mandatory Rules
4. Architecture
5. Where to Look
6. Development Workflow
7. Key Commands

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

# II-Agent Contributor Guide

This file is the entry point for agents working in this repository. It provides the architecture overview plus a map to deeper documentation.

**Read `CLAUDE.md` for the full development reference** (patterns, billing system, dependency injection, code examples).

## Quick Start

```bash
uv sync --frozen          # Install dependencies
./scripts/start.sh        # Start the server
curl localhost:8000/health # Verify
```

## Repository Map

| Resource | What it covers |
|----------|---------------|
| [`CLAUDE.md`](CLAUDE.md) | Full development guide: patterns, billing, dependency injection, code examples |
| [`docs/DESIGN.md`](docs/DESIGN.md) | Design patterns: service pattern, Dep aliases, domain module structure |
| [`docs/PLANS.md`](docs/PLANS.md) | How to write and maintain execution plans |
| [`docs/RELIABILITY.md`](docs/RELIABILITY.md) | Billing reliability, cron recovery, Redis fallbacks |
| [`docs/SECURITY.md`](docs/SECURITY.md) | Auth flow (OAuth, JWT, API keys), secrets management |
| [`docs/FRONTEND.md`](docs/FRONTEND.md) | Socket.IO events, REST API surface, real-time event flow |
| [`docs/PRODUCT_SENSE.md`](docs/PRODUCT_SENSE.md) | Product principles, user personas, key journeys |
| [`docs/QUALITY_SCORE.md`](docs/QUALITY_SCORE.md) | Per-domain quality grades and health metrics |
| [`docs/design-docs/`](docs/design-docs/index.md) | Indexed design decisions with verification status |
| [`docs/exec-plans/`](docs/exec-plans/) | Active and completed execution plans |
| [`docs/generated/db-schema.md`](docs/generated/db-schema.md) | Database schema reference (from SQLAlchemy models) |
| [`docs/product-specs/`](docs/product-specs/index.md) | Product specifications |
| [`docs/references/`](docs/references/) | LLM-optimized reference material for key dependencies |

## Mandatory Rules

1. **Use `uv run`** for all Python commands (`uv run pytest`, `uv run python ...`).
2. **Run Ruff only on the Python files you changed** before marking work complete (`uv run ruff check --fix-only <changed_python_files>`, `uv run ruff format <changed_python_files>`, `uv run ruff check <changed_python_files>`, `uv run ruff format --check <changed_python_files>`). If you changed no Python files, skip Ruff.
3. **Never call `CreditService.deduct()` directly** for LLM/tool billing — use the reservation system (see `CLAUDE.md` Billing section).
4. **Use Dep aliases everywhere** — never bare `= Depends(get_x)` in function signatures (see `CLAUDE.md` Dependency Injection Pattern).
5. **Use `LLMExecutionService`** for any new code that calls an LLM outside the agent runtime loop.

## Architecture

### Domain Map

II-Agent is organized into domain modules under `src/ii_agent/`. Each domain owns its models, repository, service, dependencies, router, and schemas.

```text
src/ii_agent/
├── app/                    # FastAPI bootstrap package, middleware, lifespan, router wiring
│
├── core/                   # Shared infrastructure (no business logic)
│   ├── config/             # Pydantic settings (database, redis, storage, oauth, stripe)
│   ├── db/                 # SQLAlchemy 2.0 base, async session management, migrations
│   ├── llm/                # LLM billing service, execution service, base client
│   ├── redis/              # Redis client, cache, pubsub, lock, cancel management
│   ├── secrets/            # GCP Secret Manager integration
│   ├── storage/            # File storage abstraction (GCS, local)
│   ├── container.py        # ServiceContainer for complex dependency graphs
│   └── dependencies.py     # DBSession, SettingsDep (shared Dep aliases)
│
├── auth/                   # Authentication & authorization
│   ├── jwt_handler.py      # JWT creation/verification (HS256)
│   ├── oidc_verify.py      # OIDC token verification (RS/ES families)
│   ├── api_key_utils.py    # API key generation
│   └── users/              # User profiles, CRUD, waitlist
│
├── billing/                # Credit ledger & billing
│   ├── credits/            # Balance, ledger, pricing, service
│   ├── reservations/       # Reserve -> settle -> release state machine
│   ├── usage/              # Usage records, LLM/tool invocation telemetry
│   ├── customers/          # Stripe customer management
│   └── webhook_handler.py  # Stripe webhook processing
│
├── sessions/               # Chat session management
│   ├── models.py           # Session model, SessionStateEnum, AppKind
│   ├── service.py          # Session CRUD, state transitions
│   ├── fork_service.py     # Session forking
│   ├── title_service.py    # Auto-title generation
│   ├── wishlist/           # Session bookmarks
│   └── pin/                # Pinned sessions
│
├── agent/                  # Agent execution framework
│   ├── application/        # Validation, execution orchestration
│   ├── runtime/            # Agent runtime models, streaming
│   ├── runs/               # Agent run task management
│   ├── events/             # Event handling & logging
│   ├── prompts/            # System prompts & templates
│   ├── sandboxes/          # E2B sandbox management
│   ├── socket/             # Socket.IO command handlers (query, cancel, plan)
│   └── subscribers/        # Event subscribers (metrics, database)
│
├── chat/                   # Chat API & LLM providers
│   ├── api/                # Chat REST endpoints
│   ├── llm/                # LLM provider implementations (Anthropic)
│   ├── media/              # Media processing (image gen, video gen, web search)
│   ├── runs/               # Chat run management
│   ├── tools/              # Chat tools (code interpreter, tool registry)
│   └── vectorstore/        # Vector store integration (OpenAI)
│
├── content/                # Content generation
│   ├── media/              # Media templates, tools, config
│   ├── skills/             # Custom skills management
│   ├── slides/             # Slide/presentation generation + templates + design
│   └── storybook/          # Storybook generation
│
├── files/                  # File upload/download service
│
├── integrations/           # External integrations
│   ├── a2a/                # Agent-to-Agent protocol
│   ├── connectors/         # External connectors (GitHub, Google Drive via Composio)
│   ├── enhance_prompt/     # Prompt enhancement
│   └── mobile/             # Mobile platform integrations (Apple, future Android)
│
├── projects/               # Project & deployment management
│   ├── cloud_run/          # Google Cloud Run deployment
│   ├── databases/          # Database provisioning
│   ├── deployments/        # Deployment orchestration
│   ├── design/             # Project design
│   ├── secrets/            # Project-level secrets
│   └── subdomains/         # Subdomain management
│
├── settings/               # User settings
│   ├── llm/                # User LLM model preferences
│   └── mcp/                # MCP server configuration
│
├── utils/                  # Shared utilities
├── workers/                # Background jobs (Celery cron)
├── scripts/                # Admin scripts
└── ws_server.py            # WebSocket server entry point
```

### Layer Architecture

Within each domain, code follows a fixed layer hierarchy. Dependencies flow downward only.

```text
    Router (FastAPI endpoints)
      |
    Dependencies (Dep aliases, factory functions)
      |
    Service (business logic, takes db: AsyncSession)
      |
    Repository (data access, SQLAlchemy queries)
      |
    Models (SQLAlchemy 2.0 declarative models)
      |
    Schemas (Pydantic DTOs for request/response)
```

### Layer Rules

- **Models** may only import from `core.db` and standard library.
- **Repository** imports models and core utilities. Never imports services.
- **Service** imports repository and models. May import other services' Dep aliases for cross-domain work.
- **Dependencies** defines factory functions and Dep aliases. Imports services and repositories.
- **Router** imports Dep aliases from dependencies. Never imports repositories directly.
- **Schemas** are pure Pydantic models. No database or service imports.

### Cross-Cutting Concerns