streetworks 0.1.0__tar.gz

streetworks-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q

streetworks-0.1.0/.github/workflows/integration.yml

@@ -0,0 +1,32 @@
+name: Integration tests (live systems)
+
+# Manual only. Hits real test/sandbox systems using credentials stored as
+# repository secrets. Never runs on push/PR, so it can't break normal CI.
+on:
+  workflow_dispatch:
+
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    environment: integration   # optional: gate behind a reviewer
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: pytest -m integration -v
+        env:
+          SM_EMAIL: ${{ secrets.SM_EMAIL }}
+          SM_PASSWORD: ${{ secrets.SM_PASSWORD }}
+          SM_ENV: sandbox
+          SM_VERSION: v6
+          DATAVIA_USER: ${{ secrets.DATAVIA_USER }}
+          DATAVIA_PASSWORD: ${{ secrets.DATAVIA_PASSWORD }}
+          DATAVIA_CLIENT_ID: ${{ secrets.DATAVIA_CLIENT_ID }}
+          DATAVIA_CLIENT_SECRET: ${{ secrets.DATAVIA_CLIENT_SECRET }}
+          DATAVIA_USRN: ${{ secrets.DATAVIA_USRN }}
+          DTRO_CLIENT_ID: ${{ secrets.DTRO_CLIENT_ID }}
+          DTRO_CLIENT_SECRET: ${{ secrets.DTRO_CLIENT_SECRET }}
+          DTRO_APP_ID: ${{ secrets.DTRO_APP_ID }}
+          DTRO_ENV: integration

streetworks-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for PyPI Trusted Publishing (no API token needed)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

streetworks-0.1.0/.github/workflows/regenerate-models.yml

@@ -0,0 +1,43 @@
+name: Regenerate Street Manager models
+
+# Run manually from the Actions tab. Downloads the official swagger specs
+# and opens a PR if the generated Pydantic models changed.
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Street Manager API version"
+        default: "v6"
+        required: true
+      url_template:
+        description: "Swagger spec URL ({api}/{version} placeholders)"
+        default: "https://api.sandbox.manage-roadworks.service.gov.uk/{version}/{api}/docs/swagger.json"
+        required: true
+
+jobs:
+  regenerate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[gen]" httpx
+      - run: |
+          python scripts/generate_models.py \
+            --version "${{ inputs.version }}" \
+            --url-template "${{ inputs.url_template }}"
+      - run: pip install -e ".[dev]" && pytest -q
+      - uses: peter-evans/create-pull-request@v6
+        with:
+          branch: regenerate-models-${{ inputs.version }}
+          title: "Regenerate ${{ inputs.version }} Street Manager models"
+          commit-message: "Regenerate ${{ inputs.version }} models from official swagger specs"
+          body: |
+            Automated regeneration of `streetworks.streetmanager.models.${{ inputs.version }}`
+            from the official DfT swagger specifications.
+
+            Spec source: `${{ inputs.url_template }}`

streetworks-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env

streetworks-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+Initial release.
+
+- `streetworks.streetmanager`: sync + async clients for all nine Street
+  Manager APIs (V6/V7, sandbox/production) with automatic auth, token
+  refresh, retries and rate-limit handling. Explicit `authenticate()` method
+  for fail-fast credential/connectivity checks.
+- Connectivity smoke test (`scripts/smoke_test.py`) and skip-guarded
+  integration test suite (`pytest -m integration`) for verifying against the
+  real test/sandbox systems.
+- `streetworks.opendata`: SNS receiver toolkit — parsing, signature
+  verification, subscription auto-confirmation, event extraction.
+- `streetworks.datavia`: OGC WFS client for Geoplace DataVIA - Basic and
+  OAuth2 client-credentials auth, full NSG layer catalogue, composable
+  OGC filters (USRN, DWithin, Intersects, BBOX, attribute equality),
+  documentation-faithful POST GetFeature bodies, KVP GET, paging iterator,
+  and all documented output formats.
+- `streetworks.dtro`: DfT Digital Traffic Regulation Orders client -
+  OAuth2 client credentials with token caching, integration/production
+  environments, publish (body/file/gzip), retrieve, delete, events search,
+  signed-URL full CSV export, provisions (create/update/delete, with the
+  distinct `App-Id` header), schemas, and search. Token metadata exposed via
+  `token_info`. Verified against the official OpenAPI spec and Postman
+  collection.

