topicforge 0.5.3__tar.gz → 0.5.4__tar.gz

{topicforge-0.5.3 → topicforge-0.5.4}/.gitignore

@@ -230,3 +230,8 @@ CLAUDE*.md
 # Pro tier: paid features kept out of the open-source repo
 # -------------------------------------------------------------------------
 pro/
+
+# Vendor license files for the demo participants (never commit)
+scripts/integration/**/rti_license.dat
+scripts/integration/**/*.dat
+.venv-demo/

{topicforge-0.5.3 → topicforge-0.5.4}/CHANGELOG.md

@@ -7,6 +7,112 @@ and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/
 
 ## [Unreleased]
 
+## [0.5.4] - 2026-10-02
+
+First run of the DDS code against a live multi-vendor bus (Windows 11, a
+Python / Cyclone DDS participant and a Rust / Dust DDS participant, TopicForge
+driven by a real MCP client). Until now every DDS adapter had only been
+checked statically. The run exposed four defects that together made the DDS
+module non-functional on Cyclone; all are fixed and pinned by tests.
+
+### Fixed
+
+- Role nodes published below their rate (about 7 Hz for 10 Hz on Windows):
+  they now keep an absolute schedule.
+
+- **`list_participants` now reports the participant name and the hostname on
+  Cyclone.** The name comes from the EntityName QoS and the hostname from the
+  `__Hostname` discovery property; both were always null on a real bus.
+- **Participant GUIDs were never read.** cyclonedds 11.0.1 exposes the builtin
+  key as a `uuid.UUID`, which the extractor did not handle, so every
+  participant collapsed onto a single `unknown` entry.
+- **Vendors were never identified.** The builtin participant sample carries no
+  vendor field. The vendor id is now read from the first two bytes of the GUID
+  prefix, as RTPS recommends; implementations that do not follow that
+  convention (Dust DDS, and RTI by default) still report `unknown`, because
+  the Cyclone Python binding does not expose the vendor id from the RTPS
+  header.
+- **The OMG vendor-id table was wrong.** It mapped `01.05` to Fast DDS and
+  `01.16` to Cyclone; the correct ids are `01.0F` (eProsima) and `01.10`
+  (Eclipse), verified against both vendors' sources. The Cyclone side ran on a
+  live bus; the Fast DDS side (`fast_extract_vendor_id`) is verified
+  statically only, since its tests need a binding that is not on PyPI. The `vendor` field of
+  `ParticipantInfo` and `ParticipantEvent` now also accepts `rti_micro`,
+  `opensplice`, `opendds`, `coredx`, `intercom` and `dust` (soft-breaking for
+  clients validating the previous enum).
+- **`detect_qos_mismatches` never reported anything on Cyclone.** cyclonedds
+  scopes its policy class names (`Reliability.BestEffort`), and the
+  normalizer matched only the bare name, so no QoS profile was ever built.
+- **A stopped participant never disappeared.** Discovery readers keep the last
+  sample of a departed participant with a NOT_ALIVE instance state; those are
+  now ignored for participants and endpoints, so a participant is reported as
+  left when its lease expires, and a dead endpoint no longer produces a
+  mismatch.
+
+- Cyclone adapter created a new DDS reader on a builtin discovery topic on
+  every tool call and never deleted it. It now keeps one reader per builtin
+  topic and takes a non-blocking snapshot, so calls no longer wait 2 s each
+  (`detect_qos_mismatches` waited 4 s).
+- `peek_dds_samples` on `DCPSPublication` / `DCPSSubscription` reported the
+  endpoints of participants that had left; disposed entries are now dropped.
+  Its payload also carries the endpoint `type_name`.
+- `test_dds_cross_vendor.py` expected an error message from v0.3; it had
+  never run, since CI has no DDS binding. First run against the real Cyclone
+  binding.
+
+### Added
+
+- `examples/dds/`: a "write the code" track. Examples 00 (hello publisher
+  and subscriber), 05 (Reliability), 06 (Durability and the late joiner),
+  07 (Deadline declared and kept) and 08 (a crash seen from inside and from
+  outside) each ship a readable `publisher.py` and `subscriber.py` in Cyclone
+  DDS Python; the subscriber prints what it receives and the DDS statuses,
+  and TopicForge explains the same situation from outside. All fourteen
+  examples pass on a live bus.
+- The generic role nodes print one line per second per reader with what
+  they received, and examples 02, 04, 10 and 13 check that the broken
+  subscriber receives nothing while the control one receives data.
+- The harness keeps each program's output in a log file and prints it live
+  under `--hold`.
+
+- `scripts/integration/interop_check.py`: one-command multi-vendor demo
+  that starts a Rust / Dust and a Python / Cyclone participant, drives
+  TopicForge over stdio through the official MCP client, checks participant
+  discovery, a deliberate Reliability mismatch between the two vendors, and
+  the departure of a stopped participant, then stops every process it started.
+- A real Rust / Dust DDS participant (`publishers/dust_publisher`) and a real
+  Python / Cyclone participant replacing the previous scaffold, which never
+  wrote a sample.
+- Twelve interop programs in total, one per vendor and language with an
+  officially released binding (Cyclone C / C++ / Rust / Python, Dust Rust /
+  Python, Fast DDS C++ / Python, RTI Connext C / C++ / Python, OpenSplice C),
+  all following the contract in `scripts/integration/DEMO_CONTRACT.md`. The
+  driver starts whichever ones are built on the host and adapts its checks;
+  `--list` shows what can run. Only Cyclone Python and Dust Rust / Python / C
+  have been run, on Windows; the rest are written but unrun. RTI participants
+  need a local license and are never run in CI.
+- One-command launch scripts, `scripts/integration/launch/setup` and
+  `run_demo` (`.ps1` and `.sh`), which create `.venv-demo`, install the Cyclone
+  binding and build the Rust participant. `setup.ps1 -Firewall` adds inbound
+  UDP 7400-7500 rules on private networks for multi-machine runs.
+- Unicast peer configuration for Cyclone and Fast DDS and a guide for a mixed
+  Linux and Windows bus (`scripts/integration/config/`).
+- `.github/workflows/demo.yml` runs the driver with the Cyclone and Dust
+  participants on Ubuntu and Windows; `demo-fast.yml` builds Fast DDS 3 from
+  pinned tags and starts the C++ participant (weekly and manual).
+- `scripts/integration/README.md` rewritten around the demo: it previously
+  described the removed docker / scenario rig.
+
+- `examples/dds/`: real use cases 10 to 14 (driver swap, wiring, safety
+  monitor dropout, deadline not offered, restart loop) next to the concept
+  examples 01 to 04. All nine pass on a live bus.
+
+### Removed
+
+- The docker / scenario integration rig (`scenarios_runner.py`, `run-local.*`,
+  `docker-compose.yml`, per-vendor Dockerfiles, scenario JSON files, schema
+  test and `integration.yml`) is removed in favour of the demo driver.
+
 ## [0.5.3] - 2026-10-01
 
 Fixes from an independent senior review of the whole repository (five
@@ -23,8 +129,9 @@ the findings.
   because the names are unclaimed anyone could have registered them: users
   following the documented `pip install topicforge[dds]` would then have run
   that code. Those extras are removed; `[dds]` now means Cyclone only. The
-  metadata of 0.3.0 to 0.5.2 is immutable on PyPI, which is why those
-  releases are being yanked and a security advisory published.
+  metadata of 0.3.0 to 0.5.2 is immutable on PyPI, so those releases have
+  been yanked: `pip install topicforge` no longer selects them, although an
+  exact pin such as `topicforge==0.5.2` still installs one.
 - **Removed the automatic `topicforge_pro` plugin hook.** At startup the
   server imported any installed package named `topicforge_pro` and handed it
   the full MCP server instance, so a third-party package with that
@@ -1007,7 +1114,8 @@ Initial MVP release of TopicForge: ROS Topic Inspector & Bag Analyzer MCP server
 - The write path (publishing, commanding robots) is intentionally out of scope for the MVP.
 - `analyze_bag` in live mode parses `ros2 bag info` text output; deeper anomaly detection remains mock-only for now.
 
-[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.5.3...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.5.4...HEAD
+[0.5.4]: https://github.com/yaniswav/TopicForge/compare/v0.5.3...v0.5.4
 [0.5.3]: https://github.com/yaniswav/TopicForge/compare/v0.5.2...v0.5.3
 [0.5.2]: https://github.com/yaniswav/TopicForge/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/yaniswav/TopicForge/compare/v0.5.0...v0.5.1

topicforge-0.5.4/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.5
+Name: topicforge
+Version: 0.5.4
+Summary: ROS Topic Inspector & Bag Analyzer MCP server for AI agents
+Project-URL: Homepage, https://github.com/yaniswav/TopicForge
+Project-URL: Repository, https://github.com/yaniswav/TopicForge
+Project-URL: Issues, https://github.com/yaniswav/TopicForge/issues
+Project-URL: Changelog, https://github.com/yaniswav/TopicForge/blob/main/CHANGELOG.md
+Author-email: Yanis ETHVIGNOT <ethvignot.yanis@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Yanis ETHVIGNOT
+        
+        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: ai,claude,mcp,model-context-protocol,robotics,ros2
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.0.0
+Requires-Dist: pydantic>=2.6
+Provides-Extra: all
+Requires-Dist: cyclonedds>=0.10; extra == 'all'
+Provides-Extra: bags
+Requires-Dist: rosbags>=0.9; extra == 'bags'
+Provides-Extra: dds
+Requires-Dist: cyclonedds>=0.10; extra == 'dds'
+Provides-Extra: dds-cyclone
+Requires-Dist: cyclonedds>=0.10; extra == 'dds-cyclone'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: rosbags>=0.9; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TopicForge
+
+<!-- mcp-name: io.github.yaniswav/topicforge -->
+
+[![PyPI version](https://img.shields.io/pypi/v/topicforge.svg)](https://pypi.org/project/topicforge/)
+[![CI](https://github.com/yaniswav/TopicForge/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/yaniswav/TopicForge/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/topicforge.svg)](https://pypi.org/project/topicforge/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/yaniswav/TopicForge/blob/main/LICENSE)
+[![Read-only by architecture](https://img.shields.io/badge/safety-read--only_by_architecture-2563eb)](https://github.com/yaniswav/TopicForge#security-model)
+
+A read-only MCP (Model Context Protocol) server that lets an AI agent inspect a ROS2 graph, recorded bag files and the DDS layer underneath ROS, without being able to publish to the bus or command a robot. It is read-only by **architecture**, not by configuration: there is no write path to misconfigure and no permission system to audit.
+
+Without grounding, an LLM asked about a robot will invent topic names, message types and bag contents. TopicForge gives it **eleven typed tools** that return frozen Pydantic schemas, identical whether the server talks to a real robot or to its built-in mock fixtures. It is aimed at ROS2 developers, robotics ML/CV engineers and teams that cannot accept a write path into a production stack.
+
+For DDS, TopicForge joins a domain as a read-only participant through one open-source binding (Eclipse CycloneDDS from PyPI) and reads the builtin discovery topics that the OMG DDS-RTPS protocol standardizes. Every conformant vendor announces itself there, so a Cyclone participant also sees RTI Connext, OpenDDS, CoreDX and Dust DDS endpoints without any proprietary binding. This covers discovery only: participants, readers, writers and their QoS. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md).
+
+## Quickstart
+
+No ROS2 needed; the mock adapter serves deterministic fixtures for a small differential robot (LIDAR + RGB camera). Python 3.10 to 3.13.
+
+```bash
+pip install topicforge
+TOPICFORGE_MODE=mock python -m topicforge
+# Windows PowerShell: $env:TOPICFORGE_MODE="mock"; python -m topicforge
+```
+
+The server speaks MCP over stdio and waits for a client, so wire it into one. For Claude Desktop, add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "topicforge": {
+      "command": "python",
+      "args": ["-m", "topicforge"],
+      "env": { "TOPICFORGE_MODE": "auto" }
+    }
+  }
+}
+```
+
+Then ask it to list the topics or to analyze `/tmp/demo.mcap`. For Claude Code: `claude mcp add topicforge -- topicforge`. Setup for a real ROS2 environment (WSL2, Linux, Docker, native Windows) is in [`docs/TESTING.md`](docs/TESTING.md); recurring monitoring prompts and the privacy contract are in [`docs/TUTORIEL.md`](docs/TUTORIEL.md).
+
+## Tools
+
+All eleven tools are read-only. Every response except `health_check` carries `mode_effective` (`"live"` or `"mock"`), so a caller can tell a real graph from fixtures.
+
+| Tool                    | Purpose                                                                                          |
+| ----------------------- | ------------------------------------------------------------------------------------------------ |
+| `health_check`          | Environment and mode introspection. Always succeeds; reports `mode` next to `requested_mode`      |
+| `list_topics`           | Discover the ROS2 graph                                                                          |
+| `get_topic_info`        | Message type, publisher/subscriber counts and QoS for one topic                                  |
+| `sample_messages`       | Peek recent messages on a ROS2 topic (count clamped to 50)                                       |
+| `analyze_bag`           | Summarize a `.mcap` / `.db3` / `.bag` recording                                                  |
+| `list_participants`     | DDS participants on the domain: vendor, `name` (EntityName QoS, Cyclone) and `hostname`          |
+| `detect_qos_mismatches` | Incompatible QoS pairs between DDS readers and writers                                           |
+| `peek_dds_samples`      | Raw DDS samples; structured on the three builtin discovery topics, presence-only on user topics   |
+| `participant_events`    | Timeline of participant `discovered` / `lost` events                                             |
+| `topic_metrics`         | Frequency, sequence-gap and latency schema; data only for builtin discovery topics               |
+| `peek_bag_samples`      | Decoded samples from a recorded bag (needs `pip install topicforge[bags]`)                       |
+
+Walkthroughs against the mock, each with the exact tool calls and payloads, are in [`examples/`](examples/README.md). To run the DDS tools against a real bus with several programs and vendors, see [`examples/dds/README.md`](examples/dds/README.md) (`python examples/dds/run_all.py`).
+
+## Modes
+
+| Mode   | When to use                                      | Backend                    |
+| ------ | ------------------------------------------------ | -------------------------- |
+| `mock` | Development, demos, CI, screencasts              | Deterministic fixtures     |
+| `live` | ROS2 sourced and on PATH, and/or a DDS backend   | `ros2` CLI, DDS participant |
+| `auto` | Detect what is available, else mock (default)    | Best available             |
+
+`live` and `auto` degrade instead of failing: if neither `ros2` nor a DDS backend comes up, the server serves the mock fixtures and `health_check` reports `mode: "mock"` next to `requested_mode`. Only `TOPICFORGE_MODE=mock` forces fixtures unconditionally. The live ROS2 adapter shells out to the `ros2` CLI, so `rclpy` does not need to be importable.
+
+## DDS backends
+
+```bash
+pip install topicforge[dds]                      # Eclipse CycloneDDS ([dds-cyclone] is the same thing)
+TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
+```
+
+`TOPICFORGE_DDS_BACKEND` accepts `mock` (default), `cyclone`, `fast` and `auto` (`fast`, then `cyclone`, then `mock`, whichever binding imports). An explicit value is honoured with or without `ros2` on PATH, in any mode except `mock`. If the binding is missing or the participant cannot start, the server logs a warning naming the cause and falls back to the ROS2 CLI alone, or to the mock fixtures. When both `ros2` and a DDS backend are up, a composite adapter routes the five ROS2 graph and bag tools to the CLI and the five DDS tools to the DDS backend.
+
+A Fast DDS adapter exists but has never run against a bus, and its `fastdds` Python binding is not on PyPI: build it from eProsima's sources and install it next to TopicForge. There is no `[dds-fast]` extra. `opendds` and `dust` are permanent stubs that never serve. `rti`, `opensplice`, `coredx` and `intercom` are rejected with a configuration error, since the Pro tier is retired (see [`docs/pro.md`](docs/pro.md)). Full backend selection, the routing table and the QoS mismatch scenario are in [`docs/DDS_QUICKSTART.md`](docs/DDS_QUICKSTART.md); error messages are in [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md).
+
+## Configuration reference
+
+| Variable                   | Default | Description                                                                                       |
+| -------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `TOPICFORGE_MODE`          | `auto`  | `mock`, `live` or `auto`                                                                          |
+| `TOPICFORGE_LOG_LEVEL`     | `INFO`  | `DEBUG`, `INFO`, `WARNING`, `ERROR`                                                               |
+| `TOPICFORGE_ROS2_BIN`      | `ros2`  | Name or path of the ROS2 CLI binary                                                               |
+| `TOPICFORGE_TELEMETRY`     | `off`   | Opt-in anonymous telemetry; an unrecognized value aborts startup. See [Telemetry](#telemetry)     |
+| `TOPICFORGE_DDS_BACKEND`   | `mock`  | `mock`, `cyclone`, `fast`, `auto` (`opendds` and `dust` are stubs)                                 |
+| `TOPICFORGE_DDS_DOMAIN_ID` | `0`     | DDS domain observed (0..232). Joined at startup; changing it needs a restart                      |
+
+Samples with comments are in [`.env.example`](.env.example). Any invalid value stops the server with `topicforge: configuration error: ...` and exit code 2, so a typo cannot silently change behaviour.
+
+## Limitations
+
+- **DDS validation is partial.** The Cyclone adapter has run against a real bus, with Cyclone and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`). The Fast DDS adapter has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
+- **User-topic payloads are not decoded.** `peek_dds_samples` on a user topic reports that the topic is announced on the bus and returns one placeholder sample (`_decode_status="raw"`, empty `_raw_bytes_hex`); no traffic is read. Consequently `topic_metrics` only has data for the builtin discovery topics, its observed frequency is the cadence of your own `peek_dds_samples` calls, and latency and sequence gaps are `null`. It is a discovery-layer probe, not a publish-rate monitor.
+- **Cyclone vendor ids.** Participants that do not follow the RTPS vendor-id convention in their GUID prefix (Dust DDS, and RTI by default) are reported with vendor `unknown`.
+- **DDS Security is not handled.** A participant without credentials sees an empty secure bus. `detect_qos_mismatches` covers Reliability, Durability, History and Deadline; Liveliness, Ownership and Partition are not checked.
+- **`sample_messages` (live)** runs `ros2 topic echo --csv --once` with a short timeout; a topic with no current publisher returns an empty sample. `timestamp_ns` is the message `header.stamp` for `Header`-stamped types and `0` for headerless ones.
+- **`analyze_bag` (live)** parses `ros2 bag info` text and does not use `rosbags`; anomaly detection is mock-only. `peek_bag_samples` is the only tool that reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output.
+- **Synchronous handlers.** The tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
+- No streaming or push subscriptions: tools are strictly request/response.
+
+The roadmap and the open work behind these limits are in [`docs/product-plan.md`](docs/product-plan.md).
+
+## Telemetry
+
+Opt-in, anonymous and **off by default**. When off, instrumentation returns the handler unchanged: no event is built, no transport is constructed, no network code runs (pinned by `tests/test_telemetry.py::test_build_app_off_makes_no_transport_calls`).
+
+```bash
+TOPICFORGE_TELEMETRY=on python -m topicforge
+```
+
+On-values: `on`, `1`, `true`, `yes`, `enabled`. Off-values: unset, `off`, `0`, `false`, `no`, `disabled`. Anything else is a configuration error, not a silent "off".
+
+When on, each tool call emits one event with exactly six fields:
+
+| Field        | Example         | Notes                                                       |
+| ------------ | --------------- | ----------------------------------------------------------- |
+| `tool_name`  | `"list_topics"` | One of the eleven tools, never argument values              |
+| `latency_ms` | `12.34`         | Handler wall-clock duration, 2 decimals                     |
+| `mode`       | `"mock"`        | Mode of the adapter actually serving: `mock` or `live`      |
+| `version`    | `"0.5.3"`       | TopicForge server version                                   |
+| `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
+| `success`    | `true`          | Whether the handler returned or raised                      |
+
+Never sent: topic names, message types or payloads, bag paths or contents, hostnames, usernames, IP addresses, environment variables, error messages. The field set is fenced by `tests/test_telemetry.py::test_payload_contains_only_whitelisted_keys`; adding a field requires updating this section. The default transport is a structured log line, there is no HTTP endpoint yet. The implementation is in [`src/topicforge/telemetry/`](src/topicforge/telemetry/).
+
+## Security model
+
+TopicForge is designed for **local trust**: it runs as a subprocess of your MCP client on a machine you control and inspects your own ROS2 graph, DDS domain and bag files. It is not hardened for adversarial inputs.
+
+- `TOPICFORGE_ROS2_BIN` accepts an arbitrary path; treat it the way you treat `PATH`.
+- `analyze_bag` and `peek_bag_samples` open whatever path the client passes (no workspace isolation, no symlink restriction).
+- All `ros2` invocations use `subprocess.run` with an argument list, never `shell=True`. ROS2 topic names are validated against `^/[A-Za-z0-9_/]+$` first.
+- The server loads no third-party code at startup. Until 0.5.2 it imported any installed `topicforge_pro` package; that hook was removed in 0.5.3 because it was an opening for a package of that name to add write tools.
+- No outbound network calls unless telemetry is turned on.
+
+Before exposing TopicForge to untrusted MCP clients (hosted endpoints, shared environments), add path isolation and revisit the `TOPICFORGE_ROS2_BIN` policy. Vulnerability reports: see [`SECURITY.md`](SECURITY.md).
+
+## Development
+
+```bash
+git clone https://github.com/yaniswav/TopicForge.git && cd TopicForge
+python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+python -m ruff check src tests
+python -m pytest
+```
+
+Tests run against the mock adapter, the live adapter's pure parsers and the binding-free DDS helpers; they never need a running ROS graph. Tests needing the `cyclonedds` or `fastdds` binding skip themselves when it is absent, and the `integration` marker (real-bus tests) is deselected by default. The `Makefile` (`make check`) uses POSIX shell syntax; on plain PowerShell run the commands above. See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Upgrading
+
+TopicForge is pre-1.0 and the 0.x releases changed things freely; [`CHANGELOG.md`](CHANGELOG.md) is the record. Two points matter if you are coming from an old install. Releases 0.3.0 to 0.5.2 are yanked, so `pip install -U topicforge` resolves to 0.5.3 or later. And since 0.5.3 the `[dds-fast]`, `[dds-opendds]`, `[dds-dust]` and `[dds-all-oss]` extras no longer exist, the DDS backend values `rti`, `opensplice`, `coredx` and `intercom` are rejected, and `[dds]` and `[all]` resolve to Cyclone only. Schema changes across 0.x were additive optional fields; a client that pins a JSON Schema with `additionalProperties: false` needs to regenerate it.
+
+## Layout
+
+```
+src/topicforge/
+  server/      MCP bootstrap, build_app(settings)
+  tools/       thin FastMCP handlers, no backend logic
+  services/    input validation, orchestration, adapter factory
+  adapters/    ros2_live, ros2_mock, dds_cyclone, dds_fast, common/ (binding-free logic)
+  models/      frozen Pydantic schemas, the contract with MCP clients
+  config/      settings and mode resolution
+  telemetry/   opt-in, off by default
+examples/      mock walkthroughs (*.md) and runnable live DDS examples (dds/)
+scripts/       real-bus interop checks
+docs/          guides, product plan
+tests/         pytest suite, mock-only, no ROS2 or DDS required
+```
+
+Layers are strictly separated: handlers never call `subprocess`, adapters are the only code that talks to a backend, and new backends implement the `MiddlewareAdapter` protocol in `adapters/base.py`.
+
+## License
+
+MIT, see [LICENSE](LICENSE). Commercial support and integration work: [`docs/pro.md`](docs/pro.md).

topicforge-0.5.4/README.md

@@ -0,0 +1,182 @@
+# TopicForge
+
+<!-- mcp-name: io.github.yaniswav/topicforge -->
+
+[![PyPI version](https://img.shields.io/pypi/v/topicforge.svg)](https://pypi.org/project/topicforge/)
+[![CI](https://github.com/yaniswav/TopicForge/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/yaniswav/TopicForge/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/topicforge.svg)](https://pypi.org/project/topicforge/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/yaniswav/TopicForge/blob/main/LICENSE)
+[![Read-only by architecture](https://img.shields.io/badge/safety-read--only_by_architecture-2563eb)](https://github.com/yaniswav/TopicForge#security-model)
+
+A read-only MCP (Model Context Protocol) server that lets an AI agent inspect a ROS2 graph, recorded bag files and the DDS layer underneath ROS, without being able to publish to the bus or command a robot. It is read-only by **architecture**, not by configuration: there is no write path to misconfigure and no permission system to audit.
+
+Without grounding, an LLM asked about a robot will invent topic names, message types and bag contents. TopicForge gives it **eleven typed tools** that return frozen Pydantic schemas, identical whether the server talks to a real robot or to its built-in mock fixtures. It is aimed at ROS2 developers, robotics ML/CV engineers and teams that cannot accept a write path into a production stack.
+
+For DDS, TopicForge joins a domain as a read-only participant through one open-source binding (Eclipse CycloneDDS from PyPI) and reads the builtin discovery topics that the OMG DDS-RTPS protocol standardizes. Every conformant vendor announces itself there, so a Cyclone participant also sees RTI Connext, OpenDDS, CoreDX and Dust DDS endpoints without any proprietary binding. This covers discovery only: participants, readers, writers and their QoS. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md).
+
+## Quickstart
+
+No ROS2 needed; the mock adapter serves deterministic fixtures for a small differential robot (LIDAR + RGB camera). Python 3.10 to 3.13.
+
+```bash
+pip install topicforge
+TOPICFORGE_MODE=mock python -m topicforge
+# Windows PowerShell: $env:TOPICFORGE_MODE="mock"; python -m topicforge
+```
+
+The server speaks MCP over stdio and waits for a client, so wire it into one. For Claude Desktop, add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "topicforge": {
+      "command": "python",
+      "args": ["-m", "topicforge"],
+      "env": { "TOPICFORGE_MODE": "auto" }
+    }
+  }
+}
+```
+
+Then ask it to list the topics or to analyze `/tmp/demo.mcap`. For Claude Code: `claude mcp add topicforge -- topicforge`. Setup for a real ROS2 environment (WSL2, Linux, Docker, native Windows) is in [`docs/TESTING.md`](docs/TESTING.md); recurring monitoring prompts and the privacy contract are in [`docs/TUTORIEL.md`](docs/TUTORIEL.md).
+
+## Tools
+
+All eleven tools are read-only. Every response except `health_check` carries `mode_effective` (`"live"` or `"mock"`), so a caller can tell a real graph from fixtures.
+
+| Tool                    | Purpose                                                                                          |
+| ----------------------- | ------------------------------------------------------------------------------------------------ |
+| `health_check`          | Environment and mode introspection. Always succeeds; reports `mode` next to `requested_mode`      |
+| `list_topics`           | Discover the ROS2 graph                                                                          |
+| `get_topic_info`        | Message type, publisher/subscriber counts and QoS for one topic                                  |
+| `sample_messages`       | Peek recent messages on a ROS2 topic (count clamped to 50)                                       |
+| `analyze_bag`           | Summarize a `.mcap` / `.db3` / `.bag` recording                                                  |
+| `list_participants`     | DDS participants on the domain: vendor, `name` (EntityName QoS, Cyclone) and `hostname`          |
+| `detect_qos_mismatches` | Incompatible QoS pairs between DDS readers and writers                                           |
+| `peek_dds_samples`      | Raw DDS samples; structured on the three builtin discovery topics, presence-only on user topics   |
+| `participant_events`    | Timeline of participant `discovered` / `lost` events                                             |
+| `topic_metrics`         | Frequency, sequence-gap and latency schema; data only for builtin discovery topics               |
+| `peek_bag_samples`      | Decoded samples from a recorded bag (needs `pip install topicforge[bags]`)                       |
+
+Walkthroughs against the mock, each with the exact tool calls and payloads, are in [`examples/`](examples/README.md). To run the DDS tools against a real bus with several programs and vendors, see [`examples/dds/README.md`](examples/dds/README.md) (`python examples/dds/run_all.py`).
+
+## Modes
+
+| Mode   | When to use                                      | Backend                    |
+| ------ | ------------------------------------------------ | -------------------------- |
+| `mock` | Development, demos, CI, screencasts              | Deterministic fixtures     |
+| `live` | ROS2 sourced and on PATH, and/or a DDS backend   | `ros2` CLI, DDS participant |
+| `auto` | Detect what is available, else mock (default)    | Best available             |
+
+`live` and `auto` degrade instead of failing: if neither `ros2` nor a DDS backend comes up, the server serves the mock fixtures and `health_check` reports `mode: "mock"` next to `requested_mode`. Only `TOPICFORGE_MODE=mock` forces fixtures unconditionally. The live ROS2 adapter shells out to the `ros2` CLI, so `rclpy` does not need to be importable.
+
+## DDS backends
+
+```bash
+pip install topicforge[dds]                      # Eclipse CycloneDDS ([dds-cyclone] is the same thing)
+TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
+```
+
+`TOPICFORGE_DDS_BACKEND` accepts `mock` (default), `cyclone`, `fast` and `auto` (`fast`, then `cyclone`, then `mock`, whichever binding imports). An explicit value is honoured with or without `ros2` on PATH, in any mode except `mock`. If the binding is missing or the participant cannot start, the server logs a warning naming the cause and falls back to the ROS2 CLI alone, or to the mock fixtures. When both `ros2` and a DDS backend are up, a composite adapter routes the five ROS2 graph and bag tools to the CLI and the five DDS tools to the DDS backend.
+
+A Fast DDS adapter exists but has never run against a bus, and its `fastdds` Python binding is not on PyPI: build it from eProsima's sources and install it next to TopicForge. There is no `[dds-fast]` extra. `opendds` and `dust` are permanent stubs that never serve. `rti`, `opensplice`, `coredx` and `intercom` are rejected with a configuration error, since the Pro tier is retired (see [`docs/pro.md`](docs/pro.md)). Full backend selection, the routing table and the QoS mismatch scenario are in [`docs/DDS_QUICKSTART.md`](docs/DDS_QUICKSTART.md); error messages are in [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md).
+
+## Configuration reference
+
+| Variable                   | Default | Description                                                                                       |
+| -------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `TOPICFORGE_MODE`          | `auto`  | `mock`, `live` or `auto`                                                                          |
+| `TOPICFORGE_LOG_LEVEL`     | `INFO`  | `DEBUG`, `INFO`, `WARNING`, `ERROR`                                                               |
+| `TOPICFORGE_ROS2_BIN`      | `ros2`  | Name or path of the ROS2 CLI binary                                                               |
+| `TOPICFORGE_TELEMETRY`     | `off`   | Opt-in anonymous telemetry; an unrecognized value aborts startup. See [Telemetry](#telemetry)     |
+| `TOPICFORGE_DDS_BACKEND`   | `mock`  | `mock`, `cyclone`, `fast`, `auto` (`opendds` and `dust` are stubs)                                 |
+| `TOPICFORGE_DDS_DOMAIN_ID` | `0`     | DDS domain observed (0..232). Joined at startup; changing it needs a restart                      |
+
+Samples with comments are in [`.env.example`](.env.example). Any invalid value stops the server with `topicforge: configuration error: ...` and exit code 2, so a typo cannot silently change behaviour.
+
+## Limitations
+
+- **DDS validation is partial.** The Cyclone adapter has run against a real bus, with Cyclone and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`). The Fast DDS adapter has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
+- **User-topic payloads are not decoded.** `peek_dds_samples` on a user topic reports that the topic is announced on the bus and returns one placeholder sample (`_decode_status="raw"`, empty `_raw_bytes_hex`); no traffic is read. Consequently `topic_metrics` only has data for the builtin discovery topics, its observed frequency is the cadence of your own `peek_dds_samples` calls, and latency and sequence gaps are `null`. It is a discovery-layer probe, not a publish-rate monitor.
+- **Cyclone vendor ids.** Participants that do not follow the RTPS vendor-id convention in their GUID prefix (Dust DDS, and RTI by default) are reported with vendor `unknown`.
+- **DDS Security is not handled.** A participant without credentials sees an empty secure bus. `detect_qos_mismatches` covers Reliability, Durability, History and Deadline; Liveliness, Ownership and Partition are not checked.
+- **`sample_messages` (live)** runs `ros2 topic echo --csv --once` with a short timeout; a topic with no current publisher returns an empty sample. `timestamp_ns` is the message `header.stamp` for `Header`-stamped types and `0` for headerless ones.
+- **`analyze_bag` (live)** parses `ros2 bag info` text and does not use `rosbags`; anomaly detection is mock-only. `peek_bag_samples` is the only tool that reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output.
+- **Synchronous handlers.** The tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
+- No streaming or push subscriptions: tools are strictly request/response.
+
+The roadmap and the open work behind these limits are in [`docs/product-plan.md`](docs/product-plan.md).
+
+## Telemetry
+
+Opt-in, anonymous and **off by default**. When off, instrumentation returns the handler unchanged: no event is built, no transport is constructed, no network code runs (pinned by `tests/test_telemetry.py::test_build_app_off_makes_no_transport_calls`).
+
+```bash
+TOPICFORGE_TELEMETRY=on python -m topicforge
+```
+
+On-values: `on`, `1`, `true`, `yes`, `enabled`. Off-values: unset, `off`, `0`, `false`, `no`, `disabled`. Anything else is a configuration error, not a silent "off".
+
+When on, each tool call emits one event with exactly six fields:
+
+| Field        | Example         | Notes                                                       |
+| ------------ | --------------- | ----------------------------------------------------------- |
+| `tool_name`  | `"list_topics"` | One of the eleven tools, never argument values              |
+| `latency_ms` | `12.34`         | Handler wall-clock duration, 2 decimals                     |
+| `mode`       | `"mock"`        | Mode of the adapter actually serving: `mock` or `live`      |
+| `version`    | `"0.5.3"`       | TopicForge server version                                   |
+| `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
+| `success`    | `true`          | Whether the handler returned or raised                      |
+
+Never sent: topic names, message types or payloads, bag paths or contents, hostnames, usernames, IP addresses, environment variables, error messages. The field set is fenced by `tests/test_telemetry.py::test_payload_contains_only_whitelisted_keys`; adding a field requires updating this section. The default transport is a structured log line, there is no HTTP endpoint yet. The implementation is in [`src/topicforge/telemetry/`](src/topicforge/telemetry/).
+
+## Security model
+
+TopicForge is designed for **local trust**: it runs as a subprocess of your MCP client on a machine you control and inspects your own ROS2 graph, DDS domain and bag files. It is not hardened for adversarial inputs.
+
+- `TOPICFORGE_ROS2_BIN` accepts an arbitrary path; treat it the way you treat `PATH`.
+- `analyze_bag` and `peek_bag_samples` open whatever path the client passes (no workspace isolation, no symlink restriction).
+- All `ros2` invocations use `subprocess.run` with an argument list, never `shell=True`. ROS2 topic names are validated against `^/[A-Za-z0-9_/]+$` first.
+- The server loads no third-party code at startup. Until 0.5.2 it imported any installed `topicforge_pro` package; that hook was removed in 0.5.3 because it was an opening for a package of that name to add write tools.
+- No outbound network calls unless telemetry is turned on.
+
+Before exposing TopicForge to untrusted MCP clients (hosted endpoints, shared environments), add path isolation and revisit the `TOPICFORGE_ROS2_BIN` policy. Vulnerability reports: see [`SECURITY.md`](SECURITY.md).
+
+## Development
+
+```bash
+git clone https://github.com/yaniswav/TopicForge.git && cd TopicForge
+python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+python -m ruff check src tests
+python -m pytest
+```
+
+Tests run against the mock adapter, the live adapter's pure parsers and the binding-free DDS helpers; they never need a running ROS graph. Tests needing the `cyclonedds` or `fastdds` binding skip themselves when it is absent, and the `integration` marker (real-bus tests) is deselected by default. The `Makefile` (`make check`) uses POSIX shell syntax; on plain PowerShell run the commands above. See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Upgrading
+
+TopicForge is pre-1.0 and the 0.x releases changed things freely; [`CHANGELOG.md`](CHANGELOG.md) is the record. Two points matter if you are coming from an old install. Releases 0.3.0 to 0.5.2 are yanked, so `pip install -U topicforge` resolves to 0.5.3 or later. And since 0.5.3 the `[dds-fast]`, `[dds-opendds]`, `[dds-dust]` and `[dds-all-oss]` extras no longer exist, the DDS backend values `rti`, `opensplice`, `coredx` and `intercom` are rejected, and `[dds]` and `[all]` resolve to Cyclone only. Schema changes across 0.x were additive optional fields; a client that pins a JSON Schema with `additionalProperties: false` needs to regenerate it.
+
+## Layout
+
+```
+src/topicforge/
+  server/      MCP bootstrap, build_app(settings)
+  tools/       thin FastMCP handlers, no backend logic
+  services/    input validation, orchestration, adapter factory
+  adapters/    ros2_live, ros2_mock, dds_cyclone, dds_fast, common/ (binding-free logic)
+  models/      frozen Pydantic schemas, the contract with MCP clients
+  config/      settings and mode resolution
+  telemetry/   opt-in, off by default
+examples/      mock walkthroughs (*.md) and runnable live DDS examples (dds/)
+scripts/       real-bus interop checks
+docs/          guides, product plan
+tests/         pytest suite, mock-only, no ROS2 or DDS required
+```
+
+Layers are strictly separated: handlers never call `subprocess`, adapters are the only code that talks to a backend, and new backends implement the `MiddlewareAdapter` protocol in `adapters/base.py`.
+
+## License
+
+MIT, see [LICENSE](LICENSE). Commercial support and integration work: [`docs/pro.md`](docs/pro.md).