AGENTS.md

Instructions for AI coding agents working on this repository.

Before coding or reviewing

Read .agents/skills/agentic-api-engineering/SKILL.md before implementing, refactoring, fixing, or reviewing code. It defines repository-wide discovery, reuse of existing typed extension points, Rust design and Clippy expectations, provider documentation/parity evidence, and the recorder/test workflow. Apply its shared preparation once. For Rust changes, use the bundled Rust skill; use the focused review skills where relevant.

Project Overview

This repository is Rust-first under the vllm-project GitHub organization.

• Rust -- primary and active implementation language at the repo root.
• Docs -- MkDocs documentation in docs/.
• Python -- a lightweight distribution and launcher for the packaged Rust gateway; the gateway implementation remains Rust-first.

Terminology

• Read and follow TERMINOLOGY.md when naming API, state, tool, streaming, MCP, or reasoning concepts in code, documentation, issues, and pull requests.
• Treat TERMINOLOGY.md as normative for preferred prose. Preserve exact field names and item types when discussing a wire protocol.
• When local wording conflicts with current OpenAI documentation, prefer the OpenAI term unless this repository has a distinct implementation concept documented in TERMINOLOGY.md.

Project Structure

.
├── TERMINOLOGY.md              # Normative project vocabulary
├── crates/agentic-server/       # Axum binary, transport handlers, and configuration
├── crates/agentic-server-core/  # Protocol types, execution, tools, and persistence
├── crates/agentic-llm-d/        # Split-execution state backend for the llm-d coordinator
├── crates/agentic-cli-docs/     # Build-time generator for the CLI reference docs
├── crates/agentic-praxis/       # Praxis integration
├── python/agentic_api/          # Python distribution, diagnostics, and launcher
├── tests/python/                # Python package and CLI tests
├── .agents/skills/              # Engineering, Rust, and focused review skills
├── pyproject.toml               # Python wheel build metadata
├── Cargo.toml                    # Workspace manifest and shared dependencies/lints
└── docs/                         # Documentation (MkDocs)

Setup

Install pre-commit hooks and build the project:

pre-commit install
cargo build

Testing

cargo test

# Python distribution and CLI tests
uv run --python 3.12 --with maturin==1.14.1 --with pytest==9.1.1 python -m pytest tests/python

# Source-install CLI E2E (also exercises the packaged wheel build)
python3 scripts/tests/agentic-cli-e2e-test.py

• Before adding or updating replay cassettes, read crates/agentic-server-core/tests/cassettes/README.md and use its recorder workflow and existing scenario scripts; do not hand-author captured request/response YAML.

Linting and Formatting

cargo clippy --all-targets -- -D warnings   # lint
cargo fmt                                     # format
cargo fmt -- --check                          # check formatting only

To run all pre-commit hooks manually:

pre-commit run --all-files

Documentation

Install docs dependencies and run docs locally:

uv venv
uv pip install -r docs/requirements.txt
uv run mkdocs serve

Releases

• Read the release guide before preparing or publishing a release or changing release automation. Keep that guide synchronized with the workflow inputs and checks.
• PRs and merges validate artifacts; they do not publish packages. Release preparation, crates publication, and PyPI publication use separate GitHub Actions workflows. Trigger publishing on main after checking the run's commit and version; GitHub Actions handles validation and registry uploads. The crates workflow also publishes the container from the release tag. Container-only recovery uses the dedicated workflow; do not republish packages to repair an image or website failure.
• Use the Cargo workspace's declared version as the source of truth. Keep the core dependency and lockfile aligned; do not invent a default release version or a separate Python version.
• Preserve duplicate-version failures and all platform-specific wheel checks. Inspect registry state before retrying any failed publication; never add skip-existing or blindly retry a partial upload.
• Verify actual registry artifacts before reporting a release complete or updating website install versions. PyPI README/metadata fixes require a new release to reach the published package page.

Code Style

• Rust edition: 2024.
• Maximum line length: 120 characters (configured in rustfmt.toml).
• unsafe code is forbidden (unsafe_code = "forbid" in Cargo.toml).
• Clippy all lints are denied; pedantic lints are warnings.
• Minimum supported Rust version (MSRV): 1.98.1, declared as rust-version in Cargo.toml and checked by the msrv CI job. Keep msrv in clippy.toml equal to it.

The agentic-server and core design architecture