streetworks-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing
+
+Thanks for your interest in improving `streetworks`!
+
+## Getting started
+
+```bash
+git clone https://github.com/KFergusonUK/streetworks
+cd streetworks
+pip install -e ".[dev]"
+pytest
+```
+
+## Ground rules
+
+- All tests must run **without credentials** — mock HTTP with `respx`.
+- New endpoints: add a typed method to the relevant API group, with the
+  documented path in the docstring, plus a mocked test.
+- New providers: one module under `src/streetworks/`, built on
+  `streetworks._transport`, raising `streetworks.exceptions` types.
+- Run `ruff check .` before opening a PR.
+
+## Verifying against real services
+
+If you have sandbox credentials for Street Manager or a DataVIA account,
+real-world verification of endpoint paths and payloads is hugely valuable —
+please note in your PR what you verified and against which environment/version.

streetworks-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Ferguson
+
+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.

streetworks-0.1.0/PKG-INFO

@@ -0,0 +1,361 @@
+Metadata-Version: 2.4
+Name: streetworks
+Version: 0.1.0
+Summary: An open SDK for UK street works APIs: DfT Street Manager, Street Manager Open Data (SNS), and Geoplace DataVIA.
+Project-URL: Homepage, https://github.com/KFergusonUK/StreetWorks-SDK
+Project-URL: Documentation, https://github.com/KFergusonUK/StreetWorks-SDK#readme
+Project-URL: Issues, https://github.com/KFergusonUK/StreetWorks-SDK/issues
+Author: Kevin Ferguson
+License: MIT License
+        
+        Copyright (c) 2026 Kevin Ferguson
+        
+        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.
+License-File: LICENSE
+Keywords: datavia,dft,geoplace,highways,nsg,permits,roadworks,street manager,street works,usrn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: cryptography>=42; extra == 'dev'
+Requires-Dist: datamodel-code-generator>=0.25; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: gen
+Requires-Dist: datamodel-code-generator>=0.25; extra == 'gen'
+Provides-Extra: sns
+Requires-Dist: cryptography>=42; extra == 'sns'
+Description-Content-Type: text/markdown
+
+# streetworks
+
+[![CI](https://github.com/KFergusonUK/StreetWorks-SDK/actions/workflows/ci.yml/badge.svg)](https://github.com/KFergusonUK/StreetWorks-SDK/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/streetworks)](https://pypi.org/project/streetworks/)
+[![Python](https://img.shields.io/pypi/pyversions/streetworks)](https://pypi.org/project/streetworks/)
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-green.svg)](LICENSE)
+
+An open Python SDK for UK street works APIs — one consistent, typed,
+well-tested client for the services the sector actually uses.
+
+> We do this not because it is easy, but because it is hard.
+
+```python
+from streetworks.streetmanager import StreetManagerClient, Environment
+
+with StreetManagerClient("api-user@example.com", password, environment=Environment.SANDBOX) as sm:
+    sm.authenticate()                                  # verify credentials
+    submitted = sm.reporting.permits(status="submitted")
+```
+
+| Module | Service | Direction |
+|---|---|---|
+| `streetworks.streetmanager` | [DfT Street Manager](https://department-for-transport-streetmanager.github.io/street-manager-docs/api-documentation/) — all nine APIs (Work, Reporting, Street Lookup, GeoJSON, Party, Data Export, Event, Sampling, Worklist), V6 & V7, sandbox & production | read + write |
+| `streetworks.opendata` | [Street Manager Open Data](https://department-for-transport-streetmanager.github.io/street-manager-docs/open-data/) — AWS SNS push notifications | receive |
+| `streetworks.datavia` | [Geoplace DataVIA](https://datavia.geoplace.co.uk/documentation) — full NSG layer catalogue over OGC WFS (Basic + OAuth2) | read |
+| `streetworks.dtro` | [DfT Digital Traffic Regulation Orders](https://d-tro.dft.gov.uk/api-documentation/) — integration & production | read + write |
+
+Shared across all modules: automatic retries with exponential backoff and
+jitter, `Retry-After`-aware 429 handling, a single exception hierarchy, and
+both **sync and async** clients built on [httpx](https://www.python-httpx.org/).
+
+## What this is (and isn't)
+
+**It is** a typed client library: it handles authentication, token lifecycles,
+retries, rate limiting, pagination, and request/response plumbing for each of
+these APIs, so you call Python methods instead of hand-rolling HTTP. Auth and
+connectivity are verified against the real systems (see **Status** below).
+
+**It isn't** a replacement for the APIs' own documentation. You still bring
+your own credentials (issued by the service operators, not by this SDK) and
+you still need each API's domain concepts — what a permit payload contains,
+what makes a valid USRN filter, which DataVIA layer holds which data. The SDK
+gets you connected and typed; the linked docs tell you what to send.
+
+## Status
+
+Early alpha (`0.1.0`). **Authentication and read/consume access are verified
+against the real systems for all four providers:** Street Manager (SANDBOX),
+Geoplace DataVIA (live — including a real feature query), D-TRO (production
+token + events search), and the Open Data SNS parsing/verification pipeline.
+
+Not yet exercised against live systems — implemented to the published specs
+and covered by mocked tests: the **write/publish** paths (Street Manager work
+submission and assessment; D-TRO create/update and provisions). These are
+publisher-scoped and deliberately excluded from the read-only smoke test.
+
+Known reconciliation items: D-TRO payload models track spec `3.4.x` while
+production is on `3.5.1` (with `4.0.0` due mid-2026); the
+`streetworks.exceptions` API and client method surface may change before
+`1.0`. See [docs/INTEGRATION.md](docs/INTEGRATION.md) for how to verify
+against the real systems yourself. First-contact reports welcome.
+
+## Install
+
+```bash
+pip install streetworks            # core
+pip install "streetworks[sns]"     # + SNS signature verification (cryptography)
+```
+
+Requires Python 3.10+.
+
+## Prerequisites: credentials
+
+Credentials are issued by the service operators. You only need the ones for the
+service(s) you'll use. Keep them in environment variables or a secret manager —
+never in code.
+
+| Service | How to get access | Environment variables |
+|---|---|---|
+| Street Manager | Your organisation's Street Manager admin issues API accounts; [start in sandbox](https://department-for-transport-streetmanager.github.io/street-manager-docs/articles/testing-with-street-manager-sandbox-environment.html) | `SM_EMAIL`, `SM_PASSWORD` |
+| Street Manager Open Data | Register an HTTPS endpoint with DfT to receive the SNS subscription | *(none — you host the receiver)* |
+| DataVIA | A [Geoplace DataVIA](https://datavia.geoplace.co.uk/) account (username/password) or issued OAuth2 client credentials | `DATAVIA_USER` + `DATAVIA_PASSWORD`, or `DATAVIA_CLIENT_ID` + `DATAVIA_CLIENT_SECRET` |
+| D-TRO | Register an application via the [D-TRO service](https://d-tro.dft.gov.uk/) for an app id and OAuth2 client credentials (integration first, then production) | `DTRO_CLIENT_ID`, `DTRO_CLIENT_SECRET`, `DTRO_APP_ID` |
+
+Credentials are **per-environment** — sandbox/integration credentials do not
+work against production, and vice versa.
+
+## Verify your setup
+
+Before writing any code, confirm your credentials and connectivity with the
+included smoke test. It targets the **test** environments by default, is
+read-only, and skips any service you haven't configured:
+
+```bash
+SM_EMAIL='api-user@example.com' SM_PASSWORD='...' python scripts/smoke_test.py
+```
+
+```
+================================================================
+streetworks connectivity smoke test
+TARGET  Street Manager: sandbox
+All checks are READ-ONLY.
+================================================================
+
+  [PASS] Street Manager - authenticated (sandbox/v6), organisation 1355
+  ...
+```
+
+A `FAIL` prints the exact exception, so a wrong credential or environment is
+obvious immediately. See [docs/INTEGRATION.md](docs/INTEGRATION.md) for the
+full variable list and how to (deliberately) target production.
+
+## Street Manager
+
+Authentication, token caching, and refresh (via the Party API, with automatic
+fall-back to re-authentication) are handled for you — following the DfT
+integration guidance: one token, reused, never re-authenticating per call.
+
+```python
+from streetworks.streetmanager import StreetManagerClient, Environment, ApiVersion
+
+with StreetManagerClient(
+    "api-user@example.com",
+    "password",                      # store securely, e.g. environment variable
+    environment=Environment.SANDBOX, # or Environment.PRODUCTION
+    version=ApiVersion.V6,           # or ApiVersion.V7 / ApiVersion.LATEST
+) as sm:
+    # Typed convenience methods for common workflows...
+    work = sm.work.get_work("TSR1591199404915")
+    submitted = sm.reporting.permits(status="submitted")
+    sm.work.assess_permit("TSR1591199404915", "TSR1591199404915-01",
+                          {"assessment_status": "granted", ...})
+
+    # ...and a generic escape hatch for every endpoint we haven't wrapped yet:
+    s58 = sm.work.post("section-58s", json={...})
+    updates = sm.event.works_updates()
+```
+
+Async is a mirror image:
+
+```python
+from streetworks.streetmanager import AsyncStreetManagerClient
+
+async with AsyncStreetManagerClient("api-user@example.com", "password") as sm:
+    permits = await sm.reporting.permits(status="submitted")
+```
+
+> **Environments.** `Environment.SANDBOX` and `Environment.PRODUCTION` are
+> isolated systems with separate credentials. Develop and test against
+> SANDBOX; only point at PRODUCTION once your workflows are proven. The smoke
+> test and integration suite refuse to touch production without an explicit
+> opt-in, so a stray setting can't send you at live data by accident.
+
+### Typed models
+
+Pydantic v2 models generated from the official DfT swagger specifications
+live under `streetworks.streetmanager.models.<version>` and validate any
+client payload:
+
+```python
+from streetworks.streetmanager.models.v6.work import WorkResponse
+
+work = WorkResponse.model_validate(sm.work.get_work("TSR1591199404915"))
+```
+
+To regenerate after a DfT release, run the **Regenerate Street Manager
+models** workflow from the Actions tab (it opens a PR), or locally:
+
+```bash
+pip install -e ".[gen]"
+python scripts/generate_models.py --version v6 --from-dir specs/streetmanager/v6
+```
+
+## Street Manager Open Data (SNS push)
+
+Open Data is a *push* model: Street Manager POSTs event notifications to an
+HTTPS endpoint you host. **The receiver needs no credentials** — messages are
+authenticated with AWS's public signing certificate (fetched over HTTPS), not
+a shared secret, so there's nothing to configure on the SDK side for parsing,
+verifying, or confirming. `streetworks.opendata` handles all of that,
+framework-agnostic:
+
+```python
+from streetworks.opendata import handle
+
+# inside your web handler, with the raw request body:
+event = handle(request_body, expected_topic_arn="arn:aws:sns:eu-west-2:...:...")
+if event is not None:               # None => subscription handshake, auto-confirmed
+    print(event["event_type"], event["object_reference"])
+```
+
+See [`examples/opendata_fastapi.py`](examples/opendata_fastapi.py) for a
+complete FastAPI receiver.
+
+> **Credentials nuance.** *Receiving* Open Data needs no credentials. But note
+> there are two distinct feeds: the fully public **Open Data** feed (this
+> module), and a separate per-organisation **API Notifications** feed whose
+> *subscription* is set up by calling an authenticated Street Manager endpoint
+> (`POST api-notifications/subscribe`) — that setup step needs Street Manager
+> credentials, though the messages, once flowing, are received the same
+> credential-free way. This module handles the receiving side of both.
+
+## Geoplace DataVIA
+
+Basic auth or OAuth2 client credentials (server-to-server), the full NSG layer
+catalogue (`Layer.STREET_LINES`, `ESU_STREETS`, `ESU_ONE_WAY_EXEMPTIONS`, and
+the Interest / Construction / Special Designation layers in all three geometry
+flavours), composable OGC filters, and transparent paging:
+
+```python
+from streetworks.datavia import DataViaClient, Layer, filters
+
+with DataViaClient(username="user", password="pass") as dv:      # or client_id=/client_secret=
+    street = dv.street_by_usrn(4401245)
+    nearby = dv.streets_near_point(-0.138405, 50.825181, 100)    # within 100m
+
+    sed = dv.get_features(
+        Layer.SPECIAL_DESIGNATION_LINES,
+        filter_fragment=filters.and_(
+            filters.intersects_polygon(ring),
+            filters.property_equals("special_designation_code", 3),
+        ),
+    )
+
+    for feature in dv.iter_features(Layer.ESU_STREETS, page_size=500):
+        ...
+```
+
+POST `GetFeature` bodies match the shapes in the DataVIA documentation
+(WFS 1.1.0 + `ogc:Filter`); GET KVP with `startIndex`/`count` is also
+available via `get_features_kvp()`. Output formats: GeoJSON (default),
+OGRGML, SHAPEZIP, CSV, SPATIALITEZIP.
+
+## DfT D-TRO
+
+OAuth2 client credentials (30-minute tokens, cached and renewed
+automatically), `x-app-id` and per-request `X-Correlation-ID` headers handled
+for you:
+
+```python
+from streetworks.dtro import DTROClient, Environment
+
+with DTROClient(client_id, client_secret, app_id=app_id,
+                environment=Environment.INTEGRATION) as dtro:
+    events = dtro.search_events(since="2026-06-01T00:00:00", pageSize=50)
+    record = dtro.get_dtro(events["events"][0]["id"])
+
+    dtro.create_dtro(payload)                          # publisher scope
+    dtro.create_dtro_from_file(big_json, gzip=True)    # large D-TROs
+    signed = dtro.get_all_dtros_url()                  # full CSV extract
+
+    dtro.schema_versions()                             # available schema versions
+    dtro.search({...})                                 # search published D-TROs
+    dtro.create_provisions([...], dtro_id="...")       # provisions (App-Id header handled)
+```
+
+## Design principles
+
+1. **Never block the user.** Typed methods for confirmed, common endpoints;
+   generic `get/post/put/delete` on every API group for everything else.
+2. **Be a good API citizen.** Token reuse, refresh-then-reauth, exponential
+   backoff, honoured `Retry-After` — per the DfT integration guidance.
+3. **Test without credentials, verify with them.** The whole unit suite runs
+   against mocked transports (`respx`) so CI needs no secrets; a separate
+   smoke test and skip-guarded integration suite verify against the real
+   systems when you supply credentials.
+4. **Room to grow.** Each provider is a self-contained module over a shared
+   transport/exception core — adding a new API is additive.
+
+## Roadmap
+
+- [x] Pydantic model generation pipeline for the Street Manager swagger specs
+- [ ] Auto-pagination helpers for the Reporting API
+- [ ] DataVIA WMS support
+- [ ] D-TRO publish models generated from the DfT JSON schemas, version-namespaced
+      (`v3.5.1` to match production, `v4.0.0` to follow) — see [docs/DTRO_SCHEMAS.md](docs/DTRO_SCHEMAS.md)
+- [ ] Scottish Road Works Register (SRWR)?
+- [ ] Ordnance Survey NGD / Linked Identifiers?
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                    # 35 mocked unit tests - no credentials needed
+ruff check .
+```
+
+The unit tests mock the network so they run offline and without credentials.
+To verify the SDK against the **real** test/sandbox systems with your own
+credentials, use the smoke test or the integration suite — see
+[docs/INTEGRATION.md](docs/INTEGRATION.md):
+
+```bash
+python scripts/smoke_test.py     # one read-only call per configured service
+pytest -m integration -v         # same checks, in the test suite
+```
+
+## Licence
+
+MIT. Not affiliated with or endorsed by the Department for Transport or
+Geoplace. Street Manager documentation is © Crown copyright, available under
+the Open Government Licence v3.0.