docs: AI gateway documentation overhaul by rikatz · Pull Request #328 · praxis-proxy/ai

rikatz · 2026-07-09T23:01:59Z

Summary

Expand docs hub with guides (OpenAI Responses, token counting), architecture pages, and filter cross-links
Add ai-guardrails example with integration test; shrink lint-example-tests SKIP list

Test plan

Conventions CI (signoff, signed commits, no AI authorship)
make lint / cargo xtask lint-example-tests
Integration tests for new ai-guardrails example

Copilot

Pull request overview

Overhauls the AI gateway documentation, generates filter-to-example references, and adds an integration-tested guardrails example.

Changes:

Adds OpenAI Responses, token-counting, and crate-architecture guides.
Expands generated filter documentation with related examples.
Adds the guardrails example and reduces the example-test allowlist.

Reviewed changes

Copilot reviewed 40 out of 40 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`xtask/src/lint_example_tests.rs`	Reduces skipped examples.
`xtask/src/filter_docs.rs`	Enhances generated filter docs.
`tests/integration/tests/suite/examples/mod.rs`	Registers guardrails tests.
`tests/integration/tests/suite/examples/ai_guardrails.rs`	Tests guardrails example passthrough.
`examples/README.md`	Documents routing and guardrails examples.
`examples/configs/ai-guardrails.yaml`	Adds guardrails configuration.
`docs/token-counting.md`	Adds token-counting guide.
`docs/README.md`	Reorganizes documentation hub.
`docs/quickstart.md`	Updates next-step links.
`docs/proposals.md`	Corrects discussion URL.
`docs/openai-responses.md`	Adds Responses API guide.
`docs/filters/tool_parse.md`	Adds related examples.
`docs/filters/token_usage_headers.md`	Updates generated reference.
`docs/filters/token_count.md`	Updates generated reference.
`docs/filters/responses_proxy.md`	Adds related examples.
`docs/filters/README.md`	Updates filter overview.
`docs/filters/prompt_enrich.md`	Adds related example.
`docs/filters/openai_stream_events.md`	Adds related examples.
`docs/filters/openai_responses_validate.md`	Adds related examples.
`docs/filters/openai_responses_rehydrate.md`	Adds related examples.
`docs/filters/openai_responses_model_rewrite.md`	Updates type formatting and examples.
`docs/filters/openai_responses_format.md`	Adds related examples.
`docs/filters/openai_response_store.md`	Updates generated reference.
`docs/filters/openai_conversations.md`	Updates generated reference.
`docs/filters/model_to_header.md`	Adds related example.
`docs/filters/mcp.md`	Adds related examples.
`docs/filters/extensions.md`	Updates dependency and generation guidance.
`docs/filters/anthropic_validate.md`	Adds related example.
`docs/filters/anthropic_to_openai.md`	Adds related example.
`docs/filters/anthropic_stream_events.md`	Adds related example.
`docs/filters/anthropic_messages_protocol.md`	Adds related example.
`docs/filters/anthropic_messages_format.md`	Adds related examples.
`docs/filters/ai_guardrails.md`	Adds related example.
`docs/filters/a2a.md`	Updates type formatting and examples.
`docs/features.md`	Refreshes feature descriptions.
`docs/developing/getting-started.md`	Corrects binary name.
`docs/architecture/response-store.md`	Corrects source paths.
`docs/architecture/crate-layout.md`	Adds crate architecture guide.
`docs/architecture/ai-inference.md`	Updates core ownership and paths.
`docs/architecture/agentic-protocols.md`	Updates agentic module paths.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 41 out of 41 changed files in this pull request and generated 5 comments.

rikatz · 2026-07-10T00:08:32Z

