fastapi-streams 0.0.1__tar.gz

fastapi_streams-0.0.1/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

fastapi_streams-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.9.2"
+          enable-cache: true
+      - run: uv sync --frozen --all-extras
+      - run: npm ci --ignore-scripts
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pyright
+      - run: uv run pylint fastapi_streams
+      - run: uv run pre-commit run --all-files
+      - run: npm run typecheck
+      - run: npm run test:coverage
+      - run: uv run pytest -q --cov --cov-report=term-missing --cov-report=xml:coverage-python.xml
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage-python-${{ matrix.python }}
+          path: |
+            coverage-python.xml
+            coverage-typescript.lcov
+      - run: uv run python scripts/codegen.py --check
+      - run: uv build
+      - run: uv run python scripts/check_package.py

fastapi_streams-0.0.1/.github/workflows/compatibility.yml

@@ -0,0 +1,47 @@
+name: Dependency compatibility
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    - cron: '17 7 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  compatibility:
+    name: ${{ matrix.os }} / Python ${{ matrix.python }} / ${{ matrix.dependencies }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.12', '3.13', '3.14']
+        dependencies: [lowest, latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: npm
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: '0.9.2'
+          enable-cache: true
+      - run: npm ci --ignore-scripts
+      - name: Resolve dependencies and run native FastAPI and client integration tests
+        run: python scripts/test_compat.py --python ${{ matrix.python }} --dependencies ${{ matrix.dependencies }}
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: compatibility-${{ matrix.os }}-${{ matrix.python }}-${{ matrix.dependencies }}
+          include-hidden-files: true
+          path: |
+            .pytest_cache/dependencies-*.txt
+            .pytest_cache/results-*.xml

fastapi_streams-0.0.1/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage*.xml
+coverage*.lcov
+htmlcov/
+dist/
+node_modules/
+tests/typescript/dist/
+*.egg-info/

fastapi_streams-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+minimum_pre_commit_version: '4.0.0'
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: Ruff lint
+        entry: uv run --frozen ruff check
+        language: system
+        types: [python]
+        exclude: ^(examples/agent_runs/generated_python|tests/fixtures/generated_python)/
+      - id: ruff-format
+        name: Ruff format
+        entry: uv run --frozen ruff format --check
+        language: system
+        types: [python]
+        exclude: ^(examples/agent_runs/generated_python|tests/fixtures/generated_python)/
+      - id: pyright
+        name: Pyright
+        entry: uv run --frozen pyright
+        language: system
+        pass_filenames: false
+        types: [python]
+      - id: pylint
+        name: Pylint
+        entry: uv run --frozen pylint fastapi_streams
+        language: system
+        pass_filenames: false
+        files: ^fastapi_streams/.*\.py$
+      - id: typescript
+        name: TypeScript
+        entry: npm run typecheck
+        language: system
+        pass_filenames: false
+        files: \.(ts|json)$
+      - id: codegen
+        name: Generated contract and client drift
+        entry: uv run --frozen python scripts/codegen.py --check
+        language: system
+        pass_filenames: false
+        files: ^(fastapi_streams/|examples/|tests/fixtures/|scripts/codegen\.py|pyproject\.toml|uv\.lock)

fastapi_streams-0.0.1/AGENTS.md

@@ -0,0 +1,11 @@
+# Repository guidance
+
+## Python module layout
+
+In new or edited Python source modules, put the public API (public classes and
+functions) first, immediately after imports and module constants. Define private
+implementation helpers below the public API. Keep the executable `__main__`
+entrypoint at the end of the module.
+
+Generated client files are owned by the generators; update their templates rather
+than editing generated output by hand.

fastapi_streams-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathis Arends
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_streams-0.0.1/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.5
+Name: fastapi-streams
+Version: 0.0.1
+Summary: Typed FastAPI streams with generated TypeScript and Python clients.
+Project-URL: Documentation, https://github.com/mathisarends/fastapi-streams/tree/main/docs
+Project-URL: Source, https://github.com/mathisarends/fastapi-streams
+Project-URL: Issues, https://github.com/mathisarends/fastapi-streams/issues
+Author: Mathis Arends
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: fastapi<1.0,>=0.143.3
+Requires-Dist: pydantic<3,>=2.11.2
+Provides-Extra: codegen
+Requires-Dist: jinja2<4,>=3.1; extra == 'codegen'
+Requires-Dist: jsonschema<5,>=4.23; extra == 'codegen'
+Description-Content-Type: text/markdown
+
+# fastapi-streams
+
+[![CI](https://github.com/mathisarends/fastapi-streams/actions/workflows/ci.yml/badge.svg)](https://github.com/mathisarends/fastapi-streams/actions/workflows/ci.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](pyproject.toml)
+[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**Decorate a FastAPI endpoint. Get typed streaming clients in TypeScript and Python.**
+
+Define your events with Pydantic and add `@router.stream()`. `fastapi-streams`
+turns that definition into an OpenAPI 3.2 stream contract and generated SDKs with
+named event values, typed async iteration, and shared SSE transport code.
+
+```text
+FastAPI decorator → OpenAPI 3.2 → shared HTTP IR → TypeScript + Python clients
+```
+
+## Why this exists
+
+An endpoint labeled `text/event-stream` does not give consumers a typed SDK.
+They still need to know which JSON events arrive, how to parse a fragmented
+stream, and how to stop it cleanly.
+
+OpenAPI 3.2 can describe each SSE event with `itemSchema` and its JSON payload
+with `contentSchema`. `fastapi-streams` connects that contract to both clients,
+so event models, endpoint parameters, and client types come from one definition.
+A CI check catches drift between the Python app, the contract, and generated code.
+
+## 1. Decorate your FastAPI endpoint
+
+Install from GitHub with the optional codegen extra:
+
+```sh
+uv add 'fastapi-streams[codegen] @ git+https://github.com/mathisarends/fastapi-streams.git'
+```
+
+Save this as `app.py`:
+
+```python
+from collections.abc import AsyncIterator
+from typing import Annotated, Literal
+
+from fastapi import FastAPI
+from pydantic import BaseModel, Field
+
+from fastapi_streams import StreamRouter
+
+
+class TokenDelta(BaseModel):
+    type: Literal["token.delta"]
+    text: str
+
+
+class RunCompleted(BaseModel):
+    type: Literal["run.completed"]
+    run_id: str
+
+
+type RunEvent = Annotated[TokenDelta | RunCompleted, Field(discriminator="type")]
+
+router = StreamRouter(prefix="/runs", tags=["agentRuns"])
+
+
+@router.stream("/{run_id}/events", operation_id="stream_run_events")
+async def stream_run_events(run_id: str) -> AsyncIterator[RunEvent]:
+    yield TokenDelta(type="token.delta", text="Hello")
+    yield RunCompleted(type="run.completed", run_id=run_id)
+
+
+app = FastAPI()
+app.include_router(router, prefix="/v1")
+```
+
+The result is `GET /v1/runs/{run_id}/events`. `StreamRouter` extends `APIRouter`:
+normal `Depends`, security dependencies, validation, middleware, and nested
+routers keep working. FastAPI handles SSE framing, serialization, and heartbeats.
+Use `methods=["POST"]` for request-body-driven streams.
+
+## 2. Export once, generate both clients
+
+```sh
+uv run fastapi-streams schema \
+  --app app:app --output openapi.json
+
+uv run fastapi-streams generate \
+  --schema openapi.json --language typescript --output generated/typescript
+
+uv run fastapi-streams generate \
+  --schema openapi.json --language python --output generated/python
+```
+
+These commands import the app and read its contract; no running server is needed.
+The exporter validates OpenAPI 3.2 and the event schemas. Both generators consume
+one HTTP intermediate representation (IR), carrying operations, parameters, and
+event types into the generated SDKs.
+
+## 3. Consume typed events
+
+The `RunEvent` union produces `RunEventType`, with the same named values in both
+languages. The discriminator narrows each event to its matching model.
+
+**TypeScript — Fetch, `AsyncIterable<RunEvent>`, no runtime dependencies:**
+
+```typescript
+import { createClient, RunEventType } from "./generated/typescript/index.js";
+
+const client = createClient({ baseUrl: "http://localhost:8000" });
+
+for await (const event of client.agentRuns.streamRunEvents({ runId: "demo" })) {
+  switch (event.type) {
+    case RunEventType.TOKEN_DELTA:
+      console.log(event.text); // TokenDelta
+      break;
+    case RunEventType.RUN_COMPLETED:
+      console.log(event.run_id); // RunCompleted
+      break;
+    default: {
+      const exhaustive: never = event;
+      throw new Error(`Unexpected event: ${exhaustive}`);
+    }
+  }
+}
+```
+
+**Python — HTTPX, Pydantic models, and `StrEnum` values:**
+
+```python
+import asyncio
+from typing import assert_never
+
+from generated.python import Client, RunEventType
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000") as client:
+        async for event in client.agent_runs.stream_run_events(run_id="demo"):
+            match event.type:
+                case RunEventType.TOKEN_DELTA:
+                    print(event.text)
+                case RunEventType.RUN_COMPLETED:
+                    print(event.run_id)
+                case _:
+                    assert_never(event)
+
+
+asyncio.run(main())
+```
+
+Install `httpx` and `pydantic` in a Python consumer (`uv add httpx pydantic`).
+HTTPX remains the default; opt in to HTTPX2 at generation time with
+`--python-http-client httpx2` and install `httpx2` instead. See
+[Python HTTP library selection](docs/clients.md#python-http-library).
+Both SDKs handle fragmented SSE frames, UTF-8 decoding, HTTP errors, and resource
+cleanup. TypeScript supports `AbortSignal`; Python supports task cancellation and
+explicit async-generator closure. See [client usage](docs/clients.md).
+
+## 4. Catch contract drift in CI
+
+Commit the exported schema and generated clients. Then check the complete chain:
+
+```sh
+uv run fastapi-streams check \
+  --app app:app --schema openapi.json \
+  --language typescript --output generated/typescript
+
+uv run fastapi-streams check \
+  --app app:app --schema openapi.json \
+  --language python --output generated/python
+```
+
+`check` fails if the app's contract changed or generated files are stale. It
+writes nothing and needs no running server. Pair it with TypeScript's compiler
+and Pyright to catch invalid parameters and event access in consumer code.
+
+| Check | What it verifies |
+| --- | --- |
+| Contract validation | OpenAPI structure, JSON Schemas, and local references. |
+| `fastapi-streams check` | App → committed contract → generated client consistency. |
+| TypeScript / Pyright | Parameter types, event fields, and exhaustive narrowing. |
+
+[Codegen and CI reference →](docs/codegen.md)
+
+## Run the complete example
+
+```sh
+git clone https://github.com/mathisarends/fastapi-streams.git
+cd fastapi-streams
+uv sync --all-extras
+npm ci
+uv run uvicorn examples.agent_runs:app --reload
+```
+
+In another terminal:
+
+```sh
+# TypeScript
+npx tsc -p tests/typescript/tsconfig.json
+node tests/typescript/dist/examples/agent_runs/consume.js
+
+# Python
+uv run python -m examples.agent_runs.consume
+```
+
+The example includes GET and authenticated POST streams, both generated SDKs,
+and committed OpenAPI regression fixtures in `tests/fixtures/`. Verify all generated artifacts with
+`uv run python scripts/codegen.py --check`.
+
+## Documentation
+
+| Guide | Topics |
+| --- | --- |
+| [Quickstart](docs/quickstart.md) | Setup, event models, and FastAPI integration. |
+| [Contracts and codegen](docs/codegen.md) | OpenAPI 3.2, both generators, and drift checks. |
+| [Client usage](docs/clients.md) | Enums, authentication, cancellation, and errors. |
+| [Architecture](docs/architecture.md) | Native SSE, shared IR, templates, and transports. |
+| [Development](docs/development.md) | Tests, supported scope, and roadmap. |
+
+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).
+
+Python 3.12+ · FastAPI 0.143.3+ · Pydantic v2 · [MIT](LICENSE)

fastapi_streams-0.0.1/README.md

@@ -0,0 +1,220 @@
+# fastapi-streams
+
+[![CI](https://github.com/mathisarends/fastapi-streams/actions/workflows/ci.yml/badge.svg)](https://github.com/mathisarends/fastapi-streams/actions/workflows/ci.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](pyproject.toml)
+[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**Decorate a FastAPI endpoint. Get typed streaming clients in TypeScript and Python.**
+
+Define your events with Pydantic and add `@router.stream()`. `fastapi-streams`
+turns that definition into an OpenAPI 3.2 stream contract and generated SDKs with
+named event values, typed async iteration, and shared SSE transport code.
+
+```text
+FastAPI decorator → OpenAPI 3.2 → shared HTTP IR → TypeScript + Python clients
+```
+
+## Why this exists
+
+An endpoint labeled `text/event-stream` does not give consumers a typed SDK.
+They still need to know which JSON events arrive, how to parse a fragmented
+stream, and how to stop it cleanly.
+
+OpenAPI 3.2 can describe each SSE event with `itemSchema` and its JSON payload
+with `contentSchema`. `fastapi-streams` connects that contract to both clients,
+so event models, endpoint parameters, and client types come from one definition.
+A CI check catches drift between the Python app, the contract, and generated code.
+
+## 1. Decorate your FastAPI endpoint
+
+Install from GitHub with the optional codegen extra:
+
+```sh
+uv add 'fastapi-streams[codegen] @ git+https://github.com/mathisarends/fastapi-streams.git'
+```
+
+Save this as `app.py`:
+
+```python
+from collections.abc import AsyncIterator
+from typing import Annotated, Literal
+
+from fastapi import FastAPI
+from pydantic import BaseModel, Field
+
+from fastapi_streams import StreamRouter
+
+
+class TokenDelta(BaseModel):
+    type: Literal["token.delta"]
+    text: str
+
+
+class RunCompleted(BaseModel):
+    type: Literal["run.completed"]
+    run_id: str
+
+
+type RunEvent = Annotated[TokenDelta | RunCompleted, Field(discriminator="type")]
+
+router = StreamRouter(prefix="/runs", tags=["agentRuns"])
+
+
+@router.stream("/{run_id}/events", operation_id="stream_run_events")
+async def stream_run_events(run_id: str) -> AsyncIterator[RunEvent]:
+    yield TokenDelta(type="token.delta", text="Hello")
+    yield RunCompleted(type="run.completed", run_id=run_id)
+
+
+app = FastAPI()
+app.include_router(router, prefix="/v1")
+```
+
+The result is `GET /v1/runs/{run_id}/events`. `StreamRouter` extends `APIRouter`:
+normal `Depends`, security dependencies, validation, middleware, and nested
+routers keep working. FastAPI handles SSE framing, serialization, and heartbeats.
+Use `methods=["POST"]` for request-body-driven streams.
+
+## 2. Export once, generate both clients
+
+```sh
+uv run fastapi-streams schema \
+  --app app:app --output openapi.json
+
+uv run fastapi-streams generate \
+  --schema openapi.json --language typescript --output generated/typescript
+
+uv run fastapi-streams generate \
+  --schema openapi.json --language python --output generated/python
+```
+
+These commands import the app and read its contract; no running server is needed.
+The exporter validates OpenAPI 3.2 and the event schemas. Both generators consume
+one HTTP intermediate representation (IR), carrying operations, parameters, and
+event types into the generated SDKs.
+
+## 3. Consume typed events
+
+The `RunEvent` union produces `RunEventType`, with the same named values in both
+languages. The discriminator narrows each event to its matching model.
+
+**TypeScript — Fetch, `AsyncIterable<RunEvent>`, no runtime dependencies:**
+
+```typescript
+import { createClient, RunEventType } from "./generated/typescript/index.js";
+
+const client = createClient({ baseUrl: "http://localhost:8000" });
+
+for await (const event of client.agentRuns.streamRunEvents({ runId: "demo" })) {
+  switch (event.type) {
+    case RunEventType.TOKEN_DELTA:
+      console.log(event.text); // TokenDelta
+      break;
+    case RunEventType.RUN_COMPLETED:
+      console.log(event.run_id); // RunCompleted
+      break;
+    default: {
+      const exhaustive: never = event;
+      throw new Error(`Unexpected event: ${exhaustive}`);
+    }
+  }
+}
+```
+
+**Python — HTTPX, Pydantic models, and `StrEnum` values:**
+
+```python
+import asyncio
+from typing import assert_never
+
+from generated.python import Client, RunEventType
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000") as client:
+        async for event in client.agent_runs.stream_run_events(run_id="demo"):
+            match event.type:
+                case RunEventType.TOKEN_DELTA:
+                    print(event.text)
+                case RunEventType.RUN_COMPLETED:
+                    print(event.run_id)
+                case _:
+                    assert_never(event)
+
+
+asyncio.run(main())
+```
+
+Install `httpx` and `pydantic` in a Python consumer (`uv add httpx pydantic`).
+HTTPX remains the default; opt in to HTTPX2 at generation time with
+`--python-http-client httpx2` and install `httpx2` instead. See
+[Python HTTP library selection](docs/clients.md#python-http-library).
+Both SDKs handle fragmented SSE frames, UTF-8 decoding, HTTP errors, and resource
+cleanup. TypeScript supports `AbortSignal`; Python supports task cancellation and
+explicit async-generator closure. See [client usage](docs/clients.md).
+
+## 4. Catch contract drift in CI
+
+Commit the exported schema and generated clients. Then check the complete chain:
+
+```sh
+uv run fastapi-streams check \
+  --app app:app --schema openapi.json \
+  --language typescript --output generated/typescript
+
+uv run fastapi-streams check \
+  --app app:app --schema openapi.json \
+  --language python --output generated/python
+```
+
+`check` fails if the app's contract changed or generated files are stale. It
+writes nothing and needs no running server. Pair it with TypeScript's compiler
+and Pyright to catch invalid parameters and event access in consumer code.
+
+| Check | What it verifies |
+| --- | --- |
+| Contract validation | OpenAPI structure, JSON Schemas, and local references. |
+| `fastapi-streams check` | App → committed contract → generated client consistency. |
+| TypeScript / Pyright | Parameter types, event fields, and exhaustive narrowing. |
+
+[Codegen and CI reference →](docs/codegen.md)
+
+## Run the complete example
+
+```sh
+git clone https://github.com/mathisarends/fastapi-streams.git
+cd fastapi-streams
+uv sync --all-extras
+npm ci
+uv run uvicorn examples.agent_runs:app --reload
+```
+
+In another terminal:
+
+```sh
+# TypeScript
+npx tsc -p tests/typescript/tsconfig.json
+node tests/typescript/dist/examples/agent_runs/consume.js
+
+# Python
+uv run python -m examples.agent_runs.consume
+```
+
+The example includes GET and authenticated POST streams, both generated SDKs,
+and committed OpenAPI regression fixtures in `tests/fixtures/`. Verify all generated artifacts with
+`uv run python scripts/codegen.py --check`.
+
+## Documentation
+
+| Guide | Topics |
+| --- | --- |
+| [Quickstart](docs/quickstart.md) | Setup, event models, and FastAPI integration. |
+| [Contracts and codegen](docs/codegen.md) | OpenAPI 3.2, both generators, and drift checks. |
+| [Client usage](docs/clients.md) | Enums, authentication, cancellation, and errors. |
+| [Architecture](docs/architecture.md) | Native SSE, shared IR, templates, and transports. |
+| [Development](docs/development.md) | Tests, supported scope, and roadmap. |
+
+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).
+
+Python 3.12+ · FastAPI 0.143.3+ · Pydantic v2 · [MIT](LICENSE)

fastapi_streams-0.0.1/docs/README.md

@@ -0,0 +1,27 @@
+# Documentation
+
+Define typed events in FastAPI, export their OpenAPI 3.2 contract, and generate
+TypeScript Fetch and Python HTTPX clients from the same definitions.
+
+| Guide | What you will find |
+| --- | --- |
+| [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. |
+| [Client usage](clients.md) | Named event values, typed iteration, authentication, cancellation, and errors. |
+| [Development](development.md) | Local checks, test coverage, supported features, and roadmap. |
+| [Architecture](architecture.md) | Server integration, shared IR, generation, and transport boundaries. |
+
+Start with the [quickstart](quickstart.md), then use the
+[codegen guide](codegen.md) to integrate the clients into your project.
+
+Python 3.12+, FastAPI 0.143.3+, and Pydantic v2 are required. Code generation is
+an optional extra: `fastapi-streams[codegen]`. No running server is needed to
+export contracts or generate clients.
+
+The [example application](../examples/agent_runs/__init__.py) includes GET and
+authenticated POST streams. Its [TypeScript](../examples/agent_runs/consume.ts)
+and [Python](../examples/agent_runs/consume.py) consumers demonstrate the complete
+journey. Generated clients and the [contract fixture](../tests/fixtures/agent_runs.openapi.json)
+are committed so you can inspect their output.
+
+[Back to the project](../README.md)