Skip to content

AGENTS.md

Latest commit

 

History

History
82 lines (66 loc) · 3.04 KB

AGENTS.md

File metadata and controls

82 lines (66 loc) · 3.04 KB
Raw

AGENTS.md

Guidance for agents working in this repository.

Project Shape

This is a Rust workspace with the ai crate in crates/ai and example packages under examples/.

The crate provides:

  • LLM streaming and one-shot completion APIs.
  • Tool calling and JSON Schema based tool definitions.
  • Model lookup and custom model configuration.
  • OAuth helpers for Anthropic and GitHub Copilot.
  • A lightweight agent loop with events, tool execution, steering, and follow-up queues.

The root README.md is intentionally short. The detailed crate documentation lives in crates/ai/README.md.

Commands

Prefer the mise tasks:

mise run fmt
mise run check
mise run clippy
mise run test-ai
mise run test
mise run all

Equivalent cargo commands:

cargo fmt --all --check
cargo check --workspace --all-targets
cargo clippy --workspace --all-targets -- -D warnings
cargo test -p ai
cargo test --workspace

API Guidance

Use stream_simple for streaming responses and complete_simple for one-shot responses unless the lower-level StreamOptions shape is needed. Use stream or complete for direct provider-option forwarding or lower-level request control.

The active built-in language provider scope is OpenAI, Anthropic, and GitHub Copilot. The active built-in image provider scope is OpenAI-compatible image generation and OpenRouter image generation. Azure Foundry and other compatible language endpoints should be documented and tested as configured provider handles, such as providers::openai::builder() plus provider.model(...).base_url(...).headers(...).compat(...). Do not add broad provider autodetection by provider name or base URL unless that provider is intentionally in scope.

Development Notes

  • Use semantic/conventional commit messages, such as feat: add provider, fix: handle stream errors, docs: update README, or chore: update lockfile.
  • When porting behavior from the original Pi TypeScript implementation to Rust, treat Pi as the source of truth and keep the port as close to 1:1 as Rust permits. Preserve Pi's behavior, control flow, data model, helper boundaries, and naming where possible; make only mechanical adaptations required by the language or this crate's existing public API. Do not add downstream consumer- specific behavior to the port. Document any unavoidable semantic divergence from Pi explicitly.
  • Use the same semantic/conventional style for PR titles, such as feat: add provider, fix(example): limit bash tool execution, or ci: run clippy in workflow. PR bodies should include concise Summary and Verification sections.
  • Keep public behavior aligned with the existing Rust API shape before adding new abstractions.
  • Add or update tests for provider payload changes, stream event ordering, tool-call behavior, abort behavior, and agent loop state changes.
  • The tests currently live mostly as module-level unit tests under crates/ai/src; there is no crates/ai/tests directory at the moment.
  • Avoid unrelated README policy sections, logos, or copied upstream text.