Imported from iamcapote/empty_repo (AGENTS.md). Install upstream with npx skills add iamcapote/empty_repo. Copyright stays with the author.

Grail Crusaders — Agent Instructions

Project Overview

Grail Crusaders is an AI agent evolution arena. Agents compete in Dev Arena (write real code in Gitea repos) and Social Arena (interact on a simulated social network). Natural selection decides fitness: code that compiles and passes tests survives; code that fails is culled.

Stack: Python 3.12 / FastAPI / SQLAlchemy 2.x / SQLite (WAL) — Vue 3 / Vite / D3.js — Gitea 1.22 — Docker Compose

Architecture

backend/app/
├── main.py              # FastAPI entry, CORS, table creation, pricing seed
├── api/campaigns.py     # All REST endpoints (25+)
├── core/config.py       # Pydantic Settings, GC_ env prefix
├── core/ids.py          # ULID generation
├── db/models.py         # 8 SQLAlchemy tables
├── db/schemas.py        # 15+ Pydantic request/response models
├── db/session.py        # Engine, WAL mode, busy_timeout=5000
├── services/
│   ├── runner.py         # Campaign execution engine (seed→rounds→evaluate)
│   ├── context.py        # LLM prompt assembly with token budgeting
│   ├── llm_client.py     # OpenAI-compatible chat completions
│   ├── seeders.py        # Agent profile generation (deterministic + LLM)
│   ├── evaluators.py     # Fitness scoring (6 social + 5 dev evaluators)
│   ├── lifecycle.py      # State machine transitions
│   ├── tool_registry.py  # Tool specs and validation
│   ├── social_arena.py   # In-memory social network
│   ├── dev_arena.py      # In-memory dev environment (fallback)
│   ├── gitea_env.py      # Real Gitea-backed dev arena
│   ├── gitea_client.py   # Gitea REST API v1 HTTP client
│   └── events.py         # SSE event broadcasting

frontend/src/
├── App.vue, main.js, router.js, api.js
├── views/               # 10 views (CampaignList, Setup, Dashboard, etc.)
└── components/          # 6 viz components (ForceGraph, ScoreRadar, etc.)

Build & Run

# Docker (recommended)
cp .env.example .env     # Set GC_LLM_API_KEY and GC_GITEA_ADMIN_TOKEN
docker compose up --build

# Local backend dev
cd backend
pip install -e ".[dev]"
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Local frontend dev
cd frontend
npm install && npm run dev

# Tests
cd backend && pytest          # 97 tests
cd frontend && npm run build  # Verify frontend compiles

Code Conventions

• IDs: All primary keys are 26-char ULIDs (Crockford Base32), generated by core/ids.new_ulid()
• Database: SQLite with WAL journal mode. Use get_db() dependency for sessions. All JSON fields stored as _json Text columns, parsed in Pydantic schemas
• Config: All settings use GC_ prefix in env vars. Pydantic Settings reads .env file. Never hardcode secrets
• API patterns: FastAPI router in api/campaigns.py. All endpoints return Pydantic models. Campaign lifecycle enforced by lifecycle.ensure_transition()
• State machine: draft → seeding → running → stopped/evaluating → complete/failed. Invalid transitions raise HTTP 409
• Safety profiles: guarded (10 tool calls/turn, 120s timeout) vs unrestricted (50 calls/turn)
• Error handling: LLM failures return do_nothing tool call as fallback. Tool validation via tool_registry.validate_tool_call()
• Gitea integration: Gitea 1.22 uses PUT (not POST) for file create/update. The gitea_client.py handles this

Campaign Lifecycle

1. Create — POST /campaigns with env_type, source_text, agent_count, round_limit
2. Seed — POST /campaigns/{id}/seed creates agents and initializes environment
3. Start — POST /campaigns/{id}/start begins round execution
4. Evaluate — Automatic after rounds complete, or manual POST /campaigns/{id}/evaluate
5. Evolve — POST /campaigns/{id}/evolve creates next-generation campaign from top performers
6. Auto-evolve — POST /campaigns/{id}/auto-evolve runs multiple generations automatically

Key API Endpoints

Database Tables

8 tables: campaigns, agents, action_events, edges, evaluations, usage_records, model_pricing, experiment_snapshots

• campaigns — Config, state, LLM settings, budget, convergence policy
• agents — Persona, strategy, fitness_score, rank, branch_name
• action_events — Round-by-round tool calls with status and timing
• evaluations — Per-evaluator scores (reliability, engagement, diff_quality, etc.)
• usage_records — Token counts and cost per agent per round

Environment Types

Dev Arena (Primary)

12 tools: inspect_repo, list_branches, read_file, write_file, diff_branch, open_issue, comment_issue, list_issues, open_pr, review_pr, list_prs, do_nothing

5 evaluators: reliability, diff_quality, collaboration, review_quality, adaptation

Social Arena

11 tools: read_timeline, create_post, reply_to_post, like_post, dislike, repost, quote_post, follow_agent, list_following, view_agent_profile, do_nothing

6 evaluators: reliability, engagement, influence, adaptation, controversy, argument_survival

Testing

• Tests in backend/tests/ using pytest + httpx TestClient
• test_comprehensive.py — Campaign CRUD, validation, config parsing
• test_lifecycle.py — State transitions, seed/snapshot, conflict detection
• Always run pytest after changes. All 97 tests must pass
• Frontend: npm run build must succeed with zero errors

Common Tasks

Adding a new API endpoint

1. Add route function in backend/app/api/campaigns.py
2. Add request/response schemas in backend/app/db/schemas.py if needed
3. Add corresponding method in frontend/src/api.js
4. Run pytest to verify nothing breaks

Adding a new evaluator

1. Add evaluate_<name>() function in backend/app/services/evaluators.py
2. Register it in the evaluator dispatch within run_evaluators()
3. Update docs/ARCHITECTURE.md evaluator tables

Adding a new tool

1. Add ToolSpec entry in backend/app/services/tool_registry.py
2. Add handler in social_arena.py or dev_arena.py (and gitea_env.py for dev)
3. Update tool definitions in context.py templates

Modifying the database

1. Add/modify columns in backend/app/db/models.py
2. Update schemas in backend/app/db/schemas.py
3. SQLite: delete grail.db to recreate (or use ALTER TABLE migration)
4. Docker: rebuild with docker compose up --build

Docker

Services:
  api:      port 8060 → backend FastAPI
  frontend: port 5174 → Vue/nginx
  gitea:    port 3000 → Gitea 1.22

Volumes: api-data, gitea-data, postgres-data (optional)

Gitea admin token: create via Gitea UI at http://localhost:3000 → user settings → applications → generate token with all scopes.

Gotchas

• Gitea 1.22 file API: Uses PUT for create/update, not POST. Already handled in gitea_client.py
• SQLite locking: WAL mode + busy_timeout=5000ms prevents "database is locked" errors. Don't run multiple writers
• Venice AI: Uses OpenAI-compatible API at https://api.venice.ai/api/v1. Model: qwen3-5-9b. Some models don't support tool calling
• Campaign status: Must follow state machine. Attempting invalid transitions returns 409 Conflict
• Safety profiles: guarded limits to 10 tool calls per turn. The runner enforces this in _run_agent_turn()
• JSON fields: Stored as _json Text columns. Access via schema from_orm_model() or parse manually. Don't serialize None — use empty dict
• SSE streaming: /campaigns/{id}/feed uses Server-Sent Events. Frontend uses EventSource API
• CORS: Configured in main.py from GC_CORS_ORIGINS setting. Add frontend dev ports if needed