kapps-semantic-middleware 0.1.0__tar.gz

kapps_semantic_middleware-0.1.0/.env.example

@@ -0,0 +1,14 @@
+# GraphDB connection for examples and demo.
+# GraphDB runs with security disabled in the local Docker image, so username/password
+# are placeholders that the client merely requires.
+#
+# Only these three variables are read. The examples and the demo name their own
+# repository in code -- kapps-demo, the one docker/docker-compose.yml creates -- and the
+# test suite names its own. A GRAPHDB_REPOSITORY left in your environment is ignored by
+# all of them (issue #146), because whatever they connect to, they wipe and re-seed.
+#
+# WARNING: point GRAPHDB_URL at a GraphDB you are allowed to overwrite. The repository is
+# pinned, but the server is not.
+GRAPHDB_URL=http://localhost:7200
+GRAPHDB_USERNAME=admin
+GRAPHDB_PASSWORD=root

kapps_semantic_middleware-0.1.0/.github/workflows/hygiene.yml

@@ -0,0 +1,40 @@
+# This workflow is the backstop for commits made directly in the public repo.
+# The pre-push gate in the dev checkout cannot see those commits, so the public
+# repo needs its own CI that runs the same hygiene checks.
+#
+# Checks 2-5. Only check 1 (remotes) is left out: a runner's remote is whatever
+# actions/checkout configured and says nothing about the release. Check 2 is the
+# reason this file exists, and fetch-depth: 0 below is what lets it read the
+# whole history rather than the one commit a shallow checkout would give it.
+
+name: hygiene
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  hygiene:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Run the release hygiene checks
+        run: python scripts/release_checks.py .
+
+      # A tool published under the org but carrying no cf-tool topic is absent
+      # from the front door, which is a thing nobody notices by looking at the
+      # repository. release_checks.py is not the place for it: that file is
+      # stdlib-only and judges a tree, and this needs the API.
+      - name: Front-door registration
+        if: startsWith(github.repository, 'circularfactory/')
+        run: |
+          gh api repos/${{ github.repository }} --jq '.topics[]' | grep -qx cf-tool || {
+            echo "::error::Published under circularfactory but carries no cf-tool topic, so it is absent from the front door."
+            exit 1; }
+        env:
+          GH_TOKEN: ${{ github.token }}

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

@@ -0,0 +1,30 @@
+# Publish to PyPI when publish_release.py pushes a version tag.
+#
+# id-token: write is what makes trusted publishing work, and is why no API token
+# is stored anywhere. The tag push from publish_release.py is what fires this.
+#
+# PyPI supports trusted publishing from GitHub and from gitlab.com only, not from
+# a self-hosted GitLab. That is the whole reason this project is published from a
+# repository here while development happens elsewhere.
+
+name: publish
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Build the distributions
+        run: pipx run build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

kapps_semantic_middleware-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.ipynb_checkpoints/
+.env
+
+# Written by scripts/prepare_release.py: the reviewed branch tip that publish_release.py
+# refuses to move past. Local state about one release run, not a fact about the project.
+.release-state.json
+# Sphinx build output (#116). The docs site is deployed as a Pages artifact,
+# never committed -- the release repo keeps one clean commit of source only.
+docs/site/_build/
+# The scenario pages are the notebooks themselves, copied in from examples/ by
+# conf.py at build time (#141). Generated, so never committed -- same rule as the
+# build output above.
+docs/site/scenarios/hello-world.ipynb
+docs/site/scenarios/door.ipynb

kapps_semantic_middleware-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

kapps_semantic_middleware-0.1.0/AGENTS.md

