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.
- 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
../praxisfor testing local core changes throughmake patch-praxis
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.
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_nameThe 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.
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, injectsResponseStoreRegistryas 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.
Follows the same conventions as praxis core. See the shared development conventions for the full coding style guide and CONTRIBUTING.md for contribution requirements.
- 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.
New capabilities require:
- Unit tests
- Integration tests
- Example config in
examples/configs/ - Functional integration test for the example config
- 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).
When an inference transformation behavior changes, update its tests and fixture coverage in the same change:
- Add or update the scenario and its focused unit/integration tests.
- Add truthful provider recordings or controlled synthetic evidence.
- Update
tests/integration/fixtures/inference/coverage.yaml, including its feature, scope, scenario, provider, and status links. - Run
cargo xtask sync-inference-readme --fix; do not hand-edit the generated coverage block in the inference fixture README. - Run
cargo xtask check-inferenceandmake 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.
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.
- Create module under
filters/src/orapis/src/ - Implement
HttpFilterfrompraxis-filter - Register in
praxis_ai_filters::register_ai_filters(filters/src/register.rs) viaregister_filters! - Add unit tests and doctests
- Add example config in
examples/configs/
- Filter callouts: use
FilteredSubrequestExecutorfor 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::Streamand 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. Reservefilter_metadatafor 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.
apis/src/anthropic/— Anthropic Messages APIapis/src/openai/— OpenAI Responses, Conversations, SSE, model rewrite, store, rehydrate, validate, proxyapis/src/classifier/— AI request format detectionapis/src/json_body.rs— Shared JSON body mutation helper (serialize, replace, tracing events)apis/src/store/— ResponseStore trait, SQLite/Postgresfilters/src/agentic/— A2A, MCP protocol filtersfilters/src/guardrails/— AI content safety (NeMo)filters/src/inference/— Model-to-header routingfilters/src/prompt_enrich/— Prompt enrichmentfilters/src/token_usage/— Token counting and headers
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.
See praxis core documentation. Pingora handles: request smuggling prevention, H2 backpressure, connection pool safety, HTTP/1.1 upgrade detection.
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.