release: ferrolabsai 0.3.0 — align with the ai-gateway v1.4.5 contract

.github/copilot-instructions.md

@@ -3,31 +3,32 @@
 ## Build, test, and lint commands
 
 - Install dev dependencies: `make install` or `pip install -e ".[dev]"`
-- Run the full test suite: `make test` or `pytest tests/ -v`
-- Run a single test: `pytest tests/test_sdk.py::TestChatCompletions::test_basic_create -v`
-- Run a subset of tests by name: `pytest tests/test_sdk.py -k streaming -v`
+- Run the full test suite: `make test` or `pytest tests/ -v` (the `tests/contract` dir auto-skips without a gateway)
+- Run a single test: `pytest tests/test_chat.py::TestCreate::test_basic_create -v`
+- Run a subset of tests by name: `pytest tests/test_chat.py -k streaming -v`
+- Run the contract suite against a real gateway: `make contract` (builds `ferrogw` from `../ai-gateway`)
 - Lint and type-check: `make lint` or `ruff check ferrolabsai tests && mypy ferrolabsai`
 - Format: `make format` or `ruff format ferrolabsai tests`
 - Build the package: `make build` or `python3 -m build`
 
 ## High-level architecture
 
-- `ferrolabsai/client.py` is the hub. It resolves API keys from `FERRO_API_KEY` with fallback to `OPENAI_API_KEY`, resolves `FERRO_BASE_URL` with a default of `http://localhost:8080`, owns the shared `httpx` client, applies retry/error handling, and wires the public namespaces.
-- Public SDK namespaces intentionally mirror the OpenAI SDK and the gateway HTTP surface: `client.chat.completions`, `client.embeddings`, `client.images`, `client.models`, and `client.admin.*`.
+- `ferrolabsai/client.py` is the hub. It resolves API keys from `FERRO_API_KEY` with fallback to `OPENAI_API_KEY`, resolves `FERRO_BASE_URL` with a default of `http://localhost:8080`, owns the shared `httpx` client, applies the retry policy (connect/timeout/408/429/5xx with jitter and `Retry-After`) and error mapping, merges the gateway's response headers into inference bodies, and wires the public namespaces. `ferrolabsai/streaming.py` wraps SSE responses in `Stream`/`AsyncStream`.
+- Public SDK namespaces intentionally mirror the OpenAI SDK and the gateway HTTP surface: `client.chat.completions`, `client.embeddings`, `client.images`, `client.models`, `client.responses`, `client.moderations`, `client.rerank()`, the probes `client.health()/ready()/live()/capabilities()`, and `client.admin.*`.
 - Resource modules are thin request builders. Each `ferrolabsai/<domain>/resource.py` file translates Python kwargs into the corresponding gateway request and delegates transport to `FerroClient._request(...)` or the streaming helpers instead of managing `httpx` behavior itself.
-- `ferrolabsai/types.py` is the response normalization layer. Gateway JSON is converted into dataclasses there, including OpenAI-compatible fields plus Ferro-specific extras like `provider`, `trace_id`, `latency_ms`, `cost_usd`, and raw gateway config payloads.
-- Admin support is a direct wrapper around `/admin/*` endpoints. The `Admin` namespace groups sub-resources for keys, config, logs, providers, and plugins, and some admin methods intentionally return raw dict payloads when the gateway response shape is still loosely structured.
-- Tests in `tests/test_sdk.py` are request/response contract tests around the HTTP layer. They use `pytest-httpx` to verify headers, payloads, path routing, SSE streaming parsing, env-var fallbacks, retry validation, and admin endpoint behavior without requiring a live gateway.
+- `ferrolabsai/types.py` is the response normalization layer. Gateway JSON is converted into dataclasses there, including OpenAI-compatible fields plus the gateway's real extensions: `provider`, `trace_id` (`X-Request-ID`), `gateway_overhead_ms` (`X-Gateway-Overhead-Ms`), `provider_metadata`, `reasoning_content`, the extra usage counters, and raw gateway config payloads. There is no cost, cache-hit, or latency field — the gateway does not expose them to callers.
+- Admin support is a direct wrapper around `/admin/*` endpoints. The `Admin` namespace groups sub-resources for keys, config, logs, providers, plugins, and audit, and some admin methods intentionally return raw dict payloads when the gateway response shape is still loosely structured.
+- Unit tests in `tests/test_{client,chat,resources,admin}.py` are request/response tests around the HTTP layer. They use `pytest-httpx` to verify headers, payloads, path routing, SSE streaming parsing, env-var fallbacks, the retry policy, and admin endpoint behavior without requiring a live gateway. `tests/contract/` runs the same claims against a real gateway booted by `scripts/with-gateway.sh`.
 
 ## Key conventions
 
 - Target Python 3.9 syntax. New modules should use `from __future__ import annotations`, public functions and methods are expected to be fully typed, and changes should stay compatible with the repo's `mypy --strict` setup.
 - Ruff is both the linter and formatter here. Keep changes aligned with the existing 100-character line length and prefer the repo's Ruff formatting over hand-formatting.
 - Preserve the OpenAI-style surface first. New capabilities should usually be exposed as additional kwargs on existing resource methods or as new resource namespaces that match gateway routes, not as a parallel custom API shape.
