Skip to content

Latest commit

 

History

History
245 lines (200 loc) · 10 KB

AGENTS.md

File metadata and controls

245 lines (200 loc) · 10 KB

AGENTS.md

This file provides guidance to coding agents when working with code in this repository.

AI tools may assist with implementation, but do not add Claude or another AI tool as a commit collaborator, co-author, or signatory. Commit sign-off belongs to the human contributor responsible for the change.

Requirements

  • Rust stable 1.96+
  • Rust nightly (for rustfmt)
  • CMake 3.31+ (for Pingora build via praxis dep)
  • Docker 29.3.0+ or Podman (for container builds)
  • Optional Praxis core checkout at ../praxis for testing local core changes through make patch-praxis

Rust Data Ownership

Avoid cloning request, response, header, body, or SSE data unless the copy is necessary for correctness. This is a high-performance proxy, so prefer borrowing, moving, or sharing data through existing ownership boundaries before adding .clone(), to_vec(), to_string(), or full-body buffering.

When a clone is necessary, keep it close to the boundary that requires ownership and make the reason clear in the surrounding code or test. Do not clone streaming chunks or provider payloads just to satisfy local control flow; instead reshape the code to move completed buffers, borrow parsed fields, or process data incrementally.

Quick Reference

make setup-hooks    # install git pre-commit hook
make build          # workspace build
make test           # all tests
make fmt            # format with nightly rustfmt
make lint           # clippy, fmt, dependency, docs, and example checks
make doc            # rustdoc with -D warnings
make audit          # cargo audit + cargo deny check
make container      # build praxis-ai container image
make container-fips # FIPS runtime image on UBI 9 (see docs/fips.md)

Run a single test:

cargo test -p praxis-ai-apis --features full,openai-all,store-all -- test_name
cargo test -p praxis-ai-filters --features full,openai-all,store-all -- test_name
cargo test -p praxis-ai-proxy --features full,openai-all,store-all -- test_name

The praxis-ai-proxy production binary defaults to full (currently standard). Responses and its stores are experimental and off by default. The independent openai-agentic-loop feature enables the ephemeral agent and requires Responses; both select the passive experimental marker. Use openai-all to explicitly opt in to all OpenAI groups, plus store-sqlite or store-postgres as needed. A test name filter that matches only compiled-out tests reports "0 passed" and exits successfully. Developer cargo xtask commands opt in through the alias; plain workspace builds do not.

Keep local and release test aggregate targets complete when CI splits their recipes into parallel subtargets; the Makefile help lists the individual CI targets.

Architecture

Crate dependency flow:

server (praxis-ai-proxy)
  -> filters (praxis-ai-filters)
  -> apis (praxis-ai-apis)
  -> praxis-filter (versioned Praxis core dependency)
  • server (praxis-ai-proxy): binary entry point, registers AI filters on top of core builtins, injects ResponseStoreRegistry as pipeline extension
  • apis (praxis-ai-apis): provider-specific API types (OpenAI, Anthropic), request classification, response storage backends (SQLite, PostgreSQL), token usage extraction, SSE parsing
  • filters (praxis-ai-filters): cross-cutting AI filter implementations (A2A, MCP, guardrails, inference routing, prompt enrichment, token usage header injection)

Dependencies on Praxis core use the versioned crates in the root Cargo.toml: praxis-filter for HttpFilter, pipeline, and registry; praxis-core for config types; praxis-protocol for HTTP/TCP adapters; and praxis-tls for TLS. Use make patch-praxis only when testing a local sibling checkout at ../praxis.

Conventions

Follows the same conventions as praxis core. See the shared development conventions for the full coding style guide and CONTRIBUTING.md for contribution requirements.

Git Workflow

  • Never amend commits — when addressing PR review feedback, add new fixup commits on top of the branch.
  • PRs are merged with squash and merge, so the final commit on the target branch is always clean regardless of intermediate fixup commits.

Test Requirements

New capabilities require:

  1. Unit tests
  2. Integration tests
  3. Example config in examples/configs/
  4. Functional integration test for the example config
  5. Generated example and filter documentation kept in sync

When changing anything under apis/src/openai/, always add or extend integration tests exercised through the OpenAI client where possible, in tests/integration/sdk/openai/test_openai_conversations.py or tests/integration/sdk/openai/test_openai_responses_vllm.py.

