feat(openai): add OGX-backed file search callout

[leseb]

Summary

Adds the openai_file_search_callout filter — a hosted executor for OpenAI Responses API file_search_call output items. When the model emits a file_search_call, this filter fans out OpenAI-compatible /v1/vector_stores/{id}/search requests to an OGX backend, aggregates and ranks results, formats them as model context with file citations, and replays the completed items back to the response pipeline.

Closes #29.

What it does

• Bounded fan-out: Cartesian product of vector_store_ids × queries, capped at 64 specs with 8-way concurrency
• Ranked aggregation: Cross-store results merged, sorted by score, truncated to max_num_results
• Citation tracking: file_id → filename mappings stored in ResponsesState.citation_files for downstream annotation
• Failure policies: on_error: reject (502, default) or on_error: ignore (log + continue with partial results)
• SSRF-safe config: Rejects localhost, private/link-local/CGNAT/zero-network IPs, DNS hostnames, userinfo, malformed bracketed IPv6, query strings, fragments, and invalid ports at startup
• Status-aware execution: Only processes searching and in_progress items; terminal statuses are skipped
• Partial failure tracking: Cap-interrupted and per-spec-failed calls marked incomplete (not completed)
• Hybrid search rejection: ranking_options.hybrid_search rejected with 400 rather than silently degrading to vector-only

Architecture

ResponsesState.output_items (file_search_call, status: searching)
  → extract_file_search_tool_def (vector_store_ids, filters, ranking_options)
  → build SearchSpec[] (capped at 64, tracking skipped/capped call IDs)
  → FileSearchClient.search (8-way concurrent, 10 MiB per-response limit)
  → aggregate, sort by score, truncate to max_num_results
  → push completed/incomplete items to messages + persisted_messages + output_items