See ARCHITECTURE.md for the full crate breakdown, request lifecycle, module-by-module walkthrough, and contribution guide.

• types/ owns wire/domain data; events/ parses and normalizes upstream events; tool/ owns tool discovery, routing, and execution; executor/ orchestrates requests across inference, tools, and persistence; storage/ owns database models and operations; utils/ contains genuinely shared, domain-neutral helpers.
• Respect this dependency direction: handlers call core APIs; executor coordinates events, tool, and storage; those modules share contracts through types. Do not introduce transport concerns into core types or business logic.

Executor streaming change rules

Read the target streaming pipeline before changing streaming code in events/ or executor/. RFC #241 is split into synchronous ingestion #243, client delivery #244, and execution-placement measurement #245. New work must converge on those boundaries:

• Assign every responsibility to one stage: inference.rs owns HTTP/SSE framing, events/ owns normalization, the synchronous ingestion state machine owns semantic-event validation and output-item assembly, the stream relay owns ordered client delivery, and engine.rs owns inference rounds, the tool loop, and persistence.
• Extend the single ingestion path. Do not add a second parser, lifecycle validator, delta folder, finalizer, tool-call translator, or client-emission path. Different validation policies must share the same state transitions.
• Keep transport free of semantic-event and output-item decisions. Keep ingestion free of client-delivery concerns. Keep the relay free of response-assembly state. Keep the engine free of SSE parsing.
• Do not introduce unbounded channels. A channel needs an entry capacity plus either a byte budget or a maximum item size, defined full/disconnect behavior, cancellation propagation, and task join/error handling.
• Run synchronous ingestion inline by default. Add worker or spawn_blocking placement only when representative measurements show a benefit and include queue occupancy, tail latency, memory, and cancellation behavior.
• Preserve compile-time extension points: typed output-item state, exhaustive matches, and one declared path for a new semantic event or output-item kind. Test invalid lifecycle order, identifier/index mismatch, duplicate completion, terminal finalization, slow consumers, and disconnects when the changed boundary can encounter them.

Use .agents/skills/executor-architecture-review/SKILL.md for a focused, read-only boundary review while planning or reviewing these changes.

Storage change rules

Read Schema, migrations, and where data goes before changing the schema, a migration, or what is persisted. Model SQL stays portable across SQLite and PostgreSQL; backend differences belong in storage/pool.rs and storage/schema.rs. Keep responses.metadata to what a continuation needs, and give data read by another path its own column. Use .agents/skills/storage-schema-change/SKILL.md as the checklist.

Rust Best Practices

• Do not use loose/untyped JSON signatures (serde_json::Value and similar) at a public API boundary. Request, response, and tool payloads must be modeled as proper types in agentic-server-core/types and serialized/ deserialized through them. Functions and APIs introduced in this repo must be typed Rust; untyped JSON is not a substitute for a real type at a public boundary.
• Prefer borrowing (&T, &str, &[T]) and avoid .clone() unless ownership or lifetime requirements make it necessary. Move values when ownership is transferred; use Arc only for genuinely shared thread-safe state, and keep required clones explicit and close to task spawn.
• Return Result for recoverable failures and propagate with ?. Use typed thiserror errors in library/core code, preserve sources during conversion, add useful boundary context, and avoid unwrap/expect in production paths except for documented, impossible invariants.
• Never hold a Mutex/RwLock guard across .await. Use Tokio async I/O, spawn_blocking for blocking or CPU-heavy work, bounded channels for backpressure, and try_join! for independent fallible work. Spawned tasks must have clear cancellation, shutdown, and join/error handling.
• Encode invariants with enums, newtypes, Option, and validated constructors. Prefer exhaustive matches and safe conversions (From/TryFrom) over stringly typed state, unchecked casts, or panics.
• Avoid speculative optimization: minimize allocations in hot paths with borrowing, slices, Bytes, and known capacities, then validate non-obvious optimizations with measurements. unsafe remains forbidden.

Commits

• Always sign off commits with the -s flag (git commit -s).
• Use conventional commit prefixes:
  • feat: -- new feature
  • fix: -- bug fix
  • ci: -- CI/CD changes
  • chore: -- maintenance tasks (deps, config)
  • docs: -- documentation only

Pull Requests

• Target the main branch.
• Include two sections in the PR description:
  • Summary -- what the PR does and why.
  • Test Plan -- how the changes were verified.
• Ensure all pre-commit hooks pass before opening the PR.