overlay: 1.0.0 info: title: API Evangelist enhancements — Cognizant Neuro SAN agent service version: 1.0.0 extends: ../openapi/cognizant-technology-neuro-san-agent-service.json x-provenance: generated: '2026-09-05' method: generated source: >- Derived from the provider's own documentation (neuro-san README, docs/clients.md, docs/mcp_service.md, agent.proto comments) and from this repository's artifacts. Every action below adds context the published contract omits; none contradicts it and the original spec is never mutated. note: >- The single highest-value addition here is the servers[] block. The published contract has NO servers[] at all, which leaves a client with four paths and no host to send them to. The value added is TEMPLATED on purpose — neuro-san is self-hosted, so the host genuinely is a variable, and inventing a concrete Cognizant hostname would be a fabrication. actions: - target: $ description: >- Add a templated server. neuro-san is self-hosted software; the provider's own examples use http://localhost:8080 after the operator starts the server. The variables make the host and port explicit rather than guessed. update: servers: - url: '{scheme}://{host}:{port}' description: >- An operator-run neuro-san agent service. Not a Cognizant-hosted endpoint — Cognizant publishes the software, the operator runs the server. variables: scheme: default: http enum: - http - https description: >- The provider's documented examples use http on loopback. TLS termination is the operator's responsibility and is not required by the contract. host: default: localhost description: The host on which the operator runs server_main_loop. port: default: '8080' description: >- The port used throughout the provider's own curl examples in docs/mcp_service.md. - target: $.info description: >- Correct the record on info.version and name the real upstream. The document's declared version is a generator default that has never tracked the software. update: x-upstream-version: 0.7.0 x-upstream-version-released: '2026-09-03' x-version-warning: >- info.version is "0.0.1", a protoc-gen-openapi default. It does not track the neuro-san release. Read currency from the PyPI package version instead. x-license: Apache-2.0 x-source-repository: https://github.com/cognizant-ai-lab/neuro-san x-generated-from: >- neuro_san/api/grpc/{concierge,agent,chat,mime_data}.proto via protoc-gen-openapi x-published-at-runtime: GET /api/v1/docs - target: $ description: Record the sibling surfaces this REST projection coexists with. update: x-surfaces: grpc: services: - dev.cognizant_ai.neuro_san.api.grpc.agent.AgentService - dev.cognizant_ai.neuro_san.api.grpc.concierge.ConciergeService note: >- The REST paths below are google.api.http annotations on these RPCs; gRPC is the source of truth, not a parallel implementation. mcp: protocol_version: '2025-06-18' transport: JSON-RPC 2.0 over HTTP POST path: /mcp note: >- Enabled with --mcp_enable=true. Each public agent network becomes one MCP tool. See mcp/cognizant-technology-tool-crosswalk.yml. - target: $.paths['/api/v1/{agent_name}/streaming_chat'].post description: >- Document the streaming and continuation semantics. These are stated in agent.proto's comments and are load-bearing for any client, but the generated OpenAPI drops comments entirely, so a client reading only the spec would get them wrong. update: x-streaming: type: server-streaming framing: >- Any single response is always on one line; responses are never broken across multiple lines in the HTTP response, so a client can parse the stream line by line. answer_location: >- The answer to a query is in the LAST streamed AGENT_FRAMEWORK message — not the first message and not necessarily the final message of the stream. mcp_divergence: >- The MCP projection of this operation does not stream; it returns a single JSON-RPC payload. x-continuation: mechanism: chat_context how: >- The last AGENT_FRAMEWORK message before the stream closes carries a populated chat_context. Copy it whole-cloth into the chat_context of the next request to continue the conversation. x-idempotency: supported: false warning: >- No replay protection. Calling this twice starts two conversations and bills the operator's LLM provider twice. A retry after a timeout cannot be made safe from the client side. x-private-channel: field: sly_data note: >- An optional map deliberately excluded from the LLM chat stream. Keys may be referenced in the stream; values are passed programmatically to tools. Documented carrier for client-supplied API keys, usernames and session ids. - target: $.paths['/api/v1/list'].get description: Record that this listing is unpaginated and may be withheld. update: x-pagination: supported: false note: Returns the full agents array; no limit, offset, cursor or page parameter exists. x-visibility: note: >- Only agent networks the server marks public are listed. The provider states the chat client is deliberately unable to enumerate all registered agents. - target: $.paths['/api/v1/{agent_name}/connectivity'].get description: Record that connectivity output is deliberately partial. update: x-disclosure: note: >- Per connectivity.proto's own comment, server-side agent descriptions may withhold connectivity they deem private or too much of an implementation detail. Connectivity reported is only as much as the server wants a client to know — an empty or shallow result is not necessarily an error. - target: $.components.schemas.Status description: Name the error model explicitly so a client does not expect RFC 9457. update: x-error-model: google.rpc.Status x-rfc9457: false x-note: >- Not application/problem+json. There is no type, title, status, detail or instance member. See errors/cognizant-technology-problem-types.yml.