fastapi-streams 0.1.0__tar.gz → 0.3.0__tar.gz

{fastapi_streams-0.1.0 → fastapi_streams-0.3.0}/CHANGELOG.md

@@ -3,6 +3,99 @@
 All notable changes and consumer upgrade steps are recorded here. Entries marked
 unreleased describe prepared source versions that have not been published.
 
+## 0.3.0 - 2026-10-18
+
+### Breaking changes
+
+- Regenerated Python SDKs validate path, query and header parameters at the
+  method call, before serialization and HTTP I/O. Invalid types or supported
+  scalar constraints now raise Pydantic `ValidationError` locally. Regenerate
+  SDKs, fix rejected arguments, and catch request validation around the method
+  call rather than only around stream iteration. Request bodies retain their
+  existing validation timing; HTTP still starts when iteration begins.
+- TypeScript generation now diagnoses scalar constraints it cannot enforce.
+  Review the selected target's diagnostics before promoting warnings to errors.
+  Existing known limitations can be accepted by exact diagnostic ID with a
+  review reason; do not suppress the warning category globally.
+
+### Added
+
+- Cache generated parameter, body and event TypeAdapters. Keep valid parameter
+  encoding, integer representations of number parameters, query array explosion,
+  optional omission and JSON body aliases unchanged.
+- Source-located diagnostics include JSON Pointer, operation ID, method/path,
+  keyword/value, target and enforcement limitation. Referenced and inline schemas
+  are located in the original document, with each affected operation identified.
+- Add `--diagnostics FILE`, `--strict` and `--allow-diagnostics FILE` to generation
+  and drift checks. Reports are deterministic JSON with stable identities;
+  malformed, duplicate and stale allowances fail before generated files change.
+  Repository drift checks use strict mode with reviewed TypeScript limitations.
+- Generated Python `StreamParseError` exposes `operation_id`, `category`
+  (`invalid_json` or `invalid_event_schema`) and `validation_errors`. Structured
+  details exclude input values and validator context. Keep `.data`, exception
+  chaining and the existing constructor; raw data and chained causes can contain
+  sensitive values and are never logged automatically by the SDK.
+- Add request/diagnostic/error regression tests for both Python HTTP backends and
+  installed-wheel consumers, plus a documented validation support matrix.
+
+### Upgrade from 0.2.0
+
+1. Upgrade the generator to 0.3.0 and regenerate with your existing HTTP backend.
+2. Validate consumer call sites, including invalid requests, before adoption.
+   Ordinary Pydantic coercion applies; valid numeric serialization is preserved.
+3. Generate JSON diagnostics and review exact allowances before enabling strict
+   CI. Changed locations, constraints, values, operations or targets need review.
+4. Read stream failure categories and structured details through public fields.
+   Keep raw payloads and full exception chains out of routine logs.
+
+## 0.2.0 - 2026-10-18
+
+- Source preparation passed workspace CI, independent wheel matrices and the
+  package release dry run. See the [release preparation evidence](../../docs/releases.md#verified-follow-up-preparation-2026-10-18).
+
+### Added
+
+- Preserve supported string patterns/lengths and numeric bounds/multiples in the
+  codegen IR and generated Python Pydantic annotations, including nested and
+  referenced scalars. Diagnose unsupported constraints and regex expressions.
+- Add `RequestOptions(unknown_events="ignore")` to generated Python SDKs. It
+  skips unknown string tags in a top-level discriminated event union; the default
+  remains an error. Malformed known events, missing tags and invalid JSON fail.
+  Both HTTPX backends retain their validation and transport behavior.
+- Add tested contract-first native proxy and private OpenAPI 3.1 REST-codegen
+  recipes. The authoritative OpenAPI 3.2 artifact remains unchanged.
+
+### Breaking generated-code changes
+
+- Regenerated Python models enforce scalar rules that 0.1.0 silently dropped.
+  Fix invalid payloads before adopting the new SDK. Unsupported constraints emit
+  `UnsupportedConstraintWarning`; constraints alongside enum/const/composition
+  and unsupported Python regex patterns fail explicitly. Move supported scalar
+  constraints onto scalar branches where possible. This is not full JSON Schema
+  validation. TypeScript remains static-only.
+- Regenerate committed SDKs and run consumer validation tests. Pass HTTPX2
+  generation/check options consistently if used. No wire names change.
+
+### Upgrade from 0.1.0
+
+1. Update `fastapi-streams[codegen]` to 0.2.0 and regenerate both SDKs from the
+   authoritative OpenAPI document. Keep the selected Python HTTP backend on
+   generation and check commands.
+2. Fix data violating preserved scalar constraints and review all unsupported-rule
+   diagnostics. Re-run consuming client validation and stream tests.
+3. Keep the default unknown-event error policy, or opt in per request only where
+   the upstream intentionally emits additional top-level discriminator values.
+
+### Release verification
+
+- Extend installed-wheel HTTPX/HTTPX2 smoke consumers to verify scalar constraints,
+  default unknown-event rejection, opt-in skipping and malformed known events.
+
+### Documentation
+
+- Fix PyPI installation instructions and supported-scope wording. Replace the
+  predecessor release guide with the workspace release process.
+
 ## 0.1.0 - 2026-10-17
 
 ### Added

{fastapi_streams-0.1.0 → fastapi_streams-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-streams
-Version: 0.1.0
+Version: 0.3.0
 Summary: Typed FastAPI streams with generated TypeScript and Python clients.
 Project-URL: Documentation, https://github.com/mathisarends/canon/tree/main/packages/fastapi-streams/docs
 Project-URL: Source, https://github.com/mathisarends/canon/tree/main/packages/fastapi-streams
@@ -45,10 +45,10 @@ A CI check catches drift between the Python app, the contract, and generated cod
 
 ## 1. Decorate your FastAPI endpoint
 
-Install from GitHub with the optional codegen extra:
+Install from PyPI with the optional codegen extra:
 
 ```sh
-uv add 'fastapi-streams[codegen] @ git+https://github.com/mathisarends/fastapi-streams.git'
+uv add 'fastapi-streams[codegen]'
 ```
 
 Save this as `app.py`:
@@ -236,7 +236,8 @@ and regenerating committed clients.
 | [Development](docs/development.md) | Tests, supported scope, and roadmap. |
 | [Releasing](docs/releasing.md) | Tag-based releases and credential-free PyPI publishing. |
 
-v0.0.1 supports GET/POST JSON SSE streams. Ordinary REST endpoints stay in the
-contract for your existing REST SDK. See the [supported scope](docs/development.md#supported-scope-and-roadmap).
+The current release supports GET/POST JSON SSE streams. Ordinary REST endpoints
+stay in the contract for your existing REST SDK. See the
+[supported scope](docs/development.md#supported-scope-and-roadmap).
 
 Python 3.12+ · FastAPI 0.143.3+ · Pydantic v2 · [MIT](LICENSE)

{fastapi_streams-0.1.0 → fastapi_streams-0.3.0}/README.md

@@ -27,10 +27,10 @@ A CI check catches drift between the Python app, the contract, and generated cod
 
 ## 1. Decorate your FastAPI endpoint
 
-Install from GitHub with the optional codegen extra:
+Install from PyPI with the optional codegen extra:
 
 ```sh
-uv add 'fastapi-streams[codegen] @ git+https://github.com/mathisarends/fastapi-streams.git'
+uv add 'fastapi-streams[codegen]'
 ```
 
 Save this as `app.py`:
@@ -218,7 +218,8 @@ and regenerating committed clients.
 | [Development](docs/development.md) | Tests, supported scope, and roadmap. |
 | [Releasing](docs/releasing.md) | Tag-based releases and credential-free PyPI publishing. |
 
-v0.0.1 supports GET/POST JSON SSE streams. Ordinary REST endpoints stay in the
-contract for your existing REST SDK. See the [supported scope](docs/development.md#supported-scope-and-roadmap).
+The current release supports GET/POST JSON SSE streams. Ordinary REST endpoints
+stay in the contract for your existing REST SDK. See the
+[supported scope](docs/development.md#supported-scope-and-roadmap).
 
 Python 3.12+ · FastAPI 0.143.3+ · Pydantic v2 · [MIT](LICENSE)

{fastapi_streams-0.1.0 → fastapi_streams-0.3.0}/docs/README.md

@@ -7,9 +7,10 @@ TypeScript Fetch and Python HTTPX clients from the same definitions.
 | --- | --- |
 | [Quickstart](quickstart.md) | Run the complete example and define your first stream. |
 | [Contracts and codegen](codegen.md) | Export OpenAPI, generate both clients, and detect drift in CI. |
+| [Native transports](native-transports.md) | Existing SSE proxies, contract-first generation and private REST codegen views. |
 | [Client usage](clients.md) | Named event values, typed iteration, authentication, cancellation, and errors. |
 | [Development](development.md) | Local checks, test coverage, supported features, and roadmap. |
-| [Releasing](releasing.md) | Tag-based releases, PyPI Trusted Publishing setup, and recovery. |
+| [Releasing](releasing.md) | Workspace release preparation, PyPI publishing, and recovery. |
 | [Architecture](architecture.md) | Server integration, shared IR, generation, and transport boundaries. |
 
 Start with the [quickstart](quickstart.md), then use the

{fastapi_streams-0.1.0 → fastapi_streams-0.3.0}/docs/clients.md

@@ -121,6 +121,38 @@ remain ordinary members of the user-defined union.
 
 ## HTTP error contracts
 
+Python request parameters and JSON bodies are validated when calling the method;
+catch Pydantic `ValidationError` around that call. Network and event errors occur
+while iterating. See the [validation matrix and CI policy](codegen.md#validation-support-matrix).
+
+Generated Python `StreamParseError` provides these public fields:
+
+| Field | Meaning |
+| --- | --- |
+| `operation_id` | Source OpenAPI operation ID |
+| `category` | `invalid_json` for malformed JSON; `invalid_event_schema` for invalid event shapes/constraints |
+| `validation_errors` | Pydantic error dictionaries with `type`, `loc`, `msg`; input values, context and URLs are excluded |
+| `data` | Original SSE data payload, retained for explicit inspection |
+
+For errors raised by generated operations, category and operation ID are always
+set. The existing `StreamParseError(data)` constructor remains valid; manually
+constructed errors can have `None` provenance/category and empty details.
+The original Pydantic `ValidationError` remains chained as `__cause__`.
+
+```python
+try:
+    async for event in client.runs.run_events(run_id="run_abc"):
+        handle(event)
+except StreamParseError as error:
+    record_failure(error.operation_id, error.category, error.validation_errors)
+```
+
+The SDK does not log event payloads or exceptions automatically. Raw `.data` and
+the full chained exception may contain sensitive values; log only reviewed fields.
+Even structured messages and field names should follow the consumer's logging
+policy. Malformed known events still fail with `unknown_events="ignore"`; only
+valid JSON objects with unknown string discriminator tags can be skipped.
+
 The SDK works with ordinary OpenAPI response declarations, including
 `application/json`, `application/problem+json`, and other declared response media
 types. No error registry or particular problem envelope is required. Declare

fastapi_streams-0.3.0/docs/codegen.md

@@ -0,0 +1,232 @@
+# Contracts and client generation
+
+[Documentation](README.md) · [Project](../README.md)
+
+## Export and generate
+
+```sh
+uv run fastapi-streams schema \
+  --app examples.agent_runs:app --output tests/fixtures/agent_runs.openapi.json
+
+uv run fastapi-streams generate \
+  --schema tests/fixtures/agent_runs.openapi.json --language typescript --output frontend/generated
+
+uv run fastapi-streams generate \
+  --schema tests/fixtures/agent_runs.openapi.json --language python --output myapp/generated
+```
+
+No running server is needed. Export imports the application. The codegen extra
+adds Jinja and JSON Schema validation; importing the server package needs neither.
+
+The exporter copies native FastAPI output, promotes compatible 3.1 output to
+OpenAPI 3.2.0, updates the declared OAS dialect when necessary, and validates the
+official bundled OpenAPI structural schema, Draft 2020-12 Schema Objects and
+local references. Incompatible contracts fail explicitly. The application's
+cached document and ordinary REST endpoints remain intact.
+
+The generator extracts application data from
+`itemSchema.properties.data.contentSchema`. Only stream operations and models
+reachable from their parameters, bodies, events and error responses are emitted.
+Operations use the first tag as their group, defaulting to `streams`.
+
+Generated method documentation carries each operation's `summary`, `description`,
+and `deprecated` marker alongside language-specific SDK behavior. Describe
+replay, retention, and server job lifetime explicitly on your endpoint; the
+generator does not infer these business guarantees. Python early exits should
+use `contextlib.aclosing`; TypeScript `for await` cleanup closes its reader.
+
+TypeScript has no runtime dependencies and uses Fetch-compatible APIs. The
+example uses ES modules and is tested on Node 24. Generated Python packages
+require Python 3.12+, `httpx>=0.28` and `pydantic>=2.11.2` (`uv add httpx pydantic`).
+
+HTTPX is the default. To generate a Python client using HTTPX2 instead, opt in
+when generating and checking it:
+
+```sh
+uv run fastapi-streams generate \
+  --schema tests/fixtures/agent_runs.openapi.json --language python \
+  --python-http-client httpx2 --output myapp/generated
+
+uv run fastapi-streams check \
+  --schema tests/fixtures/agent_runs.openapi.json --language python \
+  --python-http-client httpx2 --output myapp/generated
+```
+
+Install `httpx2>=2.13.1,<3` and `pydantic>=2.11.2` in that consumer. The
+generated package needs only the selected HTTP library; installing HTTPX2 does
+not change an existing HTTPX client. The Python generator API accepts the same
+choice as `generate_python(contract, http_client="httpx2")`. Pass the choice to
+every `check` or `generate --check` call; omitting it checks HTTPX output.
+`--python-http-client` requires `--language python`.
+
+REST operations remain available in the contract for an existing SDK generator
+such as Orval or HeyAPI. Keep REST and streaming SDKs in separate output
+directories. Reusing external generated model imports is a future feature.
+
+## Event discriminators
+
+A Python default allows omitting a field when constructing a model. It does not
+automatically make the field required in JSON Schema. The generator respects
+`required` and warns with `OptionalDiscriminatorWarning` when a stream event
+union uses an optional discriminator, including nested unions. An absent tag may
+prevent variant selection; TypeScript's static types do not validate incoming JSON.
+
+For **output-only** event models whose serializer always emits default fields,
+configure the output schema to describe that behavior:
+
+```python
+from pydantic import BaseModel, ConfigDict
+
+
+class StreamEvent(BaseModel):
+    model_config = ConfigDict(
+        json_schema_mode_override="serialization",
+        json_schema_serialization_defaults_required=True,
+    )
+```
+
+Inherit event variants from this model, or apply the configuration to an existing
+output-only base. It marks all serialized default fields required, not only the
+discriminator. Avoid applying it globally to shared request models: input and
+output requiredness can differ. Alternatively, declare the tag without a default
+and pass it explicitly. Regenerate the schema and clients after changing models.
+
+Warnings are advisory and do not change fields or defaults. Python callers can
+filter or promote this category using the standard `warnings` module; the category
+is available from `fastapi_streams.codegen.diagnostics`.
+
+## Check drift in CI
+
+```sh
+uv run fastapi-streams check \
+  --app examples.agent_runs:app --schema tests/fixtures/agent_runs.openapi.json \
+  --language typescript --output examples/agent_runs/generated
+
+uv run fastapi-streams check \
+  --app examples.agent_runs:app --schema tests/fixtures/agent_runs.openapi.json \
+  --language python --output examples/agent_runs/generated_python
+```
+
+`check` imports the app, compares its contract, validates the stored schema and
+compares generated files without writing. Omit `--app` for a contract supplied
+by another service. `schema --check` and `generate --check` are also supported.
+Exit codes: **0** current, **1** drift, **2** invalid input.
+
+Generation is deterministic. A manifest tracks owned files and cleans up stale
+generated files without deleting neighboring handwritten files. Use a dedicated
+output directory for each language. Unsafe paths and generated-name collisions
+fail explicitly.
+
+## Runtime validation and unknown variants
+
+Python validates path, query and header parameters and JSON request bodies at the
+method call, before serialization or HTTP I/O. Invalid arguments raise Pydantic
+`ValidationError` immediately, even if the returned iterator is never consumed.
+HTTP starts when iteration begins. Optional parameters supplied as `None` are
+omitted, preserving existing omission semantics. Pydantic's normal coercion
+applies; this is not Pydantic strict mode. Valid scalar encoding, integer values
+of number parameters (`0` stays `0`), query array explosion and body aliases are
+preserved. Adapters are cached in each generated API class.
+
+Python validates generated event models and request bodies with Pydantic. Supported
+scalar constraints are `pattern`, `minLength`, `maxLength`, `minimum`, `maximum`,
+`exclusiveMinimum`, `exclusiveMaximum`, and `multipleOf`. They survive nested
+models, arrays, nullable types and referenced scalar aliases. Patterns use
+Pydantic's Rust regex engine; unsupported expressions fail generation. Numeric
+multiples follow Pydantic's floating-point tolerance. This is not a complete JSON
+Schema validator. Formats, collection/object limits and other unsupported rules
+emit `UnsupportedConstraintWarning`; promote it to an error in CI when required.
+Constraints alongside enum/const or composition fail explicitly; constraints on
+scalar branches are supported. TypeScript provides static shapes and does not
+validate incoming JSON or enforce scalar constraints at runtime.
+
+Python event unions are closed by default: unknown variants raise
+`StreamParseError`. For an upstream that emits more variants than your declared
+subset, explicitly choose a per-request policy:
+
+```python
+from generated import RequestOptions
+
+options = RequestOptions(unknown_events="ignore")
+async for event in client.runs.run_events(run_id="run_abc", options=options):
+    ...
+```
+
+Ignoring requires a top-level discriminated union with known string tags. Only
+valid JSON objects with an unknown string discriminator are skipped. Invalid
+JSON, missing/non-string discriminators and malformed known variants still fail;
+unknown nested variants inside a known event fail too. The option adds no retry,
+reconnect or replay. TypeScript continues to forward JSON-decoded values without
+runtime union validation. Regenerate existing Python SDKs to obtain the option.
+
+## Validation support matrix
+
+| SDK target / boundary | Runtime shape validation | Supported scalar constraints | Timing |
+| --- | --- | --- | --- |
+| Python path/query/header | Yes | Yes, including referenced scalars and query array items | Method call, before serialization |
+| Python JSON request body | Yes | Yes, including nested values | Method call |
+| Python SSE event data | Yes | Yes, including nested values | Each event during iteration |
+| Python declared HTTP error bodies | Explicit consumer TypeAdapter | When explicitly validated | Consumer-controlled |
+| TypeScript parameters/body/events | Static types; events are JSON-decoded | No runtime enforcement | Generation diagnoses limitations |
+
+Unsupported formats and collection/object constraints remain diagnostics rather
+than implicit runtime validators. Optional `None` query/header parameters mean
+omission, not JSON null. Server-side validation remains necessary for every client.
+
+## Source diagnostics and CI policy
+
+`generate`, `generate --check` and `check` accept these options:
+
+```sh
+uv run fastapi-streams check --schema openapi.json --language python \
+  --output generated --diagnostics reports/python.json --strict \
+  --allow-diagnostics reviewed-python.json
+```
+
+Omit `--allow-diagnostics` when no limitations are accepted. The JSON report
+(`version: 1`, `diagnostics: [...]`) includes each diagnostic's `id`, `code`,
+`pointer`, `keyword`, `value`, `target`, `operation_id`, `method`, `path`, `message`
+and `accepted` status. Pointers are RFC 6901 paths into the original document,
+including inline schemas and referenced component definitions. Shared definitions
+identify each affected operation; unused components do not generate warnings.
+SSE framing metadata is outside generated event-model validation.
+
+`unsupported-constraint` identifies an unenforced rule for the selected target;
+TypeScript also diagnoses Python-supported scalar constraints because TypeScript
+has no runtime schema validator. Python's `optional-discriminator` diagnoses event
+selection risks without changing field requiredness. Human-readable warnings
+contain the same location, keyword/value, operation and limitation as the report.
+
+Without `--strict`, unaccepted diagnostics remain warnings. With it, any
+unaccepted diagnostic fails with exit code 2 before generated files change; drift
+still uses exit code 1. Reports are written even on strict-policy failure. Keep
+the report outside generated output and separate from schema/allowance inputs.
+
+Review the report and explicitly record an allowance, for example:
+
+```json
+{
+  "allow": [
+    {
+      "id": "unsupported-constraint:<copy the exact ID from the report>",
+      "reason": "Reviewed upstream UUID validation; client remains a string."
+    }
+  ]
+}
+```
+
+IDs include code, source pointer, keyword/value, target and operation context;
+message wording and schema filename are excluded. Changed constraints or contexts
+need a new review. Empty reasons, duplicate IDs, malformed files and stale
+allowances fail explicitly. Keep separate policies for each contract/target.
+Repository drift checks use strict mode with reviewed TypeScript allowances.
+
+Python generator API users can collect the same objects with
+`build_ir(document, target="python", diagnostics=items)` where `items` is an empty
+list. Omitting `diagnostics` emits warnings; the default target is Python. Select
+the matching target explicitly before calling the corresponding generator.
+
+## Existing native streams and mixed REST generation
+
+See the [native transport and mixed-codegen recipe](native-transports.md) when
+an existing generator, native server or byte-preserving proxy owns the stream.

fastapi_streams-0.3.0/docs/native-transports.md

@@ -0,0 +1,49 @@
+# Native SSE transports and mixed client generation
+
+An authoritative OpenAPI 3.2 contract can describe an existing SSE endpoint.
+`fastapi-streams generate --schema` does not require `StreamRouter`, a running
+server or replacement of the application's stream implementation.
+
+The executable [native proxy example](../examples/native_proxy.py) declares an
+explicit event union through `itemSchema.properties.data.contentSchema` and
+registers its referenced models. Its `StreamingResponse` forwards upstream raw
+bytes, status and selected response headers. Keepalives and unknown event frames
+are not decoded or reserialized. The response closes the upstream connection;
+the FastAPI lifespan owns the HTTP client. Application authentication, allowed
+headers, run identity, recovery and replay remain application responsibilities.
+The declared 200 contract must match the reviewed upstream; other upstream status
+codes are preserved and generated SDKs apply their usual HTTP error handling.
+
+From this package directory:
+
+```console
+uv run fastapi-streams schema --app examples.native_proxy:app --output openapi.json
+uv run fastapi-streams generate --schema openapi.json --language python --python-http-client httpx2 --output generated/sse
+uv run fastapi-streams check --schema openapi.json --language python --python-http-client httpx2 --output generated/sse
+```
+
+Keep `openapi.json` as the single authoritative artifact for REST and SSE. If an
+existing REST generator accepts only OpenAPI 3.1, derive a private codegen view:
+
+```console
+uv run python -m examples.rest_codegen openapi.json build/rest.openapi.json
+uv run python -m examples.rest_codegen openapi.json build/rest.openapi.json --check
+```
+
+The [adaptation example](../examples/rest_codegen.py) deep-copies the contract,
+sets the private view to 3.1 and replaces each inline JSON SSE `itemSchema` with
+a media `schema` referencing decoded event data. This keeps event models reachable
+for REST generators that use reachability or schema-tag filtering. That schema
+is a private model-discovery aid, not the SSE wire body. Filter SSE operations out
+of ordinary HTTP method generation and configure your generator's model/tag
+selection explicitly. All components and REST operations remain available.
+
+This recipe handles ordinary REST operations and inline JSON SSE envelopes. It is
+not a general OpenAPI 3.2 downgrade: review additional 3.2 features against the
+chosen REST generator. Unsupported SSE envelope shapes fail explicitly. Never
+publish the private view as the service contract or edit it by hand. Generate it
+from the authoritative artifact before REST generation/drift checks; generate
+and check the SSE SDK directly from the authoritative artifact. Keep HTTP and
+SSE outputs in separate directories. Run both clients' consumer tests.
+
+[Back to code generation](codegen.md)

fastapi_streams-0.3.0/docs/releasing.md

@@ -0,0 +1,13 @@
+# Releasing fastapi-streams
+
+Use the [workspace release process](../../../docs/releases.md). Only root
+workflows execute in this repository; nested workflows and the predecessor
+package-local release script are historical configuration.
+
+Releases use independent `fastapi-streams-vX.Y.Z` tags and the root lockfile.
+Prepare a new version, update the changelog and generated clients, pass the
+workspace and installed-artifact checks, and wait for CI on the exact commit.
+Run the root release workflow with `dry_run=true` before publication. A real
+publication requires explicit authorization.
+
+[Back to documentation](README.md)

{fastapi_streams-0.1.0 → fastapi_streams-0.3.0}/examples/agent_runs/errors.py

@@ -30,7 +30,7 @@ async def consume_with_errors(client: Client, run_id: str) -> None:
         print("Unexpected HTTP response", error.status, error.details)
         raise
     except StreamParseError as error:
-        print("Invalid event data", error.data)
+        print("Invalid event data", error.operation_id, error.category)
         raise
     except TransportError as error:
         print("Stream transport failed", str(error))

{fastapi_streams-0.1.0 → fastapi_streams-0.3.0}/examples/agent_runs/generated_python/agent_runs/api.py

@@ -6,10 +6,17 @@ from collections.abc import AsyncGenerator
 from pydantic import TypeAdapter
 
 from .. import models as Models
-from ..runtime import RequestOptions, Transport, append_query, encode_path
+from ..runtime import RequestOptions, Transport, append_query, encode_path, validate_parameter as _validate_parameter
 
 
 class AgentRunsApi:
+    _stream_prompt_run_id_adapter = TypeAdapter(str)
+    _stream_prompt_body_adapter = TypeAdapter(Models.RunRequest)
+    _stream_prompt_event_adapter = TypeAdapter(Models.RunEvent)
+    _stream_run_events_run_id_adapter = TypeAdapter(str)
+    _stream_run_events_delay_adapter = TypeAdapter(Models.StreamRunEventsDelay)
+    _stream_run_events_event_adapter = TypeAdapter(Models.RunEvent)
+
     def __init__(self, transport: Transport) -> None:
         self._transport = transport
 
@@ -33,18 +40,26 @@ class AgentRunsApi:
 
         Declared HTTP response bodies: StreamPromptErrorBody (422 application/json). HttpError.details may also contain undeclared JSON, text, or no body; validate it before accessing application fields.
 
+        Path, query and header parameters and JSON bodies are validated with Pydantic at the method call, before serialization or HTTP I/O. Optional None parameters are omitted. Pydantic's normal type coercion applies; invalid arguments raise ValidationError.
+
         Use contextlib.aclosing for deterministic cleanup when exiting iteration early. Task cancellation closes the response and propagates normally.
 
-        Events are validated with Pydantic.
+        Events are validated with Pydantic against generated shapes, variants and supported scalar constraints (string pattern/length, numeric bounds/multiples). Unsupported source constraints are diagnosed during generation; this is not full JSON Schema validation.
+
+        Unknown event variants fail by default. For a top-level discriminated union, RequestOptions(unknown_events='ignore') skips unknown string tags. Malformed known events, missing tags and invalid JSON still fail.
+
+        StreamParseError exposes operation_id, category (invalid_json or invalid_event_schema), and validation_errors without input values. Its data and chained cause may contain sensitive content; the SDK does not log them automatically.
         """
+        run_id = _validate_parameter(self._stream_prompt_run_id_adapter, run_id)
         query: list[tuple[str, str]] = []
         headers: dict[str, str] = {}
-        adapter = TypeAdapter(Models.RunRequest)
+        adapter = self._stream_prompt_body_adapter
         content = adapter.dump_json(adapter.validate_python(body), by_alias=True, exclude_unset=True)
         return self._transport.stream(
             '/v1/runs/' + encode_path(run_id) + '/events',
             'POST',
-            TypeAdapter(Models.RunEvent),
+            self._stream_prompt_event_adapter,
+            operation_id='stream_prompt',
             query=query,
             headers=headers,
             body=content,
@@ -55,7 +70,7 @@ class AgentRunsApi:
         self,
         *,
         run_id: str,
-        delay: float | None = None,
+        delay: Models.StreamRunEventsDelay | None = None,
         options: RequestOptions | None = None,
     ) -> AsyncGenerator[Models.RunEvent, None]:
         """
@@ -71,17 +86,27 @@ class AgentRunsApi:
 
         Declared HTTP response bodies: StreamRunEventsErrorBody (422 application/json). HttpError.details may also contain undeclared JSON, text, or no body; validate it before accessing application fields.
 
+        Path, query and header parameters and JSON bodies are validated with Pydantic at the method call, before serialization or HTTP I/O. Optional None parameters are omitted. Pydantic's normal type coercion applies; invalid arguments raise ValidationError.
+
         Use contextlib.aclosing for deterministic cleanup when exiting iteration early. Task cancellation closes the response and propagates normally.
 
-        Events are validated with Pydantic.
+        Events are validated with Pydantic against generated shapes, variants and supported scalar constraints (string pattern/length, numeric bounds/multiples). Unsupported source constraints are diagnosed during generation; this is not full JSON Schema validation.
+
+        Unknown event variants fail by default. For a top-level discriminated union, RequestOptions(unknown_events='ignore') skips unknown string tags. Malformed known events, missing tags and invalid JSON still fail.
+
+        StreamParseError exposes operation_id, category (invalid_json or invalid_event_schema), and validation_errors without input values. Its data and chained cause may contain sensitive content; the SDK does not log them automatically.
         """
+        run_id = _validate_parameter(self._stream_run_events_run_id_adapter, run_id)
+        if delay is not None:
+            delay = _validate_parameter(self._stream_run_events_delay_adapter, delay)
         query: list[tuple[str, str]] = []
         headers: dict[str, str] = {}
         append_query(query, 'delay', delay, explode=True)
         return self._transport.stream(
             '/v1/runs/' + encode_path(run_id) + '/events',
             'GET',
-            TypeAdapter(Models.RunEvent),
+            self._stream_run_events_event_adapter,
+            operation_id='stream_run_events',
             query=query,
             headers=headers,
             options=options,

{fastapi_streams-0.1.0 → fastapi_streams-0.3.0}/examples/agent_runs/generated_python/models.py

@@ -38,7 +38,7 @@ class RunFailed(BaseModel):
 
 class RunRequest(BaseModel):
     model_config = ConfigDict(populate_by_name=True)
-    prompt: str
+    prompt: Annotated[str, Field(max_length=500, min_length=1)]
 
 class RunStarted(BaseModel):
     model_config = ConfigDict(populate_by_name=True)
@@ -49,6 +49,8 @@ type StreamPromptError = HTTPValidationError
 
 type StreamPromptErrorBody = StreamPromptError
 
+type StreamRunEventsDelay = Annotated[float, Field(le=1, ge=0)]
+
 type StreamRunEventsError = HTTPValidationError
 
 type StreamRunEventsErrorBody = StreamRunEventsError