bbfmodels 0.2.1__tar.gz → 0.4.0__tar.gz

bbfmodels-0.4.0/.github/workflows/announce-release.yml

@@ -0,0 +1,70 @@
+name: announce-release
+
+# Posts a release's notes to the ispx Discord when they land on main.
+# release-notes/<version>.md is written after the Release PR merges and
+# lands by its own PR, so the notes file
+# arriving on main is the moment the release is told, and only a file
+# added by the push counts: an edit to existing notes is a wording fix,
+# not a release. The dispatch input re-posts one version by hand, which
+# is also how the webhook is tried out.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "release-notes/**"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Version whose notes to post, for example 0.2.1
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: announce-release
+  cancel-in-progress: false
+
+jobs:
+  announce:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Find the versions to post
+        id: versions
+        env:
+          BEFORE: ${{ github.event.before }}
+          REQUESTED: ${{ inputs.version }}
+        run: |
+          if [ -n "$REQUESTED" ]; then
+            versions="$REQUESTED"
+          else
+            git fetch --quiet --depth=1 origin "$BEFORE"
+            versions=$(git diff --name-only --diff-filter=A "$BEFORE" "$GITHUB_SHA" -- release-notes/ \
+              | sed -n 's#^release-notes/\(.*\)\.md$#\1#p' | sort -V | tr '\n' ' ')
+          fi
+          echo "list=$versions" >> "$GITHUB_OUTPUT"
+          echo "versions: ${versions:-none}"
+
+      - name: Post the notes
+        if: steps.versions.outputs.list != ''
+        env:
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_RELEASES_WEBHOOK }}
+          VERSIONS: ${{ steps.versions.outputs.list }}
+        run: |
+          if [ -z "$DISCORD_WEBHOOK_URL" ]; then
+            echo "::warning::DISCORD_RELEASES_WEBHOOK is not set, nothing posted"
+            exit 0
+          fi
+          for v in $VERSIONS; do
+            python hooks/announce.py "$v"
+          done

bbfmodels-0.4.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.0"
+}