-- Ferro-only request features are forwarded as request fields, not wrapped in separate helper abstractions. Existing examples are `template_id` and `template_variables`; sync chat completions also map `route_tag` to `x_route_tag`, but async parity is not complete yet.
+- Only send request fields the gateway actually decodes (`internal/handler/chatrequest.go`). `max_completion_tokens`, `parallel_tool_calls`, `response_format`, `stream_options`, `seed` are first-class; anything else passes through `**kwargs` verbatim. Do not reintroduce the old routing-tag / prompt-template request fields — the gateway never read them.
 - Keep resource classes thin. Shared behavior such as retries, auth headers, connection handling, status-code mapping, and HTTP client lifecycle belongs in `client.py`, not duplicated across resource modules.
 - Public resource methods should return typed dataclasses parsed via `from_dict(...)` helpers in `types.py` unless the endpoint is intentionally passthrough admin data.
 - Error translation is centralized in `_raise_api_error(...)`. Extend the existing `Ferro*Error` hierarchy instead of leaking raw `httpx` exceptions from public SDK methods.
-- Async support is added explicitly per namespace. Today `AsyncFerroClient` wires `chat.completions` and `embeddings`; if you add async support elsewhere, create the matching `async_resource.py`, register it in `AsyncFerroClient`, and add async tests.
+- Async support is added explicitly per namespace. Every namespace has an `async_resource.py` that reuses the sync module's body builders and path constants; if you add a namespace, create both, register them in `FerroClient` and `AsyncFerroClient`, and add async tests.
 - When adding public clients, exceptions, or response types, update `ferrolabsai/__init__.py` and `__all__` so the package surface stays explicit and importable from the top level.
-- Tests should mock HTTP precisely with `pytest_httpx.HTTPXMock` and assert the exact outgoing request shape, especially auth headers, routed endpoint paths, Ferro-specific fields, and SSE frames ending with `data: [DONE]`.
+- Tests should mock HTTP precisely with `pytest_httpx.HTTPXMock` and assert the exact outgoing request shape, especially auth headers, routed endpoint paths, and SSE frames ending with `data: [DONE]`. Anything that claims a gateway behaviour also needs an assertion in `tests/contract/test_contract.py`.

.github/workflows/ci.yml

@@ -9,17 +9,22 @@ on:
   pull_request:
     branches: [main, development]
 
+permissions:
+  contents: read
+
 jobs:
   test:
     name: Test (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
@@ -31,19 +36,65 @@ jobs:
           pip install -e ".[dev]"
 
       - name: Lint
-        run: ruff check ferrolabsai/
+        run: ruff check ferrolabsai/ tests/ && ruff format --check ferrolabsai/ tests/
 
       - name: Type check
-        run: mypy ferrolabsai/ --ignore-missing-imports
-        # Only enforce strict types on 3.11+
-        if: matrix.python-version == '3.11'
+        run: mypy ferrolabsai/
 
       - name: Run tests
         run: pytest tests/ -v --tb=short
 
+  contract:
+    name: Contract vs AI Gateway ${{ matrix.label }}
+    runs-on: ubuntu-latest
+    # The pinned leg is the required signal; "main" moves upstream of this
+    # repo, so a failure there must only report drift, never block a merge or
+    # a tagged release.
+    continue-on-error: ${{ matrix.gateway_ref == 'main' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # The pin is the commit SHA behind the tag so a moved tag cannot change
+          # what a release is verified against; `label` keeps the check name
+          # stable ("Contract vs AI Gateway v1.4.5"), which the publish job and
+          # the branch protection rules reference.
+          - gateway_ref: e8e4e26ddbd1dcf734722d82f02fabb50ce50037  # v1.4.5
+            label: v1.4.5
+          - gateway_ref: main
+            label: main
+    steps:
+      - name: Check out ferrolabs-python-sdk
+        uses: actions/checkout@v4
+        with:
+          path: ferrolabs-python-sdk
+          persist-credentials: false
+      - name: Check out AI Gateway
+        uses: actions/checkout@v4
+        with:
+          repository: ferro-labs/ai-gateway
+          ref: ${{ matrix.gateway_ref }}
+          path: ai-gateway
+          persist-credentials: false
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: ai-gateway/go.mod
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install the SDK
+        run: pip install -e ".[dev]"
+        working-directory: ferrolabs-python-sdk
+      - name: Boot the gateway and run the contract suite
+        run: ./scripts/with-gateway.sh
+        working-directory: ferrolabs-python-sdk
+        env:
+          FERRO_GATEWAY_SOURCE: ${{ github.workspace }}/ai-gateway
+
   publish:
     name: Publish to PyPI
-    needs: test
+    # A release must pass the unit matrix and the pinned-gateway contract leg.
+    needs: [test, contract]
     runs-on: ubuntu-latest
     # Only run on semver tag pushes (see `on.push.tags` above).
     if: startsWith(github.ref, 'refs/tags/v')
@@ -62,6 +113,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
 
       - name: Set up Python
         uses: actions/setup-python@v5

.github/workflows/publish-langchain-ferrolabsai.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     defaults:
       run:
@@ -41,7 +41,6 @@ jobs:
 
       - name: Type check
         run: mypy langchain_ferrolabsai/ --ignore-missing-imports
-        if: matrix.python-version == '3.11'
 
       - name: Run tests
         run: pytest tests/ -v --tb=short