When changing anything under apis/src/anthropic/, always add or extend integration tests exercised through the Anthropic client where possible, in tests/integration/sdk/anthropic/ (e.g. tests/integration/sdk/anthropic/test_anthropic_error_formatter.py).

Inference Fixture Maintenance

When an inference transformation behavior changes, update its tests and fixture coverage in the same change:

  1. Add or update the scenario and its focused unit/integration tests.
  2. Add truthful provider recordings or controlled synthetic evidence.
  3. Update tests/integration/fixtures/inference/coverage.yaml, including its feature, scope, scenario, provider, and status links.
  4. Run cargo xtask sync-inference-readme --fix; do not hand-edit the generated coverage block in the inference fixture README.
  5. Run cargo xtask check-inference and make test-inference-fixtures.

Do not enumerate Rust test function names in the README. The manifest is the stable coverage inventory; test names may change without changing behavior. Credentialed live recordings require explicit authorization and must retain truthful provider, model, and provenance metadata.

Adding a Filter

Before creating a filter, inspect existing filters in apis/src/ and filters/src/ for overlapping responsibilities, including filters that already parse the same protocol or derive related routing facts. Prefer extending the filter that owns that behavior and reusing its parsed data. For example, derive modality in existing API protocol filters rather than adding a separate filter that buffers and parses the same request body. Create a new filter only when it has a distinct responsibility; explain which existing filters were considered and why extending them is unsuitable.

  1. Create module under filters/src/ or apis/src/
  2. Implement HttpFilter from praxis-filter
  3. Register in praxis_ai_filters::register_ai_filters (filters/src/register.rs) via register_filters!
  4. Add unit tests and doctests
  5. Add example config in examples/configs/

Key Patterns

  • Filter callouts: use FilteredSubrequestExecutor for every outbound call made by a filter. It runs the configured outbound filter chain around the HTTP exchange, including credential injection and other outbound policies. SubRequestClient::execute_url() performs the HTTP exchange without running a configured filter pipeline.
  • Classify → route → branch: classifier filters promote facts to internal headers (x-praxis-ai-*) and the router matches those headers to select clusters.
  • Do not buffer full streaming responses: streaming and SSE filters should use BodyMode::Stream and process chunks incrementally.
  • Per-response working state: keep private parser buffers, counters, indices, and progress in a typed struct in filter_state, isolated per filter instance. Reserve filter_metadata for intentional consumers outside the filter; inspect readers before moving keys. Retain bytes directly rather than encoding private buffers as strings or hex. Release retained buffers on completion or abandonment.
  • Incremental parsing: before adding a streaming parser, inspect existing helpers and reuse them when their boundary, UTF-8, limit, and EOF behavior matches. Explain behavior or crate-dependency constraints that prevent reuse. Carry owned buffers and scanning progress across chunks so unfinished prefixes are not repeatedly copied or rescanned. For buffering changes, measure allocated bytes across increasing event sizes at a fixed chunk size to detect quadratic growth.
  • Streaming regressions: test delivery before EOF, split delimiters and UTF-8, configured limits, terminal cleanup, and two instances sharing one request context. Assert output after intermediate chunks as well as the final combined output.
  • Validate only proxy-needed fields: let the backend handle parameter ranges, model availability, and role ordering.

Filter Organization

  • apis/src/anthropic/ — Anthropic Messages API
  • apis/src/openai/ — OpenAI Responses, Conversations, SSE, model rewrite, store, rehydrate, validate, proxy
  • apis/src/classifier/ — AI request format detection
  • apis/src/json_body.rs — Shared JSON body mutation helper (serialize, replace, tracing events)
  • apis/src/store/ — ResponseStore trait, SQLite/Postgres
  • filters/src/agentic/ — A2A, MCP protocol filters
  • filters/src/guardrails/ — AI content safety (NeMo)
  • filters/src/inference/ — Model-to-header routing
  • filters/src/prompt_enrich/ — Prompt enrichment
  • filters/src/token_usage/ — Token counting and headers

Dynamic Config Reload

Praxis swaps filter pipelines at runtime without restarting. The AI server inherits this from praxis-protocol. The ResponseStoreRegistry is injected as a PipelineExtension and created fresh per pipeline build.

Pingora Boundary

See praxis core documentation. Pingora handles: request smuggling prevention, H2 backpressure, connection pool safety, HTTP/1.1 upgrade detection.

CI Workflows

CI workflows that post PR comments must use the praxis-bot-app GitHub App token (via actions/create-github-app-token), not the default github.token.