+    let needle = format!("filter: {filter_name}");
+    let mut matches = Vec::new();
+    for path in yaml_files {
+        let Ok(content) = fs::read_to_string(&path) else {
+            continue;
+        };
+        if content.contains(&needle)


Acknowledged — not fixing in this docs PR. Substring matching has no false positives in current examples; YAML-aware exact filter: matching is reasonable follow-up if the example set grows.

Copilot

Pull request overview

Copilot reviewed 41 out of 41 changed files in this pull request and generated 2 comments.

rikatz · 2026-07-10T00:08:34Z

+    // Uses core `json_body_field`; covered by praxis core examples/tests.
    "ai-inference-body-based-routing.yaml",


Acknowledged — not fixing in this docs PR. model-to-header-routing.yaml is back on the SKIP list with an explicit justification; wiring model_to_header.rs to load_example_config is follow-up work.

Copilot

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 3 comments.

rikatz · 2026-07-10T00:08:35Z

-    // All configs are skipped until tests/integration is re-enabled.
-    "a2a-classifier-routing.yaml",
-    "a2a-task-routing.yaml",
+    // Uses core `json_body_field`; covered by praxis core examples/tests.


Same as the earlier SKIP-thread comment: kept on SKIP intentionally; integration test still uses inline YAML in this PR.

Expand the docs hub with OpenAI Responses and token-counting guides, crate-layout architecture, and generated filter docs with navigable example links. Add ai-guardrails example and integration test, shrink the example-test SKIP list, and address review feedback (guardrails scaffold labeling, issue tracker links, filter_metadata docs, and config-note link normalization). Signed-off-by: Ricardo Pchevuzinske Katz <katz@redhat.com>

Copilot

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 4 comments.

rikatz · 2026-07-10T00:08:38Z

+    let parsed: serde_json::Value = serde_json::from_str(&body).expect("backend should echo valid JSON");
+    assert_eq!(parsed["model"], "gpt-4o", "body should pass through unchanged");


Acknowledged — not expanding in this PR. The test verifies status 200 and backend echo; asserting the full JSON payload is a reasonable follow-up for stronger pass-through coverage.

Clarify filter_metadata token phase-ordering in extensions.md, drop stale praxis-proxy#48 references from guardrails docs, and keep model-to-header-routing.yaml on the SKIP list. Signed-off-by: Ricardo Pchevuzinske Katz <katz@redhat.com>

Copilot

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 2 comments.

Update guardrails filter rustdoc and regenerate filter pages so they match the pass-through example. Fix awkward praxis-proxy#50 link wording in features.md. Signed-off-by: Ricardo Pchevuzinske Katz <katz@redhat.com>

Copilot

Pull request overview

Copilot reviewed 44 out of 44 changed files in this pull request and generated no new comments.

rikatz requested review from a team, aslakknutsen and Copilot July 9, 2026 23:02

Copilot started reviewing on behalf of rikatz July 9, 2026 23:02 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread xtask/src/filter_docs.rs

Comment thread xtask/src/filter_docs.rs Outdated

Comment thread docs/features.md Outdated

Comment thread examples/configs/ai-guardrails.yaml Outdated

Comment thread docs/token-counting.md Outdated

Comment thread docs/architecture/crate-layout.md Outdated

Copilot AI review requested due to automatic review settings July 9, 2026 23:14

Copilot started reviewing on behalf of rikatz July 9, 2026 23:14 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 9, 2026 23:19

Copilot started reviewing on behalf of rikatz July 9, 2026 23:19 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

rikatz force-pushed the docs/overhaul branch from 37c00eb to ce8dc3b Compare July 9, 2026 23:44

Copilot AI review requested due to automatic review settings July 9, 2026 23:47

Copilot started reviewing on behalf of rikatz July 9, 2026 23:47 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 10, 2026 00:00

rikatz force-pushed the docs/overhaul branch from f43e4fb to 70c94e8 Compare July 10, 2026 00:00

Copilot started reviewing on behalf of rikatz July 10, 2026 00:00 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

docs: address follow-up Copilot review items

08385c6

Clarify filter_metadata token phase-ordering in extensions.md, drop stale praxis-proxy#48 references from guardrails docs, and keep model-to-header-routing.yaml on the SKIP list. Signed-off-by: Ricardo Pchevuzinske Katz <katz@redhat.com>

Copilot AI review requested due to automatic review settings July 10, 2026 00:13

Copilot started reviewing on behalf of rikatz July 10, 2026 00:13 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread docs/filters/ai_guardrails.md

Comment thread docs/features.md Outdated

docs: align ai_guardrails generated docs with scaffold state

94e56c3

Update guardrails filter rustdoc and regenerate filter pages so they match the pass-through example. Fix awkward praxis-proxy#50 link wording in features.md. Signed-off-by: Ricardo Pchevuzinske Katz <katz@redhat.com>

Copilot AI review requested due to automatic review settings July 10, 2026 00:18

Copilot started reviewing on behalf of rikatz July 10, 2026 00:18 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

rikatz mentioned this pull request Jul 10, 2026

docs: overhaul praxis.fast site for praxis + ai doc refresh praxis-proxy/praxis-proxy.github.io#4

Open

3 tasks

		// Uses core `json_body_field`; covered by praxis core examples/tests.
		"ai-inference-body-based-routing.yaml",

		let parsed: serde_json::Value = serde_json::from_str(&body).expect("backend should echo valid JSON");
		assert_eq!(parsed["model"], "gpt-4o", "body should pass through unchanged");

Uh oh!

Conversation

rikatz commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rikatz Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

rikatz Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

rikatz Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

rikatz Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rikatz commented Jul 9, 2026 •

edited

Loading