Not yet registered in production. This filter requires pipeline continuations (praxis#777) to receive pre-populated ResponsesState.output_items. It is compiled, tested, and documented but gated behind #[cfg(test)] in the server binary.

New files

File	Purpose
apis/src/openai/responses/file_search_callout/mod.rs	Filter implementation and orchestration
apis/src/openai/responses/file_search_callout/client.rs	OGX callout client with bounded concurrency
apis/src/openai/responses/file_search_callout/config.rs	YAML config parsing, URL/SSRF validation
apis/src/openai/responses/file_search_callout/citations.rs	Citation formatting and annotation
apis/src/openai/responses/file_search_callout/tests.rs	58 unit + functional tests (mock OGX)
apis/src/openai/responses/file_search_callout/live_tests.rs	Live OGX contract tests
examples/configs/openai/responses/file-search-callout.yaml	Example pipeline configuration
docs/filters/openai_file_search_callout.md	Generated filter reference

Test plan

• 58 unit/functional tests against mock OGX (cargo test -p praxis-ai-apis -- file_search_callout)
• Example integration test (cargo test -p praxis-ai-integration -- file_search_callout)
• Live OGX contract test in vLLM CI workflow
• make lint clean (clippy + nightly fmt + separator lint + filter doc lint)
• make build and make doc pass

Known limitations

• Body collection is unbounded: Core CalloutClient buffers the full response before the size check runs; requires a core crate change to enforce during streaming
• Aggregate memory: All 64 parsed responses are retained in memory before ranking; incremental top-k merge deferred
• First-turn state: Filter depends on upstream filters to initialize ResponsesState with output_items; not yet wired for non-continuation creates

[leseb]

blocked on praxis-proxy/praxis#849

[praxis-bot]

Review: feat(openai): add OGX-backed file search callout

Excellent, comprehensive addition. The security posture, bounded deserialization, and resource admission design are all strong. 58 unit/functional tests with a full mock OGX server provide solid coverage. A few issues worth addressing before merge.

Findings

#	Severity	File	Description
1	Medium	client.rs	Global static semaphores shared across all filter instances without documented sharing semantics
2	Medium	client.rs	merge_top_results uses O(n*k) linear-scan eviction instead of a min-heap
3	Medium	mod.rs	apply_batch returns Err(FilterAction) for non-error control flow
4	Medium	citations.rs	annotate_response is #[expect(dead_code)] -- dead public(crate) code shipped in production
5	Medium	mod.rs	bounded_string_copy can produce a string 1-4 bytes over max_bytes with misleading name
6	Medium	tests.rs	MockServer listener thread never terminates -- leaked OS threads per test
7	Medium	live_tests.rs	300-second timeout in fixture provisioning is very long for CI

Details

[Medium] client.rs -- The RESPONSE_BODY_BUDGET and RESPONSE_DECODE_SLOTS are process-wide static semaphores. This means all FileSearchCalloutFilter instances in all pipelines share the same 512 MiB budget and 32 decode slots. Hot-reload creating a new pipeline does not release permits held by the old pipeline's in-flight requests. This is a reasonable design for a shared proxy process, but the tradeoff should be documented explicitly. A future multi-tenant deployment could hit surprising contention if two unrelated listeners each configure large max_total_response_bytes.

[Medium] client.rs:1952-1976 -- merge_top_results performs O(incoming * k) work per merge because it scans for the minimum-scored element on every candidate. For the current MAX_NUM_RESULTS=50 cap this is fine, but the comment says "without retaining more than the final top-k" which implies awareness of scalability. Consider a BinaryHeap<Reverse<...>> if the limit ever increases, or at least add a doc comment noting the quadratic bound is intentional given MAX_NUM_RESULTS.

[Medium] mod.rs:106-111 -- apply_batch returns Err(FilterAction::Reject(...)) to communicate a rejection through the call chain. Using Err for non-error control flow is unconventional and makes the return type confusing (Result<(), FilterAction> where both Ok and Err are valid outcomes). Consider returning Option<FilterAction> or a dedicated enum instead.

[Medium] citations.rs:571-573 -- annotate_response is marked #[expect(dead_code)] with reason "consumed when core continuation returns the final inference response". This is fine as a forward declaration, but the function is pub(crate) and shipped in the binary. If it truly cannot be tested until continuation lands, consider gating it behind #[cfg(test)] or removing the pub(crate) visibility until it has a caller.

[Medium] mod.rs:684-695 -- bounded_string_copy deliberately copies up to max_bytes + 4 bytes when the value exceeds the limit (to preserve a char boundary). The doc comment says "only enough of an oversized value for the client to reject it" but the actual behavior is that the copy exceeds max_bytes. Downstream code that trusts max_bytes as a hard ceiling (e.g., search_url checking store_id.len() > MAX_VECTOR_STORE_ID_BYTES) will still reject it, so this is safe in practice. But the naming and doc are misleading -- the function does not produce a bounded copy, it produces an intentionally-oversized copy. Rename or clarify the doc.

[Medium] tests.rs -- Each MockServer::start_with spawns an OS thread with std::thread::spawn that loops on listener.incoming(). Since the listener is never shut down, these threads leak for the duration of the test process. With 20+ async tests each creating a MockServer, this accumulates. Consider using a shutdown channel or Drop impl that closes the listener.

[Medium] live_tests.rs -- The OgxFixture::provision method has a 300-second timeout for client construction and a 300-second loop for wait_for_indexing. In CI, this means a broken OGX server will hang the job for 10 minutes. Consider a shorter deadline (e.g., 60s) or making it configurable via env var.

Positive observations

• SSRF protection is thorough: rejects localhost, private/link-local/CGNAT/zero-network IPs, DNS hostnames, userinfo, malformed IPv6, query strings, fragments, and invalid ports.
• API key handling uses SecretString + Zeroizing + sensitive header marking. Error paths never leak the key value.
• Custom bounded DeserializeSeed deserialization with deadline checks is a strong defense against malicious OGX responses.
• Citation marker extraction handles Unicode correctly (character offsets, not byte offsets).
• The test suite covers failure modes, budget exhaustion, deadline enforcement, concurrent scheduling, and outbound input validation.
• Integration test replaces ${VECTOR_STORE_API_KEY} without set_var (unsafe in Rust 2024).
• Filter is properly registered in server/src/lib.rs and documented in docs/filters/.

---

Reviewed by praxis-bot

[praxis-bot]

[Medium] Process-wide static semaphores (RESPONSE_BODY_BUDGET at 512 MiB, RESPONSE_DECODE_SLOTS at 32) are shared across all filter instances and pipeline reloads. This is a reasonable design, but the sharing semantics should be called out explicitly in the module doc. A deployment with multiple listeners each configuring large max_total_response_bytes could hit surprising contention because the global budget is not partitioned.

[praxis-bot]

[Medium] merge_top_results uses O(incoming * k) linear-scan eviction to find the lowest-scored element on every candidate. Safe at the current MAX_NUM_RESULTS=50 cap, but worth a doc comment noting the quadratic bound is intentional. A BinaryHeap<Reverse<...>> would be needed if the limit ever grows.

[praxis-bot]

[Medium] apply_batch returns Err(FilterAction) for a non-error rejection path. Using Result<(), FilterAction> where the Err variant is a valid expected outcome (size-limit rejection) is unconventional. Consider Option<FilterAction> or a dedicated enum to make the control flow clearer.

[praxis-bot]

[Medium] annotate_response is #[expect(dead_code)] and pub(crate). If it cannot be called until continuation support lands, consider gating it behind #[cfg(test)] so the expectation is satisfied by test-only usage rather than a blanket dead-code suppression in production.

[praxis-bot]

[Medium] bounded_string_copy intentionally returns a string exceeding max_bytes (up to +4 bytes for char boundary). The name "bounded" and the doc "only enough of an oversized value" are misleading. Downstream callers like search_url do reject the oversized result, so this is safe, but renaming to e.g. defensive_string_copy or adjusting the doc to say "slightly exceeds max_bytes" would prevent future confusion.