experiential AGENTS.md

Agent guide — experiential

Experiential builds immutable task evidence from agent traces, composes and fits frozen model routers, runs those routers on loopback, and executes bounded SFT from persisted datasets. All importable code lives under exp/; benchmark data arrives as a dependency (see rule 6).

Toolchain

Managed with uv; lint/format with ruff; type-check with ty.

uv sync --extra dev
uv run ruff check .
uv run ruff format --check .
uv run ty check
uv run pytest -q

Repository checks

• Every new or rewritten hand-authored source, configuration, and documentation file with a covered suffix stays below 1,000 physical lines. The executable limit is 999 lines and counts comments and blank lines. Test modules named *_test.py are exempt so cohesive tests are not split solely to satisfy a line count. Generated lock files are excluded. Generated code belongs in an explicitly named generated/ directory and is never edited by hand.
• Full-repository Ruff check, Ruff format check, and ty check are required on every change. No pre-existing lint or type failures are grandfathered.
• Production imports follow the approved dependency direction: common may not import runtime, simulation, optimize, or cli; runtime may not import simulation, optimize, or cli; simulation may not import optimize or cli; optimize may not import cli. Optimize owns application orchestration and may depend inward on common, runtime, and simulation. The AST gate rejects every current forbidden edge directly and proves that the package graph is acyclic.
• The root CLI command set is exact: build, config, optimize, and run. An invocation without a subcommand opens the default gateway home screen. exp/cli/app_test.py and the release tests enforce the current command and distribution shape.

CLI package ownership

• exp/cli/app.py owns root command composition only. Command implementations live in the build/, config/, judge/, optimize/, and gateway/ packages. Gateway serving and the default home screen live under gateway/.
• exp/cli/providers/ owns provider discovery, model selection, and catalog setup shared by commands. Command-specific orchestration stays with its command package. In particular, router-candidate collection belongs to exp/cli/optimize/.
• exp/cli/shared/ owns reusable terminal, Typer, consent, picker, and progress primitives. It must not import command packages. exp/cli/providers/ may import shared/, but it must not import command packages.
• Keep the exp/cli/ root closed to new command implementation modules. Package-wide CLI tests may live in exp/cli/tests/; module tests stay beside the module they cover.