@@ -0,0 +1,170 @@
+# AGENTS.md
+
+Orientation for an agent building against `kapps_semantic_middleware`.
+
+This library lets a piece of Python code running on or next to a shopfloor resource expose its
+functionality through an RDF knowledge graph, and lets other middleware instances discover and
+invoke that functionality through the graph rather than through hardcoded network references.
+
+If you are prototyping against this middleware, read the consumption rules below first. They are
+constraints that **do not surface in type signatures** — most of them fail silently, producing
+structurally wrong behavior rather than an exception. Then read the mechanics pages for whichever
+part you are touching.
+
+## Where to read what
+
+**Vocabulary — what the words mean.** Read these before the mechanics pages; the mechanics pages
+assume their terms and do not re-define them.
+
+| File | Covers |
+|---|---|
+| [`CONTEXT-MAP.md`](CONTEXT-MAP.md) | The five contexts, how they depend on each other, and the three-module ontology layering |
+| [`src/kapps_semantic_middleware/CONTEXT.md`](src/kapps_semantic_middleware/CONTEXT.md) | The core vocabulary: Service, Workflow, Parameter, ClassScope, Projection, Binding descriptor, Operation, Mode |
+| [`src/kapps_semantic_middleware/shacl_interop/CONTEXT.md`](src/kapps_semantic_middleware/shacl_interop/CONTEXT.md) | Precondition and outcome shapes derived from a function's type hints |
+| [`examples/CONTEXT.md`](examples/CONTEXT.md) | The self-contained scenario notebooks |
+| [`demo/transferunits/CONTEXT.md`](demo/transferunits/CONTEXT.md) | The runnable multi-process factory demonstration |
+
+**Mechanics — how to use it.** Written in construction order; a reader can go start to finish
+without forward references.
+
+| Page | Covers |
+|---|---|
+| [`docs/mechanics/01-instantiation-and-lifecycle.md`](docs/mechanics/01-instantiation-and-lifecycle.md) | Constructing an instance, choosing a mode, what appears in the graph at startup, heartbeat, deregistration |
+| [`docs/mechanics/02-workflow-registration.md`](docs/mechanics/02-workflow-registration.md) | Declaring what a Service exposes, the ontology prerequisites, signature-derived shapes, address vs. endpoint |
+| [`docs/mechanics/03-state-and-parameters.md`](docs/mechanics/03-state-and-parameters.md) | Modelling resource state as Parameters, committed value vs. locator, where a parameter's shape comes from |
+| [`docs/mechanics/04-connector-binding.md`](docs/mechanics/04-connector-binding.md) | The recognition chain, adding a protocol the library does not ship, connector wiring, transports |
+| [`docs/mechanics/05-operation-coordination.md`](docs/mechanics/05-operation-coordination.md) | Dispatch, the event trigger, pull-and-run, the status lifecycle, handover, recovery |
+| [`docs/mechanics/06-views-and-projection.md`](docs/mechanics/06-views-and-projection.md) | Defining a ClassScope, what a view cannot select, what the northbound projection removes |
+| [`docs/mechanics/07-writing-to-the-graph-and-to-devices.md`](docs/mechanics/07-writing-to-the-graph-and-to-devices.md) | Every path that causes a write, naming the field that moved, northbound vs. southbound, IRI handling |
+| [`docs/mechanics/08-provisioning-and-seeding.md`](docs/mechanics/08-provisioning-and-seeding.md) | **Read first if `ogm=` is a mystery.** The bootstrap order, loading the shared ontologies, authoring the domain TBox, and seeding the instance data a Parameter needs |
+
+### A note on the citations you will find in the glossaries
+
+The `CONTEXT.md` files cite architecture decision records as **ADR 00nn** and **root ADR
+000n**. Those records are development-repository material and are **not part of this
+distribution** — no copy of them ships, and the release rewrites every path that pointed
+at one, so a citation here is never a link you can follow.
+
+**Do not go looking for them.** The citations are provenance markers, not links. Every mechanism a
+glossary cites a record for is explained in full by the mechanics page covering it — ADR 0004's
+subject is the "Address and endpoint" section of
+[`02-workflow-registration.md`](docs/mechanics/02-workflow-registration.md), ADR 0006's is "The
+graph-facing connector" in [`04-connector-binding.md`](docs/mechanics/04-connector-binding.md), and
+so on. If a citation seems to point at something the mechanics pages do not cover, that is a
+documentation bug worth reporting, not a missing file worth hunting.
+
+## Where the names come from
+
+This library re-exports much of its surface from its three dependencies, so the import you need is
+often *not* from `kapps_semantic_middleware`. Use this table rather than guessing.
+
+| Name | Import from |
+|---|---|
+| `SemanticMiddleware`, `Mode` | `kapps_semantic_middleware` |
+| `IRI`, `GraphDB` | `kapps_triplestore_interface` |
+| `OGM` | `kapps_ogm` |
+| `ClassScope` | `kapps_ogm.utils.class_scope` |
+| `SyncDirection` | `transitional_sync_middleware.middleware.sync.synced_connector` |
+| `ConnectionInfo` | `transitional_sync_middleware.middleware.registries` |
+| `INF` (the interface vocabulary) | `kapps_semantic_middleware.vocabulary` |
+| `graphdb_for`, `credentials_for` | `kapps_semantic_middleware.credentials` |
+| `DataModel`, `Reference`, `Identifier` | `kapps_semantic_middleware` (re-exported from `transitional_sync_middleware`) |
+
+Binding internals, if you are adding a protocol, live under
+`kapps_semantic_middleware.connectors` — `semantic`, `mqtt_binding`, `rest_binding`,
+`knowledge_graph_connector`, `wiring`.
+
+> `kapps_semantic_middleware/ontology/` is **not** a Python module. It is the directory holding the
+> three vocabulary files (`core.ttl`, `mes.ttl`, `service.ttl`). Importing from it fails.
+
+## Consumption rules
+
+### These fail silently
+
+**`GraphDB.from_env()` connects to whatever `GRAPHDB_REPOSITORY` names, and seeding destroys what it
+connects to.** `seeding.clear_repository` clears the default graph of the client's current
+repository, so a value left over in a shell — from another project, another checkout, a `.bashrc`
+written months ago — silently redirects a wipe. Nothing validates that the repository was the one you
+meant; it only has to exist. Use `credentials.graphdb_for("name")`, which names the repository in
+code and ignores the variable, for anything that seeds, clears, or re-seeds. Note this hazard belongs
+to the *variable*, not the server: pinning the repository does not stop `GRAPHDB_URL` pointing at a
+shared instance.
+
+**A `ClassScope` terminates at a Parameter and cannot select within one.** Any chain element below
+a complex property is silently discarded during fetch. A view that tries to reach inside a
+parameter blanknode materializes only as far as the parameter itself, with no error raised. A scope
+chooses *which* parameters, never *which parts* of one.
+
+**Connector bindings must be registered at construction, not later.** The framework calls
+`connect()` on everything in the connection registry before it runs `on_start_up` callbacks. A
+connector registered after construction never has `connect()` called, so inbound traffic dies
+silently — the listener task never starts and the queue is never fed — while outbound may limp
+along, making the fault one-directional and quiet.
+
+**A Parameter's shape comes from the TBox restriction on its property's range, not from the
+instance data.** Anything the restriction does not declare is dropped at materialization with only
+a warning logged. Metadata a connector needs must be declared in the restriction or it never
+arrives, and the connector fails with nothing raised.
+
+**Under the locator pattern a Parameter's value is not in the graph at all.** Fast-changing
+parameters keep only metadata in the graph; the live value exists only in the datamodel and over
+REST. An unobserved parameter materializes as an empty list, which means *not yet read* — not zero,
+and not null. Handle the empty case.
+
+**A persistence write must name the region of the model that changed.** The fan-out notifies only
+the connectors that region covers. A write that does not name its field notifies every synced
+connector, so devices are written that nobody touched — and for a settable parameter that
+fabricates a command rather than merely wasting traffic.
+
+**The northbound REST payload never carries protocol connection metadata.** Broker addresses,
+topics and endpoints are pruned from the served datamodel *before* any data is fetched. This is
+structural, not a permission check: the northbound model has no field able to carry a broker
+address. It stops a peer *learning* an address from this surface; it does not stop someone who
+already knows it.
+
+**OWL existential restrictions do not make a field required.** Only SHACL shapes enforce
+requiredness, and only at admission. A parameter with no observed value does not raise a validation
+error on materialization merely because its restriction declares `owl:someValuesFrom`. Absence of a
+triple means *unknown*, never *false*.
+
+**Any prettified or shortened IRI is display only.** Production code carries fully back-resolvable
+IRIs in their mangled form — REST path segments, datamodel field names, `svc:endpoint` triples. A
+consumer that parses a displayed IRI, or round-trips one back into a query, gets a wrong answer
+with no exception raised.
+
+### These fail loudly
+
+**Every class you register against must already exist in the ontology.** The middleware creates
+instances automatically but never mints classes. A domain-specific subclass of `svc:Service`,
+`svc:Workflow` or `svc:StateProperty`, and the `cfc:Capability` subclass a Workflow realizes, must
+all pre-exist. Startup fails immediately, naming the missing class.
+
+**All knowledge-graph writes go through the OGM.** Raw SPARQL `UPDATE` or direct
+`kapps_triplestore_interface` mutation calls bypass the validated write path, so the written node passes no
+shape check and a property replacement loses its atomicity — the intermediate state fails
+validation. Reads may use the access module directly; only writes are constrained.
+
+**`@mw.workflow` and `@mw.state` are resource-mode only.** Each raises `RuntimeError` when called
+on an instance in any other mode, and `ValueError` when a required class IRI is missing.
+
+### Structural facts
+
+**Build against `src/kapps_semantic_middleware/`. `examples/` and `demo/` are illustrations, not
+API.** They are teaching vehicles seeded against throwaway repositories, not production patterns to
+copy.
+
+**The demo imports as `kapps_semantic_middleware.demonstrations`, not `demo`.** The wheel remaps
+the `demo/` directory into the library namespace. `import demo.transferunits` works only in a
+development checkout.
+
+**There is one Service per middleware *instance*, not per Resource.** Several instances may wrap
+one Resource — a controller and a monitor, say — each owning its own Service node, address and
+heartbeat, all linked by `svc:isServiceOf`. Discovery may therefore return several Services for one
+Resource; select by address or by advertised capability rather than assuming exactly one.
+
+**Only `resource` and `watchdog` modes are implemented.** `server` is reserved and raises
+`NotImplementedError`. A graph-*consuming* participant — a planner, a controller, a mobile robot —
+is a resource-mode instance with its own Resource, not a server-mode one.
+
+**Docker is a prerequisite for running the examples, never for using the library.** The bundled
+`docker compose` file provides the GraphDB the scenarios and the factory need.

