Repository navigation
MOD-20222: Align Gateway docs with the merged GA contract - #4410
Conversation
|
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
🧠 Redis MemoryFound 5 related items from repository history:
Memory updated at 4ae6468 |
|
Verified all three findings against the merged Gateway implementation and fixed them in 4ae6468:
Independent review, the three-page link check, and whitespace checks passed. There were no GitHub review threads for these findings, so there are no matching threads to resolve. The PR description is updated. |
2c169f6
into
RED-222240/drop-result-cache-names
Summary
The Gateway pages still describe the previous API and contain placeholder walkthroughs. This update brings the documentation onto the merged GA contract and gives operators and developers complete examples they can run against it.
namespace__toolnames, current limits, explicit capture failures, bounded Surface paging, and combined selection/grouping. Clarify search truncation and conditional invocation metadata.flowchart LR A["Existing cache/compression and database-default docs"] ==> B["GA contract and runnable examples"] C["Merged Gateway and published API"] ==> B D["Released SDK and CLI versions"] ==> BStack: this branch starts at the head of #4358 and targets its branch,
RED-222240/drop-result-cache-names. The original PR remains unchanged.Review the API examples and quickstart together first, then configuration and failure handling. Details follow.
Stack
Base:
RED-222240/drop-result-cache-namesat0bc1138a28e2873c5531aa8a1f5e626d9dbf3c61. This is the GA follow-up to #4358, not a replacement for its existing changes.Ticket ID
MOD-20222, Context Gateway GA hardening. Documentation delivery: RED-220418.
Description
1. Match the merged public contract.
The authoritative server revision is
4e7b63210ab541ed457a1776155b5561b4b3d4f5, the merged Gateway GA change. The bundled control-plane OpenAPI is the exact artifact from publisher run41114961138, SHA-25645e4ceafe69b2e2e3d0f0d4682681a180aea9d8407c94a624132147b9fd7beaa. It is copied unchanged, including the explicitly identified cloud-only database-list operation.Examples use the unified control-plane, MCP, and protected-resource metadata routes. Management requests use
name,expectedRevision, and uppercase enum values. Responses use resource-specific IDs,items, andnextCursor. Error guidance useserrors[], 412 for stale revisions, and 413 for oversized requests. Ordinary health probes remain distinct from the public service-health routes.2. Describe tool and handle behavior accurately.
Full-mode callers use discovered names unchanged. The docs cover the 32-character namespace limit, sanitized tool names, resource-name validation, and the distinction between direct unknown MCP calls and unknown managed targets.
Explicit capture returns a tool error when it cannot produce a handle. Automatic capture can still return inline. The failure tables include
handle_storage_full,handle_not_created,handleOutcome, andcompletion: dispatched, with guidance against repeating a mutating tool merely to obtain a handle.Eligible Surface filter and text queries can collect continuation pages within limits. Counts apply to captured rows, partial results carry warnings, and semantic/hybrid top-K queries are not continued. JSONPath selection can precede grouping in a direct MCP call. The released CLI still rejects those two count flags together.
Search guidance distinguishes the requested result limit from the response-size cap. Invocation
toolandcatalogRevisionfields are present only after an Upstream tool is resolved.3. Give operators the actual configuration and monitoring controls.
The configuration explains cache and handle memory shares of 0.4 and 0.5, their combined maximum of 0.95, and the 90% database backstop. It describes the positive
maxmemoryandnoevictionrequirements, runtime memory setting, and paging row, byte, concurrency, wait, and time budgets.Only the cache admits an unreported eviction policy. Handle creation requires an explicitly reported
noevictionpolicy before its memory checks.Metadata-resolution caching is optional and belongs under
dataplane.config. Its guidance includes the all-writers rollout prerequisite and bounded maximum age. Metrics use theiris_context_gateway_*prefix. Embedding settings now use a supported mounted Secret overlay because the previous Helm config placement was rejected by the chart schema.4. Replace placeholders with a coherent clinic walkthrough.
The setup loads two synthetic clinics and three provider records, creates full and search Gateways, registers the Surface on both, mints a scoped agent key, and verifies access. Management and Surface examples include create, read, update, refresh, policy, credential, and delete operations.
The Python quickstart discovers the provider filter, invokes it in both modes, explicitly captures a small result, reads and counts it, and releases its handle in a finally block. OpenAI Agents SDK and LangChain/LangGraph examples use separate dependency environments. The Surface guidance explains one index per field and normalization of stored TEXT line breaks, including rewriting existing records.
The install pins are released Python Gateway SDK
1.0.0b1, CLI1.0.0b2, and TypeScript SDK1.0.0-beta.1. Generic MCP behavior is distinguished from generated REST methods awaiting an SDK release. No server, SDK, or CLI implementation changes are included.Testing
4ae6468e8: all three review findings rechecked against merged server code, independently reviewed, and fixed. Three-page link and whitespace checks passed. No broad suites were rerun for these wording-only edits.1.0.0b1: normal flow, explicit capture refusal, and count failure with handle cleanup passed.1.0.0b2flags and its combined-count limitation. Both pinned framework programs import and their constructor/call signatures match. Dependency checks passed.Remaining release validation
No live Gateway deployment or model-provider calls were run for this documentation update. Run the clinic walkthrough against the release deployment before publishing the site. Existing TODOs for release artifact versions, supported platform qualification, backup guarantees, and provider-specific sign-in testing remain because this change cannot establish those release facts.
The deferred phrase-search issue MOD-20599 is unchanged. No packages or documentation site were published.
Note
Low Risk
Documentation-only changes with no runtime code; incorrect examples could mislead migrations to the GA API until validated against a live deployment.
Overview
Updates Context Gateway documentation to match the merged GA service contract and replaces placeholder walkthroughs with copy-paste examples.
API and behavior: Documents unified Control Plane and Data Plane routes under
/iris/..., uppercase enums (FULL,SEARCH,ENABLED,DISABLED),gatewayId/expectedRevision, structurederrors[], and 412 revision conflicts. Tool discovery now usesnamespace__toolnames (32-character namespaces) instead of dotted names. MCP reference covers splitunknown_toolhandling, explicitrun_tool_as_handlefailures (includingcompletion: dispatched), partial Surface captures, and JSONPath plusgroupByon direct MCP calls.Operator content: Helm/deploy values, cache/handle memory shares, paging limits, metadata-cache rollout,
iris_context_gateway_*metrics, embedding via mounted overlays, andaws_secrets_managercredential storage.Developer content: A shared clinic dataset powers the quickstart (pinned
redis-context-gateway==1.0.0b1),redis-iris==1.0.0b2CLI snippets, cURL/jq management pages, self-managed setup, and full OpenAI Agents SDK / LangGraph samples.Reviewed by Cursor Bugbot for commit 4ae6468. Bugbot is set up for automated code reviews on this repo. Configure here.