bbfmodels-0.4.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## [0.4.0](https://github.com/ispx-limited/bbfmodels/compare/v0.3.0...v0.4.0) (2026-11-02)
+
+
+### Added
+
+* **models:** USP commands and events as classes and paths, and the xsi:type a CWMP stack needs ([#20](https://github.com/ispx-limited/bbfmodels/issues/20)) ([eca0c46](https://github.com/ispx-limited/bbfmodels/commit/eca0c46a10c6fc205dbc198d051dbb860f321003))
+
+## [0.3.0](https://github.com/ispx-limited/bbfmodels/compare/v0.2.1...v0.3.0) (2026-11-02)
+
+
+### Added
+
+* **paths:** typed paths with autocomplete for every model, no pydantic model needed ([#17](https://github.com/ispx-limited/bbfmodels/issues/17)) ([ba3a7b7](https://github.com/ispx-limited/bbfmodels/commit/ba3a7b7781129477aed7ee015d51f9079521b331))
+
+## [0.2.1](https://github.com/ispx-limited/bbfmodels/compare/v0.2.0...v0.2.1) (2026-11-02)
+
+
+### Fixed
+
+* **models:** generated files no longer record the tool version, which broke the release build ([#10](https://github.com/ispx-limited/bbfmodels/issues/10)) ([ab909c7](https://github.com/ispx-limited/bbfmodels/commit/ab909c7d67b102b11f09122d8c01cea674859e8c))
+* **parser:** a vendor document's empty syntax is read as a string instead of failing ([#11](https://github.com/ispx-limited/bbfmodels/issues/11)) ([7cdb4a1](https://github.com/ispx-limited/bbfmodels/commit/7cdb4a1c4fa39b7741c90a67c84b43812c889fe2))
+* **parser:** a vendor document's unknown vocabulary values fall back with a warning instead of failing ([#13](https://github.com/ispx-limited/bbfmodels/issues/13)) ([bb3e807](https://github.com/ispx-limited/bbfmodels/commit/bb3e80723320fdd69d2b2263ef066d790a28feb2))
+
+## [0.2.0](https://github.com/ispx-limited/bbfmodels/compare/v0.1.0...v0.2.0) (2026-11-02)
+
+
+### Added
+
+* **models:** generated pydantic models for every published data model, and a generator for any document ([#7](https://github.com/ispx-limited/bbfmodels/issues/7)) ([adf73f2](https://github.com/ispx-limited/bbfmodels/commit/adf73f2004eb7cf24673a52298a251af45f39364))
+
+## 0.1.0 (2026-11-02)
+
+
+### Added
+
+* **parser:** read a published document into the intermediate representation ([#1](https://github.com/ispx-limited/bbfmodels/issues/1)) ([462d045](https://github.com/ispx-limited/bbfmodels/commit/462d04530a7d3a7d62a3da440404f4afcadb2c4f))
+* **runtime:** resolve paths, hold a device's values and validate them against the schema ([#3](https://github.com/ispx-limited/bbfmodels/issues/3)) ([35146ad](https://github.com/ispx-limited/bbfmodels/commit/35146adb52757ac9a05836415f87815135c55b94))

bbfmodels-0.4.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: bbfmodels
+Version: 0.4.0
+Summary: Typed models and schema tooling for Broadband Forum data models (TR-181, TR-098, TR-104 and more), generated from the published XML
+Project-URL: Homepage, https://github.com/ispx-limited/bbfmodels
+Project-URL: Documentation, https://docs.bbfmodels.ispx.co/
+Project-URL: Changelog, https://docs.bbfmodels.ispx.co/changelog/
+Author: ISPX LIMITED
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: broadband-forum,cwmp,data-model,tr-069,tr-098,tr-181,tr-369,usp
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.14
+Description-Content-Type: text/markdown
+
+# bbfmodels
+
+Typed models and schema tooling for Broadband Forum data models (TR-181,
+TR-098, TR-104 and the rest), generated from the XML the Forum publishes.
+
+The Forum defines what a broadband gateway exposes to its management system
+as XML in the TR-106 schema: thousands of objects and parameters, their types,
+ranges, enumerations, writability and multi-instance tables. Everyone who
+builds against those models, an ACS, a USP controller, a device simulator, an
+integration script, re-derives the same facts from the same XML and hand-types
+the same parameter paths as strings. bbfmodels does it once:
+
+- A parser that reads the published XML into a normalised intermediate
+  representation, published as JSON with its own schema.
+- A Python runtime that works from that representation: resolve a path,
+  validate a value against the model's constraints, convert between the flat
+  path and value lists that CWMP and USP carry on the wire and a typed tree.
+- Generated typed bindings: pydantic models for Python, shipped for TR-181
+  and TR-098 and the service models (TR-104 voice, TR-135 set-top box,
+  TR-140 storage, TR-196 femtocell, TR-517 Matter), and generated on demand
+  for any other document, a vendor's included.
+- Typed paths for code that only needs correct path strings:
+  `str(Device.WiFi.SSID[1].SSID)` with autocomplete over the whole model
+  and the parameter's definition one attribute away. JSON Schema and TypeScript follow from the
+  same representation, Go when there is a consumer.
+
+Names stay as the Forum wrote them. `Device.WiFi.SSID.{i}.SSID` is a table of
+`SSID` entries indexed by instance number, and the attribute is `SSID`, not
+`ssid`.
+
+## Install
+
+```sh
+pip install bbfmodels
+```
+
+Python 3.11 or later. The one runtime dependency is pydantic.
+
+## Status
+
+Early. The parser, the intermediate representation, the runtime, the
+generated Python models with USP commands and events, and typed paths are
+in place. JSON Schema and TypeScript come next. Before 1.0 a minor release
+may change the IR and the runtime API.
+
+```python
+from bbfmodels.tr181_cwmp import Device
+
+device = Device.from_flat(values_from_the_device)
+radio = device.WiFi.Radio[1]
+radio.Channel  # 36, an int
+radio.Enable  # True
+device.problems()  # every value outside the model's constraints
+device.flatten()  # back to path and text pairs
+```
+
+The design decisions behind the code are in `context/decisions/`, indexed in
+`context/README.md`. Read them before changing the parser or the IR.
+
+## Development
+
+Prerequisites: git and [uv](https://docs.astral.sh/uv/). The pinned Python is
+installed by uv.
+
+```sh
+scripts/bootstrap.sh
+make test
+make lint
+```
+
+`make help` lists the rest. Documentation is built from `docs/` with
+`make docs` and published at https://docs.bbfmodels.ispx.co/.
+
+## Licence
+
+Apache-2.0, copyright ISPX LIMITED. The Broadband Forum publishes its data
+models under the BSD 3-clause licence; output derived from them carries the
+Forum's notice.

bbfmodels-0.4.0/README.md

@@ -0,0 +1,78 @@
+# bbfmodels
+
+Typed models and schema tooling for Broadband Forum data models (TR-181,
+TR-098, TR-104 and the rest), generated from the XML the Forum publishes.
+
+The Forum defines what a broadband gateway exposes to its management system
+as XML in the TR-106 schema: thousands of objects and parameters, their types,
+ranges, enumerations, writability and multi-instance tables. Everyone who
+builds against those models, an ACS, a USP controller, a device simulator, an
+integration script, re-derives the same facts from the same XML and hand-types
+the same parameter paths as strings. bbfmodels does it once:
+
+- A parser that reads the published XML into a normalised intermediate
+  representation, published as JSON with its own schema.
+- A Python runtime that works from that representation: resolve a path,
+  validate a value against the model's constraints, convert between the flat
+  path and value lists that CWMP and USP carry on the wire and a typed tree.
+- Generated typed bindings: pydantic models for Python, shipped for TR-181
+  and TR-098 and the service models (TR-104 voice, TR-135 set-top box,
+  TR-140 storage, TR-196 femtocell, TR-517 Matter), and generated on demand
+  for any other document, a vendor's included.
+- Typed paths for code that only needs correct path strings:
+  `str(Device.WiFi.SSID[1].SSID)` with autocomplete over the whole model
+  and the parameter's definition one attribute away. JSON Schema and TypeScript follow from the
+  same representation, Go when there is a consumer.
+
+Names stay as the Forum wrote them. `Device.WiFi.SSID.{i}.SSID` is a table of
+`SSID` entries indexed by instance number, and the attribute is `SSID`, not
+`ssid`.
+
+## Install
+
+```sh
+pip install bbfmodels
+```
+
+Python 3.11 or later. The one runtime dependency is pydantic.
+
+## Status
+
+Early. The parser, the intermediate representation, the runtime, the
+generated Python models with USP commands and events, and typed paths are
+in place. JSON Schema and TypeScript come next. Before 1.0 a minor release
+may change the IR and the runtime API.
+
+```python
+from bbfmodels.tr181_cwmp import Device
+
+device = Device.from_flat(values_from_the_device)
+radio = device.WiFi.Radio[1]
+radio.Channel  # 36, an int
+radio.Enable  # True
+device.problems()  # every value outside the model's constraints
+device.flatten()  # back to path and text pairs
+```
+
+The design decisions behind the code are in `context/decisions/`, indexed in
+`context/README.md`. Read them before changing the parser or the IR.
+
+## Development
+
+Prerequisites: git and [uv](https://docs.astral.sh/uv/). The pinned Python is
+installed by uv.
+
+```sh
+scripts/bootstrap.sh
+make test
+make lint
+```
+
+`make help` lists the rest. Documentation is built from `docs/` with
+`make docs` and published at https://docs.bbfmodels.ispx.co/.
+
+## Licence
+
+Apache-2.0, copyright ISPX LIMITED. The Broadband Forum publishes its data
+models under the BSD 3-clause licence; output derived from them carries the
+Forum's notice.

bbfmodels-0.4.0/context/README.md

@@ -0,0 +1,25 @@
+# Design memory
+
+This directory is the project's design memory: the decisions that shape
+the code and the reasons behind them, so a contributor, or a coding agent
+working with one, can change the code without undoing a decision by
+accident. Read it before touching the parser, the IR or a generator.
+
+`decisions/` holds one record per significant decision: context, decision,
+consequences, in a page or less. Records are append-only. When a decision
+changes, a new record is written and the old one is marked superseded.
+
+| Number | Title | Status |
+| --- | --- | --- |
+| [0001](decisions/0001-one-parser-one-ir-several-emitters.md) | One parser, one intermediate representation, several emitters | Accepted |
+| [0002](decisions/0002-names-stay-as-the-forum-wrote-them.md) | Names stay as the Forum wrote them | Accepted |
+| [0003](decisions/0003-parse-the-flattened-full-documents.md) | Parse the Forum's flattened full documents | Accepted |
+| [0004](decisions/0004-generated-output-is-committed.md) | Generated output is committed and checked for drift | Accepted |
+| [0005](decisions/0005-python-models-are-pydantic.md) | Generated Python models are pydantic, built lazily per subtree | Accepted |
+| [0006](decisions/0006-everything-optional-unknown-paths-kept.md) | Everything is optional and unknown paths round-trip | Accepted |
+| [0007](decisions/0007-vendor-extensions-are-overlays.md) | Vendor extensions are overlays in the same schema | Accepted |
+| [0008](decisions/0008-python-toolchain.md) | Python toolchain: uv, ruff, mypy, pytest, standard library XML | Accepted |
+| [0009](decisions/0009-the-tree-keeps-wire-text.md) | The data tree keeps wire text and decodes on demand | Accepted |
+| [0010](decisions/0010-generated-python-packages.md) | One generated package per document, lenient on input, strict in `problems` | Accepted |
+| [0011](decisions/0011-typed-paths-are-a-stub-over-the-schema.md) | Typed paths are a generic runtime plus a stub, not generated classes | Accepted |
+| [0012](decisions/0012-commands-and-events-have-argument-paths.md) | Commands and events get argument paths, and classes named by owner | Accepted |

bbfmodels-0.4.0/context/decisions/0011-typed-paths-are-a-stub-over-the-schema.md

@@ -0,0 +1,44 @@
+# 0011: Typed paths are a generic runtime plus a stub, not generated classes
+
+## Context
+
+Not every user wants models. Code that queries an ACS API asks for a
+parameter by its path string and gets a string back, and what it needs
+from bbfmodels is a correct path with autocomplete and the parameter's
+definition one step away. Generating a class per object with a property
+per member would give that, at the cost of another megabyte of code per
+package, import time to match, and a second copy of every name the models
+already carry.
+
+## Decision
+
+Typed paths are one generic runtime (`bbfmodels.paths`) that walks the
+package's shipped IR, plus a generated stub file (`paths.pyi`) per package
+that declares every object and parameter with the Python type of its
+value. The runtime `paths.py` in a package is three lines: the root path
+over the package's schema. Editors and type checkers read the stub; the
+interpreter never does.
+
+- `str()` of a path is the data path. A table renders as its partial path
+  and offers `search` for the USP wildcard form and `schema_path` for the
+  `{i}` form. Paths compare and hash as strings.
+- `definition` returns the IR object or parameter.
+- An unknown name is an `AttributeError`. A name the schema does not list
+  is reached with `child()`, so a typo in a standard name is never taken
+  for a vendor parameter.
+- Identifiers follow the models' rule (`N11kEnable` for `11kEnable`), and
+  the runtime maps the identifier back to the Forum name.
+
+pydantic remains a dependency even for a user who only wants paths, because
+the IR the runtime walks is built on it. That is accepted: the cost is one
+ubiquitous package, and a second dependency-free distribution can be split
+out if someone needs it.
+
+## Consequences
+
+- Autocomplete over the whole of TR-181 with no import cost: the stub for
+  TR-181 is a few hundred kilobytes that only tools read.
+- The first attribute access loads the package's IR (about 50 ms); every
+  one after that is a dictionary lookup.
+- The value type in the stub (`ParamPath[int]`) is documentation for the
+  reader and the type checker; the runtime does not use it.

bbfmodels-0.4.0/context/decisions/0012-commands-and-events-have-argument-paths.md

@@ -0,0 +1,47 @@
+# 0012: Commands and events get argument paths, and classes named by owner
+
+## Context
+
+USP adds commands (`Device.Reboot()`, `Device.IP.Diagnostics.TraceRoute()`)
+with input and output arguments, and events (`Device.Boot!`) with a
+payload. The specification gives the command and the event a path but not
+their arguments: an Operate request carries input arguments as a map of
+names to values, and the response the output the same way, with objects
+inside an output (`RouteHops.{i}.`) flattened into dotted names. The
+schema, the models and the paths each needed a way to refer to those
+arguments, and command names repeat across objects (`Reset()`,
+`Upload()`, `ScheduleTimer()`), so a class cannot be named after the
+command alone.
+
+## Decision
+
+- **The schema indexes arguments as objects under synthetic paths**:
+  `Device.IP.Diagnostics.TraceRoute().Input.`,
+  `Device.IP.Diagnostics.TraceRoute().Output.`, `Device.Boot!.`, with the
+  objects inside an output under them
+  (`...TraceRoute().Output.RouteHops.{i}.`). Argument values then resolve
+  and validate like any parameter. These objects are not `children()` of
+  the owning object; they are reached through the command or event.
+- **Generated classes are named by owner, command and side**:
+  `IP_Diagnostics_TraceRoute_Input`, `IP_Diagnostics_TraceRoute_Output`,
+  `IP_Diagnostics_TraceRoute_Output_RouteHops`; an event is `Device_Boot_Event`, the suffix keeping it apart from an object class of the same name.
+  Each package exposes `COMMANDS`, a map from command path to its input
+  and output classes, and `EVENTS`, from event path to its class, so a
+  controller can pick the class for a response by the path it sent.
+  `flatten("")` gives the bare argument names an Operate request carries.
+- **Paths name commands and events as the specification does**:
+  `str(Device.IP.Diagnostics.TraceRoute)` is `Device.IP.Diagnostics.TraceRoute()`
+  and `str(Device.Boot)` is `Device.Boot!`; attribute access drops the
+  suffix, `child()` takes the full name.
+- **`codec.xsd_type` gives the `xsi:type` CWMP carries** for a parameter,
+  derived from its base type, `xsd:string` for any list. This is the one
+  piece a CWMP stack needs from the model that the model alone did not
+  state. SOAP and protobuf envelopes stay out of scope.
+
+## Consequences
+
+- The synthetic paths are bbfmodels' own notation and never appear on the
+  wire; they exist so that one validation routine serves parameters and
+  arguments alike.
+- TR-181 USP generates 1486 classes rather than 975; import time is
+  unchanged at about a third of a second.

bbfmodels-0.4.0/docs/guides/models.md

@@ -0,0 +1,178 @@
+# Generated models
+
+A generated package has a pydantic class per object, a typed optional
+field per parameter and a `dict[int, Child]` per table. Names are the
+Forum's names, PascalCase and all. These packages ship with bbfmodels:
+
+| Package | Document | Root class |
+| --- | --- | --- |
+| `bbfmodels.tr181_cwmp` | TR-181 issue 2, CWMP edition | `Device` |
+| `bbfmodels.tr181_usp` | TR-181 issue 2, USP edition | `Device` |
+| `bbfmodels.tr098` | TR-098 | `InternetGatewayDevice` |
+| `bbfmodels.tr104_1` | TR-104 issue 1, voice on TR-098 gateways | `VoiceService` |
+| `bbfmodels.tr104_cwmp`, `bbfmodels.tr104_usp` | TR-104 issue 2, voice | `VoiceService` |
+| `bbfmodels.tr135_cwmp`, `bbfmodels.tr135_usp` | TR-135, set-top box | `STBService` |
+| `bbfmodels.tr140_cwmp`, `bbfmodels.tr140_usp` | TR-140, storage | `StorageService` |
+| `bbfmodels.tr196_cwmp`, `bbfmodels.tr196_usp` | TR-196, femtocell | `FAPService` |
+| `bbfmodels.tr517_usp` | TR-517, Matter | `MatterService` |
+
+Each package records `SOURCE`, `SPEC` and `MODEL`, and `schema()` returns
+the `Schema` of the IR it was generated from.
+
+## From device values and back
+
+`from_flat` takes the path and value pairs an ACS or USP controller
+returns. Values coerce to their Python type: integers, booleans (`1` and
+`true` alike), dates, binary, decimals, and comma-separated lists.
+
+```python
+from bbfmodels.tr181_cwmp import Device
+
+device = Device.from_flat({
+    "Device.DeviceInfo.UpTime": "1234",
+    "Device.DeviceInfo.FirstUseDate": "2026-01-02T03:04:05Z",
+    "Device.WiFi.Radio.1.Enable": "1",
+    "Device.WiFi.Radio.1.Channel": "36",
+    "Device.WiFi.SSID.1.LowerLayers": "Device.WiFi.Radio.1",
+})
+device.DeviceInfo.UpTime           # 1234
+device.DeviceInfo.FirstUseDate     # datetime(2026, 1, 2, 3, 4, 5, tzinfo=UTC)
+device.WiFi.Radio[1].Enable        # True
+device.WiFi.SSID[1].LowerLayers    # ['Device.WiFi.Radio.1']
+device.WiFi.Radio[2]               # KeyError: only instance 1 was given
+```
+
+Every field is optional, because no device exposes the whole model, and a
+child object that was not given is `None`. Paths may also be relative to
+the object: `Device.from_flat({"WiFi.Radio.1.Channel": "36"})`.
+
+`flatten` writes the model back as path and text pairs in canonical form:
+`true` for a boolean, `a,b` for a list, upper-case hex for binary.
+
+```python
+device.flatten()
+# {'Device.DeviceInfo.UpTime': '1234', ..., 'Device.WiFi.Radio.1.Enable': 'true', ...}
+```
+
+## Validation
+
+Parsing is lenient on purpose. Ranges, sizes, patterns and enumerations are
+not enforced when a model is built, because a real device returns values
+outside them and a model that refused them could not hold what the device
+said. `problems()` reports every violation against the shipped schema:
+
+```python
+device.WiFi.Radio[1].Channel = 999
+device.WiFi.Radio[1].Status = "zz"
+device.problems()
+# [('Device.WiFi.Radio.1.Status', "'zz' is not one of the enumerated values"),
+#  ('Device.WiFi.Radio.1.Channel', '999 is outside the allowed ranges')]
+```
+
+An enumeration is typed `Literal[...] | str`: an editor completes the
+Forum's values, and a vendor's extra value still validates. A parameter
+that takes its allowed values from another parameter, as
+`OperatingChannelBandwidth` does from `SupportedOperatingChannelBandwidths`,
+is not checked against a fixed list, because the list is the device's.
+
+## Tables and construction
+
+A table is a plain `dict[int, Child]`. Classes construct directly, and
+`flatten` takes the data path to write under:
+
+```python
+from bbfmodels.tr181_cwmp.wifi import WiFi_Radio
+
+radio = WiFi_Radio(Enable=True, Channel=36, OperatingFrequencyBand="5GHz")
+radio.flatten("Device.WiFi.Radio.1.")
+# {'Device.WiFi.Radio.1.Enable': 'true', 'Device.WiFi.Radio.1.OperatingFrequencyBand': '5GHz', 'Device.WiFi.Radio.1.Channel': '36'}
+```
+
+Class names are the object's path with the root dropped and dots replaced:
+`WiFi_Radio`, `WiFi_Radio_Stats`, `IP_Interface_IPv4Address`. They live in
+the module of their top-level subtree: `bbfmodels.tr181_cwmp.wifi`,
+`bbfmodels.tr181_cwmp.ip`.
+
+## Vendor parameters
+
+Parameters and objects the model does not define are kept as pydantic
+extras and written back by `flatten`. An unknown parameter is text; an
+unknown object is a nested dict with instance numbers as string keys.
+
+```python
+device = Device.from_flat({
+    "Device.WiFi.Radio.1.X_ACME_TxPower": "high",
+    "Device.X_ACME_Mesh.1.Role": "controller",
+})
+device.WiFi.Radio[1].X_ACME_TxPower   # 'high'
+device.X_ACME_Mesh                    # {'1': {'Role': 'controller'}}
+device.flatten()                      # both paths come back
+```
+
+For typed access to a vendor's extensions, generate a package from the
+vendor's document: see [vendor models](vendor-models.md).
+
+## Service models
+
+A service model's root is a table, `VoiceService.{i}.`, that a device
+mounts under its `Services.` object. The generated classes carry the
+document's paths and the mount is given when converting:
+
+```python
+from bbfmodels.tr104_cwmp import VoiceService
+
+voice = VoiceService.from_flat(values, "Device.Services.VoiceService.1.")
+voice.Capabilities.MaxLineCount
+voice.flatten("Device.Services.VoiceService.1.")
+voice.problems("Device.Services.VoiceService.1.")
+```
+
+Without a prefix, `from_flat` takes paths relative to the instance
+(`Capabilities.MaxLineCount`) and `problems` reports against instance 1.
+
+## Commands and events
+
+The USP packages carry a class for every command's input and output and
+every event's payload. `COMMANDS` maps a command path to its two classes
+and `EVENTS` an event path to its class, which is how a controller picks
+the class for the response to the Operate it sent:
+
+```python
+from bbfmodels.tr181_usp import COMMANDS, EVENTS
+
+request_cls, response_cls = COMMANDS["Device.IP.Diagnostics.TraceRoute()"]
+request = request_cls(Host="example.net", NumberOfTries=3)
+request.flatten("")           # {'Host': 'example.net', 'NumberOfTries': '3'}, the input_args of an Operate
+
+response = response_cls.from_flat({
+    "Status": "Complete",
+    "ResponseTime": "12",
+    "RouteHops.1.Host": "gw",
+    "RouteHops.1.RTTimes": "1,2,3",
+})
+response.RouteHops[1].RTTimes   # [1, 2, 3]
+response.problems()             # checked like any parameter
+
+boot = EVENTS["Device.Boot!"].from_flat({"Cause": "LocalReboot"})
+```
+
+The classes are importable by name too, `IP_Diagnostics_TraceRoute_Input`
+from `bbfmodels.tr181_usp.ip`, named by the owning object, the command
+and the side. In the schema the arguments live under
+`Device.IP.Diagnostics.TraceRoute().Input.` and `.Output.`, and an event's
+under `Device.Boot!.`, which is where `problems()` reports them.
+
+## Names that had to change
+
+Three kinds of Forum name cannot be a Python field as written. The field
+gets a safe name and the Forum's name as its alias, so `from_flat` and
+`flatten` are unaffected:
+
+| Forum name | Field | Why |
+| --- | --- | --- |
+| `Config` | `Config_` | pydantic reads `Config` from a class body as its legacy configuration |
+| `11kRSSIHighThresholdOffset` | `N11kRSSIHighThresholdOffset` | an identifier cannot start with a digit |
+| a name with a hyphen or other symbol | the symbol becomes `_` | not an identifier |
+
+None of the Forum's own documents needs the second or third; vendor
+documents do.