# Python Parity And Production Readiness

This package tracks Python `azure-ai-agentserver-responses`, but the Python
package is currently more mature. Use this document as the working parity map.

## Comparison Scope

Use the Python packages as responsibility references, not as file-layout
templates:

| TypeScript | Python | Status |
| --- | --- | --- |
| `@cuylabs/agent-foundry-agentserver-core` | `azure-ai-agentserver-core` | Same host-foundation role, but Express/Node instead of ASGI/Starlette/Hypercorn |
| `@cuylabs/agent-foundry-agentserver-responses` | `azure-ai-agentserver-responses` | Same Responses protocol role and depends on the TS core package |
| `@cuylabs/agent-foundry-hosting/responses` | No direct Python package peer | agents-ts bridge that maps local `agent-core` events into Responses events |

This means `agent-foundry-hosting/responses` should be compared against
`agent-core` and `agent-server` behavior, while protocol correctness should be
checked in `agent-foundry-agentserver-responses`.

## Source Of Truth

The Python package points at the Azure REST API specs TypeSpec source through
`type_spec/tsp-location.yaml`:

```yaml
directory: specification/ai-foundry/data-plane/Foundry/src/sdk-service-agentserver-contracts
entrypointFile: client.tsp
additionalDirectories:
  - specification/ai-foundry/data-plane/Foundry/src/openai-responses
  - specification/ai-foundry/data-plane/Foundry/src/openai-conversations
  - specification/ai-foundry/data-plane/Foundry/src/tools
  - specification/ai-foundry/data-plane/Foundry/src/common
  - specification/ai-foundry/data-plane/Foundry/src/memory-stores
```

For production parity, TypeScript should eventually generate or validate its
protocol models from the same TypeSpec/OpenAPI source instead of relying only on
hand-written structural interfaces.

## Current TS Coverage

| Area | TS status |
| --- | --- |
| Express host and route surface | Implemented |
| Create, get, delete, cancel, input-items endpoints | Implemented |
| SSE response framing | Implemented |
| Replay cursor `starting_after` | Implemented |
| `TextResponse` convenience helper | Implemented |
| `ResponseContext` input text, input items, history | Implemented |
| `ResponseProvider` and `ResponseStreamProvider` contracts | Implemented |
| Foundry HTTP storage provider | Implemented |
| In-memory provider for dev/test | Implemented |
| Agent Server headers, isolation, tracing hook-up | Implemented foundation through core; responses-specific contract coverage still partial |
| `agent-core` bridge | Implemented in `@cuylabs/agent-foundry-hosting/responses` |
| TypeSpec-generated request/response models | Not implemented |
| Generated schema validation | Not implemented |
| Full `ResponseEventStream` builder API | Not implemented |
| SSE keep-alive option | Not implemented |
| Python contract-suite parity | Partial |

## Important Gaps Before Calling This Fully Production-Equivalent

The TS source now follows the same broad domains as Python:
`hosting`, `store`, and `streaming`. It intentionally does not copy Python's
private module names one-for-one, and the model layer remains hand-written until
the TypeSpec generation work is added.

The current TS implementation is a good protocol host foundation, but it is not
yet as hardened as the Python SDK.

First, request validation is still mostly structural and semantic. Python
generates validators from the TypeSpec/OpenAPI model and rejects malformed
payloads earlier and with richer details.

Second, Python has a full lifecycle/state-machine layer around emitted events.
It validates first-event rules, output item event shape, terminal transitions,
and output manipulation invariants. TS currently normalizes only the minimum
needed event shape.

Third, Python has a broad contract suite covering mode matrices, stream replay,
disconnect behavior, cancellation consistency, persistence failure behavior,
chat isolation, eager eviction, and OpenAI wire compliance. TS has focused unit
and host tests, but not yet the equivalent contract matrix.

Fourth, Python exposes richer handler ergonomics through `ResponseEventStream`
and builder helpers for messages, function calls, reasoning items, annotations,
images, and structured outputs. TS currently supports raw events and
`TextResponse`.

Fifth, Python's Foundry storage provider is layered on the Azure SDK pipeline,
including retry, request logging, tracing, and storage-specific serialization.
The TS provider follows the same HTTP endpoint shape, but it currently uses a
direct `fetch` implementation and needs the same production transport hardening.

## Recommended Next Work

1. Add TypeSpec/OpenAPI-based model generation or runtime validation for
   `CreateResponse`, response items, and stream events.
2. Port the Python mode matrix and cross-API contract tests into TS.
3. Add a TS `ResponseEventStream` builder API instead of expecting raw events
   for non-text outputs.
4. Add lifecycle validation for handler-emitted events.
5. Add persistence-failure tests and storage error mapping parity.
6. Add SSE keep-alive support if hosted Foundry requires long-lived streams
   through infrastructure that closes idle connections.