Repository navigation
MOD-20222: Align Context Gateway docs with the GA contract - #4358
Conversation
…fig, metrics and spans
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. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2aef0b7394
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
mich-elle-luna
left a comment
mich-elle-luna
left a comment
There was a problem hiding this comment.
thank you! I see there are a couple codex comments, but I will approve so you aren't blocked
…from the upgrade notes
…ontracts Regenerated from redislabsdev/iris main (81f2e7a0c) Smithy public projections, following each product's publish workflow: Agent Memory data plane (with the published overlay), Agent Memory self-managed control plane (shared /v2 contract merged with the on-prem ingestion-hooks contract, cloud-only elements prefixed), Agent Playbooks data plane, and Lens data plane (v1beta1). The Context Gateway control-plane spec is left to redis#4358. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MOD-20222: Align Gateway docs with the merged GA contract
|
|
nkanu17
changed the title
Summary
The Context Gateway pages described older routes, configuration names, and request fields, and several walkthroughs were placeholders. These changes align the developer and self-managed documentation with the merged GA service and provide complete setup, management, SDK, CLI, and agent examples.
namespace__toolnames, revision conflicts, tool errors, capture failures, partial results, and conditional invocation metadata.flowchart LR A["Merged Gateway GA service"] ==> D["Developer and operator docs"] B["Published OpenAPI"] ==> D C["Pinned SDK and CLI versions"] ==> D D ==> E["Deploy, configure, and run the clinic examples"]Stack: targets
iris-ga-docs. Includes the original cache/compression and database-default changes plus the GA follow-up merged from #4410.Review the setup and quickstart together first, then the configuration and failure-handling tables. Full details follow.
Stack
Base:
iris-ga-docs. Service reference: redislabsdev/iris#2217, merged as4e7b63210ab541ed457a1776155b5561b4b3d4f5. The documentation follow-up #4410 is already merged into this branch.Ticket ID
MOD-20222, Context Gateway GA hardening. Documentation delivery: RED-220418. Includes the cache/compression naming work from RED-222240 and default database guidance from MOD-19196.
Description
1. Use current cache, compression, and database-default names.
Configuration uses
cache.*andcompression.*, the tool-result hit marker is_meta.cache, and metrics useiris_context_gateway_cache_*andiris_context_gateway_compression_*. A handle remains the object returned by compression. Related headings, anchors, and upgrade guidance use the same terminology.The Helm defaults
defaultDatabases.gatewayDbanddefaultDatabases.surfaceDbrender asdefault_databases.gatewayanddefault_databases.surface. The docs distinguish the Gateway database used for cache and handles from the Surface database holding customer records, recommend separate endpoints when compression is enabled, and explain Redis JSON and eviction-policy requirements.Management examples explain omitted database IDs, invalid explicit empty or null IDs on create, resolved
databaseBindingresponses, and detaching a Gateway database only after cache and compression are disabled. The generated Control Plane OpenAPI is now refreshed from the published artifact described below. The separate ADK tool-result cache and Lens API are outside this update.2. 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.3. 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.4. 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.The deployment and authentication guidance also covers separate Redis credentials through per-plane overlays, the exact Surface pool setting, OIDC audience and public URL configuration, and the differences between Control Plane and Data Plane readiness 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.5. 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
1dadb82d8: resolved the quickstart conflict while retaining the GA SDK example and adding the shared CLI profile setup link. Independent merge review, whitespace and conflict-marker checks passed. The repository link checker scanned 19 Gateway Markdown pages with no findings. No runtime examples changed, so broader tests were not rerun.The checks below were run during the original update and its follow-ups in #4410, now merged into this branch. The merge check below covers the later integration with the current base branch.
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.06c7031dd, before later wording and overlay additions: 56 Bash blocks, 5 Python blocks, 1 JSON block, and 9 YAML blocks passed. Shell placeholders were substituted only for syntax validation.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 application code; the main risk is outdated or incorrect operator guidance if it diverges from the shipped GA service.
Overview
This PR rewrites Context Gateway developer and self-managed operator documentation to match the merged GA service contract instead of the older paths, field names, and placeholder walkthroughs.
API and naming: Docs now use unified Control Plane (
/iris/v1/context-gateway/...) and Data Plane MCP routes, uppercase enums (FULL/SEARCH,ENABLED/DISABLED),name/gatewayId/expectedRevision, anderrors[](including 412 revision conflicts). Tool exposure is documented as discoverednamespace__toolnames (32-character namespaces), not dotted names.Product terminology: Result cache and result handles are renamed to cache and compression across concepts, limits, metrics (
iris_context_gateway_*), and Helm settings (cache.*,compression.*, invocation_meta.cache).Behavior callers must handle: Explicit
run_tool_as_handlefailures (no silent inline fallback), partial Surface captures and completeness warnings,unknown_toolon managed targets vs direct MCP calls, conditional invocation metadata, and CLI vs MCPcount_resultslimitations.Runnable content: Placeholder “Iris example” blocks are replaced with a shared clinic dataset flow—pinned
redis-context-gateway==1.0.0b1,redis-iris==1.0.0b2, full quickstart Python, cURL/jq management pages, self-managed deploy/api-examples, and OpenAI Agents SDK / LangGraph samples.Operations: New guidance covers default Gateway/Surface databases, Gateway DB requirements (JSON,
noeviction, memory shares), per-plane Redis overlays, optional metadata-resolution cache rollout, readiness differences, and updated troubleshooting tables.Reviewed by Cursor Bugbot for commit 1dadb82. Bugbot is set up for automated code reviews on this repo. Configure here.