Skip to content

AGENTS.md

Latest commit

 

History

History
128 lines (97 loc) · 5.18 KB

AGENTS.md

File metadata and controls

128 lines (97 loc) · 5.18 KB
Raw

AGENTS.md

Instructions for AI coding agents working on this repository.

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 gateway code has been removed as part of the migration plan.

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-praxis/       # Praxis integration
├── 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
  • 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

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.85.

agentic-server-core boundaries

  • 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.
  • In src/ code, reuse utils::common for JSON serialization/deserialization and fallback behavior. Do not call serde_json directly when an existing strict, optional, or defaulting helper expresses the required policy; add a focused helper there when the policy is reused. Direct serde_json use is fine in tests, fixtures, and cassette tooling. Keep Serde wire-format attributes on the owning type.

Rust Best Practices

  • 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.