kapps_semantic_middleware-0.1.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+Notable changes to `kapps-semantic-middleware`. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project uses
+[semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+`prepare_release.py` turns the Unreleased heading below into the dated entry for the version
+being released, and stops the release if there is no such heading. Write the entry as the work
+lands, not at release time.
+
+(That sentence deliberately does not spell the heading out. `edit_changelog` insists on finding
+exactly one of it, and prose naming it is a second occurrence — which stopped a release the
+first time this file was written.)
+
+## 0.1.0 — 2026-08-12
+
+### Added
+
+- **First public release.** A resource's state is described in an RDF knowledge graph as a
+  protocol-interface parameter, and the middleware wires that description to a real device:
+  peer discovery through the graph, a northbound REST surface, and southbound connectors that
+  keep graph and device in step.
+- Two runnable scenarios and a six-process factory demonstration, copied out of the installed
+  package with `kapps-examples` — including the `docker compose` files that stand up the
+  GraphDB they need, which previously reached only a reader of the source repository.
+- `kapps-transferunit-factory`, a console script that boots the factory demonstration.
+- Agent-facing documentation inside the distribution: `AGENTS.md`, `CONTEXT-MAP.md` and the
+  eight `docs/mechanics/` pages, so a consuming agent reading `site-packages` finds the rules
+  that explain what it is reading.
+
+### Changed
+
+- The synchronization layer is now `transitional-sync-middleware`, imported as
+  `transitional_sync_middleware`. It is the same code this project has always built on — a
+  transitional fork of `aas-middleware` carrying four synchronization fixes — published under
+  its own name. **It is retired within a few releases; do not build on it directly.**
+
+### Known limitations
+
+- Only `resource` and `watchdog` modes are implemented. `server` is reserved and raises
+  `NotImplementedError`.
+- A `ClassScope` selects *which* parameters, never *which parts* of one. Any chain element
+  below a complex property is discarded during fetch, with nothing raised.
+- Several consumption rules fail silently rather than raising. They are listed in `AGENTS.md`
+  under "These fail silently", and reading that section is not optional if you are writing code
+  against this library.

kapps_semantic_middleware-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+See [AGENTS.md](AGENTS.md).

kapps_semantic_middleware-0.1.0/CONTEXT-MAP.md

@@ -0,0 +1,59 @@
+# Context Map
+
+## Contexts
+
+- [Core Middleware](./src/kapps_semantic_middleware/CONTEXT.md) — the middleware library itself.
+  It holds the Service/Workflow/Capability/Operation/Mode registration machinery and the
+  execution machinery.
+- [SHACL Interop](./src/kapps_semantic_middleware/shacl_interop/CONTEXT.md) — the temporary SHACL
+  seam for workflow precondition shapes and outcome shapes. It generates and parses them. It is
+  explicit scaffolding, will move to `kapps_ogm` (see its ADR 0001).
+- [Example Scenarios](./examples/CONTEXT.md) — self-contained demonstration notebooks, plus the
+  seed-data logic and the ontology-provisioning logic under them. That logic makes each notebook
+  reproducible against a dummy repository, and never against the production state.
+- [TransferUnit Factory](./demo/transferunits/CONTEXT.md) — the runnable multi-process demo. A
+  launcher seeds N units and starts one process per participant (ADR 0029). Its decisions live
+  with the Core Middleware ADRs, next to ADR 0029.
+- **Module Requirements** — requirements this project places on sibling KAPPS-family
+  modules (`kapps_ogm`, the not-yet-created visual-toolbox GUI). Not a code context, and its
+  documents are development-repository material that does not ship.
+
+## Relationships
+
+- **Core Middleware → SHACL Interop**: Core Middleware calls into SHACL Interop to read or write
+  a shape. The shape belongs to a Workflow class or a StateProperty class. The call happens when
+  `@mw.workflow` or `@mw.state` registers or resolves one. SHACL Interop has no dependency back
+  on Core Middleware. It operates on class IRIs and shapes, and not on types of the Core Middleware.
+- **Example Scenarios → Core Middleware**: Example Scenarios instantiate and exercise Core
+  Middleware end-to-end, against the ontology and the instance data they seed themselves. Core Middleware
+  has no dependency on Example Scenarios.
+- **TransferUnit Factory → Core Middleware**: the factory runs several instances of the library
+  in separate processes. That is one instance per unit, plus a controller. A monitor is
+  milestone 2 (ADR 0032) and is not built. Core Middleware has no dependency on the factory.
+- **Module Requirements** records obligations that Core Middleware and SHACL Interop place on
+  `kapps_ogm` and the visual-toolbox repo. It does not depend on the code contexts, and no code
+  context depends on it. It is a record for work that belongs elsewhere.
+
+## Ontology-module layering
+
+The vocabulary of the project is layered across three modules (Core Middleware ADR 0012):
+
+- **`cfc:` — Core** (`.../Core#`): published, external, superior — `Operation`/`Capability`/
+  `Resource`/`Task`. The system imports and specializes it. The system does not modify it.
+- **`mes:` — MES** (`.../MES#`, `src/kapps_semantic_middleware/ontology/mes.ttl`): a
+  **domain** ontology that imports Core and details it out — possession + handover ability.
+  What domain experts touch.
+- **`svc:` — Service** (`.../Service#`, `ontology/service.ttl`): middleware-to-middleware
+  **reachability and coordination only**, domain code does not touch it. It holds Service, Workflow and
+  StateProperty, the address, the endpoint and the heartbeat. It also holds the resolution chain,
+  and an Operation's status and provenance.
+
+`mes:` and `svc:` are siblings that both import Core. `mes:` is domain-facing, `svc:` is
+middleware-facing.
+
+## Where the decisions are written down
+
+The architecture decision records are development-repository material and are not part of
+this distribution. What they decided is described, without the deliberation, in
+[`docs/mechanics/`](docs/mechanics/); [`AGENTS.md`](AGENTS.md) indexes those pages.
+

kapps_semantic_middleware-0.1.0/LICENSE

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

kapps_semantic_middleware-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: kapps-semantic-middleware
+Version: 0.1.0
+Summary: Semantic middleware for industrial data integration, built on transitional-sync-middleware
+Author-email: Etienne Hoffmann <etienne.hoffmann@kit.edu>, Sören Weindel <soeren.weindel@kit.edu>
+Maintainer-email: Etienne Hoffmann <etienne.hoffmann@kit.edu>, Sören Weindel <soeren.weindel@kit.edu>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: aiomqtt>=2.1.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: kapps-ogm>=0.2.0
+Requires-Dist: kapps-triplestore-interface>=2.1.0
+Requires-Dist: transitional-sync-middleware>=0.1.0
+Provides-Extra: examples
+Requires-Dist: amqtt>=0.11.0; extra == 'examples'
+Requires-Dist: rdflib>=7.1.3; extra == 'examples'
+Requires-Dist: uvicorn>=0.29.0; extra == 'examples'
+Provides-Extra: notebooks
+Requires-Dist: jupyter>=1.1.1; extra == 'notebooks'
+Requires-Dist: jupytext>=1.16.0; extra == 'notebooks'
+Requires-Dist: nbconvert>=7.16.0; extra == 'notebooks'
+Description-Content-Type: text/markdown
+
+# kapps_semantic_middleware
+
+Let a piece of Python running on or beside a shopfloor resource expose what it can do through an
+RDF knowledge graph — and let other instances discover and invoke that capability **through the
+graph**, rather than through hardcoded network addresses.
+
+A resource's state is described in the graph as a protocol-interface **parameter**. The middleware
+wires that description to the real device: it discovers peers, serves them over REST, and keeps the
+graph and the device in step.
+
+```bash
+pip install kapps-semantic-middleware
+```
+
+Python 3.12 or newer. Nothing else is required to use the library.
+
+## Run the examples
+
+The scenarios and the factory demo need a few more packages and a running GraphDB. One extra
+covers the packages:
+
+```bash
+pip install "kapps-semantic-middleware[examples]"
+```
+
+Copy the runnable files out of the installed package into a directory you own — a notebook inside
+`site-packages` cannot be opened, edited or re-run:
+
+```bash
+kapps-examples ./kapps-examples
+cd kapps-examples
+```
+
+You now have scenario 1 and scenario 2 (each as a `.py` and a `.ipynb`), the seed data they load,
+and a `docker/` directory. Add the `[notebooks]` extra if you want to open the `.ipynb` files in
+Jupyter; the `.py` versions run with `[examples]` alone.
+
+### Start a GraphDB
+
+Docker is needed for the examples and the demo, **never for the library itself**.
+
+```bash
+cd docker
+docker compose up -d
+```
+
+GraphDB comes up on <http://localhost:7200> and the `kapps-demo` repository is created for you.
+This works the same on Linux, macOS and Windows.
+
+Then point the library at it:
+
+```bash
+export GRAPHDB_URL=http://localhost:7200
+export GRAPHDB_USERNAME=admin
+export GRAPHDB_PASSWORD=root
+```
+
+Three variables, not four. `GraphDBCredentials.from_env()` in `kapps_triplestore_interface` also
+reads `GRAPHDB_REPOSITORY`, and your own code may well use it — but nothing here does. The examples
+and the demo name `kapps-demo` in code, and the test suite names its own. **A `GRAPHDB_REPOSITORY`
+you already have set is ignored rather than obeyed**, because these are the parts that wipe and
+re-seed whatever they connect to.
+
+> **Never point `GRAPHDB_URL` at a GraphDB you care about.** The examples and the demo clear the
+> repository they use on every run. `docker compose down -v` wipes the throwaway one; the next run
+> re-seeds it.
+
+### Run a scenario
+
+```bash
+python scenario1_hello_world.py     # operation coordination through the graph
+python scenario2_door.py            # direct state discovery and control
+```
+
+### Run the factory demo
+
+A small factory as six real processes — one per mock PLC, one per middleware instance, and a
+controller that discovers every unit *in the graph* and drives it over REST. You watch it from a
+browser.
+
+```bash
+kapps-transferunit-factory
+```
+
+## Where to read what
+
+| | |
+|---|---|
+| [`AGENTS.md`](AGENTS.md) | **Start here to build against this.** The consumption rules — including the ones that fail *silently* — and which name to import from where. |
+| [`docs/mechanics/`](docs/mechanics/) | How each mechanism actually works, one page each, in construction order. |
+| [`CONTEXT-MAP.md`](CONTEXT-MAP.md) | The five contexts and how they relate. |
+| `examples/` | Scenario 1 and scenario 2, self-contained. |
+| `demo/transferunits/` | The factory demo. |
+
+If you are writing code against this library, read `AGENTS.md` first. Several of its rules are
+constraints that **do not appear in any type signature** and fail by producing quietly wrong
+behaviour rather than an exception.
+
+## Status
+
+`0.1.0` is the first public release. It is usable — the scenarios and the factory demo run end to
+end — but the API may still move. See [`CHANGELOG.md`](CHANGELOG.md).
+
+## Contributing
+
+Development happens in a private repository and this one is the published half: it carries one
+commit per release and no ancestry, so there is nothing here to branch from.
+
+Bug reports and questions are welcome as issues on this repository. A patch is welcome too --
+say what it changes and why, and it will be applied on the development side and credited in
+`CHANGELOG.md` for the release that carries it.
+
+## Acknowledgements
+
+This package is developed as part of the INF subproject of the CRC 1574: Circular Factory for the
+Perpetual Product. This work is therefore supported by the Deutsche Forschungsgemeinschaft (DFG,
+German Research Foundation) [grant-number: SFB-1574-471687386].