topicforge 0.1.2__tar.gz → 0.2.0__tar.gz

{topicforge-0.1.2 → topicforge-0.2.0}/.gitignore

@@ -197,6 +197,21 @@ CLAUDE*.md
 /docs/projet-file/**
 !/docs/projet-file/README.md
 !/docs/projet-file/*-spec.md
+# Traction snapshots are versioned: weekly JSON + summary + folder README.
+# This is the historical curve that informs decision gates G1/G2/G3
+# (product-plan §12). Numeric history must survive across machines.
+!/docs/projet-file/traction/
+!/docs/projet-file/traction/**
+# Launch-post drafts (Reddit, LinkedIn, X). Versioned so the maintainer
+# can diff drafts across releases and keep marketing history auditable.
+# Drafts, not production copy — never the public README.
+!/docs/projet-file/launch-posts/
+!/docs/projet-file/launch-posts/**
+# Audit reports (security, architecture) + audit-followup triage docs.
+# Versioned so audit trails survive across machines and the triage
+# decisions are bisectable per release.
+!/docs/projet-file/*-audit-*.md
+!/docs/projet-file/audit-*.md
 /docs/assets/screencast-raw/
 
 

{topicforge-0.1.2 → topicforge-0.2.0}/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-14
+
+### Strategic
+
+- **Mono-MCP pivot (2026-05-14).** The 3-to-5-MCP pack draft is collapsed into a 2-product strategy: TopicForge umbrella (this product — covers ROS2 today and grows a DDS observability module starting with v0.2.0), and **DatasetForge** (Vision Dataset Inspector, the standalone second product). DdsForge as a standalone repo is cancelled — its spec is reframed as the TopicForge DDS module spec at `docs/projet-file/mcp-02-spec.md`. Motif: solo-maintenance cost of two parallel repos was the binding constraint, and ROS2 / DDS are the same problem shape (typed pub/sub graph introspection) under the same `MiddlewareAdapter` superset.
+
+### Added
+
+- **DDS module — 3 new MCP tools.** `list_participants(domain_id)`, `detect_qos_mismatches(topic)`, `peek_dds_samples(topic, count)`. All read-only ; surface DDS-layer introspection distinct from the ROS2 graph tools. `peek_dds_samples` is deliberately separate from `sample_messages` — different layer, different semantics, distinct tool description so an LLM picks the right one in a mixed setup.
+- **`MiddlewareAdapter` protocol** in `adapters/base.py` — superset of the historical `RosAdapter`. Covers both ROS2 graph methods and the new DDS methods under one contract. `RosAdapter` retained as a backward-compat alias (`RosAdapter = MiddlewareAdapter`).
+- **`CycloneDdsAdapter`** (`adapters/dds_cyclone/`) — lazy-imported only when `TOPICFORGE_DDS_BACKEND=cyclone` and the optional `cyclonedds` extras are installed (`pip install topicforge[dds]`). **v0.2.0 ships a protocol-compliant stub**: the lazy import, `is_available()`, and routing all work ; the 3 DDS methods raise `AdapterError` with a v0.2.x roadmap pointer. The real CycloneDDS discovery (builtin topics, QoS pair extraction, typed reader for samples) lands in a v0.2.x patch. The mock backend (`TOPICFORGE_DDS_BACKEND=mock`, the default) exposes a working DDS surface against deterministic fixtures in the meantime.
+- **3 new Pydantic schemas**: `QosProfile` (Reliability / Durability / History / Deadline at MVP), `ParticipantInfo` (GUID, vendor, hostname, domain_id), `MismatchReport` (incompatible_policies + severity). All frozen, `extra="forbid"`.
+- **Pure analyzer** `adapters/common/qos_analyzer.detect_mismatches` — module-level pure function, testable against synthesized QoS pairs without any DDS middleware installed.
+- **Environment variables**:
+  - `TOPICFORGE_DDS_BACKEND` — `mock | cyclone | rti | auto`, default `mock`. The DDS module is opt-in ; existing ROS2-only setups behave unchanged.
+  - `TOPICFORGE_DDS_DOMAIN_ID` — DDS domain id observed (0..232), default `0`.
+- **Mock fixtures enriched**: 2 deterministic DDS participants, two-topic scenario (`/dds/well_matched` and `/dds/qos_mismatch`) exercising `detect_qos_mismatches` end-to-end.
+- **`pyproject.toml` extras**: `[dds]` pulls `cyclonedds>=0.10` ; `[all]` aliases `[dds]`. `pip install topicforge` keeps the core + mock only (zero install impact on ROS2-only users).
+
+### Changed
+
+- **`TopicInfo` schema soft-breaking.** Three additive optional fields (`reader_count: int | None`, `writer_count: int | None`, `qos_profile: QosProfile | None`) — all default `None`. Producer side: code constructing `TopicInfo` directly is unaffected (defaults compile). **Strict MCP clients that validated v0.1.x responses against the `TopicInfo` schema with `additionalProperties: false` will reject v0.2.0 responses unless their schema is regenerated. Standard MCP clients that read tool descriptions dynamically are unaffected.**
+- **`HealthReport` schema soft-breaking**, same shape. Three additive optional fields (`dds_backend`, `dds_domain_id`, `middleware_available`) with safe defaults (`"none"`, `None`, `False`).
+- **`RosAdapter` renamed to `MiddlewareAdapter`** in `adapters/base.py`. The old name remains as an alias (`RosAdapter = MiddlewareAdapter`) ; existing imports `from topicforge.adapters import RosAdapter` still type-check. The `Ros2CliAdapter.name` value moves from `"live"` to `"ros2_cli"` — internal tag, separate from the MCP-wire `mode_effective` field which keeps its `Literal["mock", "live"]` contract.
+- **`Settings`** gains `dds_backend` and `dds_domain_id` fields with safe defaults (`"mock"`, `0`). Existing `Settings(...)` constructors are unaffected.
+- **`Ros2CliAdapter` DDS methods raise `AdapterError`** with a clear remediation path (`pip install topicforge[dds]` + `TOPICFORGE_DDS_BACKEND=cyclone`). This is the v0.2.0 MVP limitation D6 (single-adapter-at-a-time) ; a composite adapter that delegates per-tool is a v0.2.x roadmap item.
+
+### Internal
+
+- `parse_topic_info` and `parse_bag_info` parsers : `mode_effective` kwarg typed as `EffectiveMode` (`Literal["mock", "live"]`) rather than the broader `AdapterName`, cleanly separating the wire-facing mode from the implementation tag.
+- New pytest marker `requires_cyclonedds` for tests that need the SDK. Auto-skips otherwise via `pytest.importorskip`.
+
+### Notes
+
+- **`cyclonedds` is optional.** Default installs (`pip install topicforge`) are unchanged from v0.1.2 in dependency footprint. Only `pip install topicforge[dds]` pulls the bindings (`cyclonedds>=0.10`).
+- **No code change to the 5 ROS2 tools** — `health_check`, `list_topics`, `get_topic_info`, `sample_messages`, `analyze_bag` behave identically to v0.1.2. The wire contract (`mode_effective: Literal["mock", "live"]`) is unchanged.
+- **v0.2.0 MVP limitation**: single adapter at a time. Users select ROS2 introspection (default) or DDS observability via `TOPICFORGE_DDS_BACKEND=cyclone`, not both simultaneously. The unselected half raises `AdapterError` with a remediation pointer. A composite adapter delegating per-tool category is a v0.2.x roadmap item.
+
 ## [0.1.2] - 2026-05-13
 
 ### Fixed
@@ -67,7 +105,8 @@ Initial MVP release of TopicForge — ROS Topic Inspector & Bag Analyzer MCP ser
 - 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.1.2...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/yaniswav/TopicForge/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/yaniswav/TopicForge/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/yaniswav/TopicForge/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/yaniswav/TopicForge/releases/tag/v0.1.0

{topicforge-0.1.2 → topicforge-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topicforge
-Version: 0.1.2
+Version: 0.2.0
 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
@@ -40,6 +40,10 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.11
 Requires-Dist: mcp>=1.0.0
 Requires-Dist: pydantic>=2.6
+Provides-Extra: all
+Requires-Dist: cyclonedds>=0.10; extra == 'all'
+Provides-Extra: dds
+Requires-Dist: cyclonedds>=0.10; extra == 'dds'
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
@@ -47,9 +51,14 @@ Description-Content-Type: text/markdown
 
 # TopicForge
 
-> **The safety-first read-only MCP for ROS2 robotics.** TopicForge lets AI agents inspect your ROS2 graph and bag files without ever publishing back to the bus — so your safety officer doesn't flinch when you wire Claude into your robot stack.
+[![PyPI version](https://img.shields.io/pypi/v/topicforge.svg)](https://pypi.org/project/topicforge/)
+[![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)
 
-TopicForge is a production-minded MCP (Model Context Protocol) server that lets AI agents — such as Claude — inspect ROS2 topics and analyze ROS bag files through a clean, structured tool interface. It is read-only by **architecture**, not by configuration: there is no write path to misconfigure, no permission system to audit, no liability conversation to have. The MCP client can see the robot stack; it cannot touch it.
+> **The safety-first read-only MCP for ROS2 robotics — now with a DDS observability module (v0.2.0).** TopicForge lets AI agents inspect your ROS2 graph, ROS bag files, and (since v0.2.0) the raw DDS layer beneath ROS, without ever publishing back to the bus. The MCP client can see the stack ; it cannot touch it.
+
+TopicForge is a production-minded MCP (Model Context Protocol) server that lets AI agents — such as Claude — inspect ROS2 topics, analyze ROS bag files, and (since v0.2.0) observe the raw DDS layer through a clean, structured tool interface. It is read-only by **architecture**, not by configuration: there is no write path to misconfigure, no permission system to audit, no liability conversation to have. The MCP client can see the robot stack; it cannot touch it.
 
 This stance matters because the ROS-MCP space is no longer empty — general-purpose ROS-MCP servers exist that let an LLM publish topics, call services, and command robots. That shape is fine for demos; it is untenable for production fleets, defense systems, automotive AUTOSAR Adaptive surfaces, or anything safety-certified. TopicForge is the read-only alternative for those audiences, plus the robotics developers, ML/CV engineers, and teams that want their AI tooling to *understand* their robotics stack without commanding it.
 
@@ -179,6 +188,31 @@ TOPICFORGE_MODE=live python -m topicforge
 
 TopicForge invokes the `ros2` CLI under the hood, so it does **not** require `rclpy` to be importable. This keeps the live adapter portable across ROS2 distros.
 
+### DDS support (v0.2.0+)
+
+Beyond ROS2 graph introspection, TopicForge can also observe a raw DDS bus directly — useful for non-ROS DDS stacks (defense, aerospace, automotive AUTOSAR Adaptive, industrial integration) and for diagnosing why a ROS2 subscriber isn't receiving when the graph says it should. Same safety-first contract : read-only by **architecture**, never publishes back to the bus.
+
+Install the optional DDS extras and select a backend :
+
+```bash
+pip install topicforge[dds]
+TOPICFORGE_MODE=live TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
+```
+
+Three new MCP tools (in addition to the five ROS2 tools above) :
+
+| Tool                    | Purpose                                                                          |
+| ----------------------- | -------------------------------------------------------------------------------- |
+| `list_participants`     | DDS participants discovered on a domain, with vendor and hostname                |
+| `detect_qos_mismatches` | Reader/writer QoS incompatibilities preventing communication on a topic          |
+| `peek_dds_samples`      | Recent samples on a raw DDS topic (distinct from `sample_messages` on ROS2 graph)|
+
+**v0.2.0 limitation.** TopicForge selects one adapter at a time. With `TOPICFORGE_DDS_BACKEND=cyclone`, the 3 DDS tools work and the 5 ROS2 tools raise a clear `AdapterError` — and vice versa with the default `TOPICFORGE_DDS_BACKEND=mock`. The mock backend exposes all 8 tools against deterministic fixtures for local development and tests. Real CycloneDDS discovery (builtin topics, QoS pair extraction, typed reader for samples) ships as a v0.2.x patch ; the v0.2.0 `CycloneDdsAdapter` is a protocol-compliant stub that raises a clear roadmap message. A composite adapter delegating per-tool is a v0.2.x roadmap item.
+
+`RTI Connext` and additional vendors will be available in the Pro tier (see `docs/pro.md`).
+
+**Full 5-minute walkthrough** — including the canonical QoS-mismatch debugging scenario, the single-adapter limitation matrix, and troubleshooting — lives in [`docs/DDS_QUICKSTART.md`](docs/DDS_QUICKSTART.md).
+
 ### Configure with Claude Desktop
 
 Add to your `claude_desktop_config.json`:
@@ -226,12 +260,14 @@ make check    # both, plus tests (CI bundle)
 
 ## 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 usage telemetry. See [Telemetry](#telemetry).    |
+| 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 usage telemetry. See [Telemetry](#telemetry).                |
+| `TOPICFORGE_DDS_BACKEND`    | `mock`  | DDS module backend: `mock`, `cyclone`, `rti`, or `auto`. See [DDS support](#dds-support-v020). |
+| `TOPICFORGE_DDS_DOMAIN_ID`  | `0`     | DDS domain id observed (0..232) when a DDS backend is active.                 |
 
 See [`.env.example`](.env.example).
 
@@ -305,6 +341,7 @@ See [`docs/product-plan.md`](docs/product-plan.md) for the full product trajecto
 Near-term additions on the bench:
 
 - `rclpy`-backed live adapter for faster & richer sampling
+- DDS observability module (Cyclone DDS first as an `extras` install — `pip install topicforge[dds]` —, RTI Connext later in the Pro tier). Generalizes the existing `RosAdapter` to a `MiddlewareAdapter` protocol. Same safety-first read-only contract.
 - URDF inspector / validator MCP tools
 - Bag anomaly detection (clock jumps, gaps, dropped frames, TF tree health)
 - Dataset export helpers (rosbag → COCO / HF Datasets)

{topicforge-0.1.2 → topicforge-0.2.0}/README.md

@@ -1,8 +1,13 @@
 # TopicForge
 
-> **The safety-first read-only MCP for ROS2 robotics.** TopicForge lets AI agents inspect your ROS2 graph and bag files without ever publishing back to the bus — so your safety officer doesn't flinch when you wire Claude into your robot stack.
+[![PyPI version](https://img.shields.io/pypi/v/topicforge.svg)](https://pypi.org/project/topicforge/)
+[![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)
 
-TopicForge is a production-minded MCP (Model Context Protocol) server that lets AI agents — such as Claude — inspect ROS2 topics and analyze ROS bag files through a clean, structured tool interface. It is read-only by **architecture**, not by configuration: there is no write path to misconfigure, no permission system to audit, no liability conversation to have. The MCP client can see the robot stack; it cannot touch it.
+> **The safety-first read-only MCP for ROS2 robotics — now with a DDS observability module (v0.2.0).** TopicForge lets AI agents inspect your ROS2 graph, ROS bag files, and (since v0.2.0) the raw DDS layer beneath ROS, without ever publishing back to the bus. The MCP client can see the stack ; it cannot touch it.
+
+TopicForge is a production-minded MCP (Model Context Protocol) server that lets AI agents — such as Claude — inspect ROS2 topics, analyze ROS bag files, and (since v0.2.0) observe the raw DDS layer through a clean, structured tool interface. It is read-only by **architecture**, not by configuration: there is no write path to misconfigure, no permission system to audit, no liability conversation to have. The MCP client can see the robot stack; it cannot touch it.
 
 This stance matters because the ROS-MCP space is no longer empty — general-purpose ROS-MCP servers exist that let an LLM publish topics, call services, and command robots. That shape is fine for demos; it is untenable for production fleets, defense systems, automotive AUTOSAR Adaptive surfaces, or anything safety-certified. TopicForge is the read-only alternative for those audiences, plus the robotics developers, ML/CV engineers, and teams that want their AI tooling to *understand* their robotics stack without commanding it.
 
@@ -132,6 +137,31 @@ TOPICFORGE_MODE=live python -m topicforge
 
 TopicForge invokes the `ros2` CLI under the hood, so it does **not** require `rclpy` to be importable. This keeps the live adapter portable across ROS2 distros.
 
+### DDS support (v0.2.0+)
+
+Beyond ROS2 graph introspection, TopicForge can also observe a raw DDS bus directly — useful for non-ROS DDS stacks (defense, aerospace, automotive AUTOSAR Adaptive, industrial integration) and for diagnosing why a ROS2 subscriber isn't receiving when the graph says it should. Same safety-first contract : read-only by **architecture**, never publishes back to the bus.
+
+Install the optional DDS extras and select a backend :
+
+```bash
+pip install topicforge[dds]
+TOPICFORGE_MODE=live TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
+```
+
+Three new MCP tools (in addition to the five ROS2 tools above) :
+
+| Tool                    | Purpose                                                                          |
+| ----------------------- | -------------------------------------------------------------------------------- |
+| `list_participants`     | DDS participants discovered on a domain, with vendor and hostname                |
+| `detect_qos_mismatches` | Reader/writer QoS incompatibilities preventing communication on a topic          |
+| `peek_dds_samples`      | Recent samples on a raw DDS topic (distinct from `sample_messages` on ROS2 graph)|
+
+**v0.2.0 limitation.** TopicForge selects one adapter at a time. With `TOPICFORGE_DDS_BACKEND=cyclone`, the 3 DDS tools work and the 5 ROS2 tools raise a clear `AdapterError` — and vice versa with the default `TOPICFORGE_DDS_BACKEND=mock`. The mock backend exposes all 8 tools against deterministic fixtures for local development and tests. Real CycloneDDS discovery (builtin topics, QoS pair extraction, typed reader for samples) ships as a v0.2.x patch ; the v0.2.0 `CycloneDdsAdapter` is a protocol-compliant stub that raises a clear roadmap message. A composite adapter delegating per-tool is a v0.2.x roadmap item.
+
+`RTI Connext` and additional vendors will be available in the Pro tier (see `docs/pro.md`).
+
+**Full 5-minute walkthrough** — including the canonical QoS-mismatch debugging scenario, the single-adapter limitation matrix, and troubleshooting — lives in [`docs/DDS_QUICKSTART.md`](docs/DDS_QUICKSTART.md).
+
 ### Configure with Claude Desktop
 
 Add to your `claude_desktop_config.json`:
@@ -179,12 +209,14 @@ make check    # both, plus tests (CI bundle)
 
 ## 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 usage telemetry. See [Telemetry](#telemetry).    |
+| 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 usage telemetry. See [Telemetry](#telemetry).                |
+| `TOPICFORGE_DDS_BACKEND`    | `mock`  | DDS module backend: `mock`, `cyclone`, `rti`, or `auto`. See [DDS support](#dds-support-v020). |
+| `TOPICFORGE_DDS_DOMAIN_ID`  | `0`     | DDS domain id observed (0..232) when a DDS backend is active.                 |
 
 See [`.env.example`](.env.example).
 
@@ -258,6 +290,7 @@ See [`docs/product-plan.md`](docs/product-plan.md) for the full product trajecto
 Near-term additions on the bench:
 
 - `rclpy`-backed live adapter for faster & richer sampling
+- DDS observability module (Cyclone DDS first as an `extras` install — `pip install topicforge[dds]` —, RTI Connext later in the Pro tier). Generalizes the existing `RosAdapter` to a `MiddlewareAdapter` protocol. Same safety-first read-only contract.
 - URDF inspector / validator MCP tools
 - Bag anomaly detection (clock jumps, gaps, dropped frames, TF tree health)
 - Dataset export helpers (rosbag → COCO / HF Datasets)

topicforge-0.2.0/docs/DDS_QUICKSTART.md

@@ -0,0 +1,111 @@
+# DDS quickstart — TopicForge v0.2.0+
+
+A 5-minute tour of TopicForge's DDS observability module. Same safety-first read-only contract as the ROS2 tools — the `MiddlewareAdapter` protocol does not expose a write method, so the MCP client can observe the bus but never publish to it.
+
+This guide does **not** assume you have ROS2 installed.
+
+---
+
+## 1. Mock mode — 30-second demo
+
+The deterministic mock fixtures expose the full DDS tool surface without any DDS SDK or middleware. Useful for evaluating the tools before pulling in a real broker.
+
+```bash
+pip install topicforge
+TOPICFORGE_MODE=mock python -m topicforge
+```
+
+In the spawned MCP client (Claude Desktop, Claude Code, Cursor, ...), the 3 DDS tools are now available alongside the 5 ROS2 tools:
+
+- `list_participants(domain_id=0)` → returns 2 mock participants on domain 0 (vendor `cyclone`, hostnames `mock-robot` and `mock-laptop`).
+- `detect_qos_mismatches(topic=None)` → returns 1 `MismatchReport` for `/dds/qos_mismatch` (deliberate Reliability incompatibility — RELIABLE reader vs BEST_EFFORT writer).
+- `peek_dds_samples(topic="/dds/well_matched", count=3)` → returns 3 deterministic samples ; `peek_dds_samples(topic="/dds/qos_mismatch", count=1)` returns 1 sample with a `qos_note` field annotating the mismatch.
+
+Mock fixtures are stable across runs — you can write integration tests against them.
+
+---
+
+## 2. Live mode with CycloneDDS
+
+Install the DDS extras and select the Cyclone backend:
+
+```bash
+pip install topicforge[dds]
+TOPICFORGE_MODE=live TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
+```
+
+`TOPICFORGE_DDS_BACKEND` accepts `mock` (default), `cyclone`, `rti` (Pro tier, not shipped in v0.2.0), or `auto` (resolves to `cyclone` when `cyclonedds` is importable, else `mock`).
+
+`TOPICFORGE_DDS_DOMAIN_ID` selects the DDS domain (`0..232`, default `0`).
+
+### v0.2.0 stub limitation
+
+The v0.2.0 `CycloneDdsAdapter` ships as a **protocol-compliant stub**: the lazy import, `is_available()`, and factory routing all work, but the 3 DDS tools raise an `AdapterError` with a v0.2.x roadmap pointer when invoked. The real CycloneDDS discovery (builtin topics, QoS pair extraction, typed reader for samples) lands in a v0.2.x patch.
+
+In the meantime, use `TOPICFORGE_DDS_BACKEND=mock` for end-to-end tool testing.
+
+---
+
+## 3. The QoS mismatch scenario
+
+Mock fixtures encode the canonical "subscriber doesn't receive" debugging case. From an MCP client:
+
+```
+> Detect QoS mismatches on the current bus.
+
+[tool call: detect_qos_mismatches]
+[result]
+[
+  {
+    "topic": "/dds/qos_mismatch",
+    "reader_guid": "010f1c2a-3b4c-5d6e-7f80-000000000001",
+    "writer_guid": "010f1c2a-3b4c-5d6e-7f80-000000000002",
+    "incompatible_policies": ["Reliability"],
+    "severity": "incompatible",
+    "mode_effective": "mock"
+  }
+]
+```
+
+An LLM reading this output has enough information to suggest a concrete fix ("the writer is BEST_EFFORT but the reader requires RELIABLE — either relax the reader or upgrade the writer"). That is the diagnostic loop the DDS module is designed to support.
+
+The pure analyzer behind `detect_qos_mismatches` lives in `src/topicforge/adapters/common/qos_analyzer.py` and covers the four MVP policies that explain the bulk of real-world mismatch cases: **Reliability**, **Durability**, **History**, **Deadline**.
+
+---
+
+## 4. Single-adapter limitation (v0.2.0)
+
+TopicForge v0.2.0 selects **one adapter at a time** based on `TOPICFORGE_MODE` + `TOPICFORGE_DDS_BACKEND`:
+
+| `TOPICFORGE_MODE` | `TOPICFORGE_DDS_BACKEND` | Active adapter | ROS2 tools | DDS tools |
+| ----------------- | ------------------------ | -------------- | ---------- | --------- |
+| `mock`            | (any)                    | `MockAdapter`  | work (fixtures) | work (fixtures) |
+| `live` / `auto`   | `mock` (default)         | `Ros2CliAdapter` | work | raise with remediation pointer |
+| `live` / `auto`   | `cyclone`                | `CycloneDdsAdapter` (stub) | raise with remediation pointer | raise with v0.2.x roadmap pointer |
+| `live` / `auto`   | `rti`                    | falls back to `Ros2CliAdapter` (Pro not shipped in v0.2.0) | work | raise |
+
+A composite adapter that delegates per-tool category (ROS2 graph vs DDS layer) is on the v0.2.x roadmap — see `docs/projet-file/mcp-02-spec.md §7`. For now, restart the server with a different `TOPICFORGE_DDS_BACKEND` to switch sides.
+
+The error message from the unselected side is explicit and points at the remediation path — no silent failures.
+
+---
+
+## 5. What's next
+
+- **v0.2.x** — Replace the `CycloneDdsAdapter` stub with real CycloneDDS discovery (`BuiltinTopicDcpsParticipant` for participants, `BuiltinTopicDcpsSubscription`/`Publication` for QoS pair extraction, typed reader on builtin topics first then arbitrary user topics).
+- **v0.2.x** — Composite adapter routing ROS2 tools to `Ros2CliAdapter` and DDS tools to `CycloneDdsAdapter` so both surfaces are usable simultaneously.
+- **v0.3.0+** — `RtiConnextAdapter` in the Pro tier (BYO RTI Connext license, gated by `TOPICFORGE_LICENSE_KEY`).
+- **v0.3.0+** — Extended QoS mismatch coverage (Liveliness, Ownership, Partition, TimeBasedFilter, LatencyBudget).
+
+Full strategic roadmap lives in `docs/product-plan.md §5` (Phase 1 remaining) and `docs/projet-file/mcp-02-spec.md §7` (DDS module phasing).
+
+---
+
+## 6. Troubleshooting
+
+- **`pip install topicforge[dds]` fails on Windows / macOS Python 3.13+** — `cyclonedds` wheels are typically published for Python 3.8 to 3.12. Pin Python 3.11 or 3.12 for the install host.
+- **`pip install topicforge[dds]` fails with `CYCLONEDDS_HOME`** — pip is trying to build `cyclonedds` from source because no wheel matches your platform/Python combination. Either switch to a supported Python (3.11/3.12) or install the native CycloneDDS C library first (see Eclipse CycloneDDS releases).
+- **DDS tool returns "v0.2.0 stub" error** — expected with `TOPICFORGE_DDS_BACKEND=cyclone` in v0.2.0. Use `TOPICFORGE_DDS_BACKEND=mock` for end-to-end testing until the v0.2.x patch lands.
+- **DDS tool returns "DDS module is not active" error** — your `TOPICFORGE_DDS_BACKEND` resolves to neither `cyclone` nor `mock` (likely you're in `live` mode with the default backend). Set `TOPICFORGE_DDS_BACKEND=cyclone` or `=mock` explicitly.
+
+Report issues at https://github.com/yaniswav/TopicForge/issues.

topicforge-0.2.0/docs/MIGRATION_v0.1_to_v0.2.md

@@ -0,0 +1,140 @@
+# Migrating from TopicForge v0.1.x to v0.2.0
+
+Reading time : 5 minutes. v0.2.0 is mostly additive over v0.1.2, but two surfaces are soft-breaking and worth a once-over before you upgrade.
+
+---
+
+## Who needs to read this
+
+| Setup | Action |
+| ----- | ------ |
+| You use TopicForge through Claude Desktop / Claude Code / Cursor / Cline with `pip install topicforge` and no custom code | **Read §1 and §4 only.** Everything else is internal to the server. |
+| You import `topicforge` modules in your own Python code | **Read all sections.** Two soft-breaking changes affect imports and schemas. |
+| You validate MCP responses against a pinned JSON Schema with `additionalProperties: false` | **Read §2 carefully.** v0.2.0 adds optional fields to `TopicInfo` and `HealthReport`. |
+
+---
+
+## 1. New tools and env vars (additive — no migration needed)
+
+v0.2.0 ships 3 new MCP tools alongside the existing 5 ROS2 tools :
+
+- `list_participants(domain_id)` → `list[ParticipantInfo]`
+- `detect_qos_mismatches(topic)` → `list[MismatchReport]`
+- `peek_dds_samples(topic, count)` → `SampleResult`
+
+Existing clients see the new tools the next time they query `list_tools()` ; no client code change required to ignore them.
+
+Two new env vars — both optional, safe defaults :
+
+- `TOPICFORGE_DDS_BACKEND` — `mock | cyclone | rti | auto`, default `mock`. DDS module is opt-in.
+- `TOPICFORGE_DDS_DOMAIN_ID` — `0..232`, default `0`.
+
+If you don't set them, v0.2.0 behaves exactly like v0.1.2 from the client's perspective, plus three new tools that raise an `AdapterError` with a remediation pointer when invoked.
+
+---
+
+## 2. Soft-breaking schema changes
+
+### 2.1 `TopicInfo` schema
+
+Three additive optional fields were added — all default `None` :
+
+- `reader_count: int | None`
+- `writer_count: int | None`
+- `qos_profile: QosProfile | None`
+
+**Producer side** : Python code constructing `TopicInfo` directly is unaffected. The defaults compile and v0.1.x constructor calls still work.
+
+**Client side (over MCP)** : additive on the wire — an MCP client consuming JSON sees three extra optional keys per `TopicInfo` and is unaffected unless it strictly validates against the v0.1.x schema with `additionalProperties: false`. **Strict MCP clients that validated v0.1.x responses against the `TopicInfo` schema with `additionalProperties: false` will reject v0.2.0 responses unless their schema is regenerated. Standard MCP clients that read tool descriptions dynamically are unaffected.**
+
+### 2.2 `HealthReport` schema
+
+Same shape : three additive optional fields with safe defaults :
+
+- `dds_backend: Literal["mock", "cyclone", "rti", "none"] = "none"`
+- `dds_domain_id: int | None = None`
+- `middleware_available: bool = False`
+
+Same remediation as `TopicInfo` — regenerate strict schemas pinned to v0.1.x.
+
+---
+
+## 3. Renamed protocol (backward-compat alias kept)
+
+The `RosAdapter` protocol in `topicforge.adapters.base` has been generalized into `MiddlewareAdapter` — a superset covering both ROS2 graph methods and the new DDS methods under one contract.
+
+```python
+# v0.1.x
+from topicforge.adapters.base import RosAdapter
+
+# v0.2.0 — both still work
+from topicforge.adapters.base import RosAdapter          # backward-compat alias
+from topicforge.adapters.base import MiddlewareAdapter   # canonical name
+```
+
+`RosAdapter` is preserved as a type alias `RosAdapter = MiddlewareAdapter`, so any import of `RosAdapter` keeps type-checking. Internal `Ros2CliAdapter.name` value moved from `"live"` to `"ros2_cli"` — an internal tag, not the MCP-wire `mode_effective` field. The wire-facing `mode_effective: Literal["mock", "live"]` is unchanged.
+
+Two new types live alongside :
+
+- `AdapterName = Literal["mock", "ros2_cli", "cyclone", "rti"]` — internal tag, widened to support DDS.
+- `EffectiveMode = Literal["mock", "live"]` — extracted, wire-facing.
+
+---
+
+## 4. Optional install for DDS
+
+The default install footprint of `pip install topicforge` is **unchanged from v0.1.2**. No new dependency.
+
+To unlock the DDS module on a real broker, opt into the extras :
+
+```bash
+pip install topicforge[dds]
+```
+
+This pulls `cyclonedds>=0.10` (BSD-licensed Python bindings, ~20 MB on install). Mock and ROS2-only installs are unaffected.
+
+`pip install topicforge[all]` is an alias of `[dds]` for now ; future extras will join it.
+
+---
+
+## 5. v0.2.0 MVP limitation
+
+TopicForge v0.2.0 runs **one adapter at a time** — selected by `TOPICFORGE_MODE` plus `TOPICFORGE_DDS_BACKEND`. With `TOPICFORGE_DDS_BACKEND=cyclone`, the 3 DDS tools work and the 5 ROS2 tools raise `AdapterError` with a clear remediation pointer. Reverse holds for the default `TOPICFORGE_DDS_BACKEND=mock`.
+
+A composite adapter that delegates per-tool category is a v0.2.x roadmap item. The full matrix lives in `docs/DDS_QUICKSTART.md §4`.
+
+For end-to-end testing of all 8 tools simultaneously, use `TOPICFORGE_MODE=mock` — the mock adapter serves both ROS2 and DDS surfaces from deterministic fixtures.
+
+---
+
+## 6. Testing the migration
+
+After `pip install --upgrade topicforge`, sanity-check :
+
+```bash
+TOPICFORGE_MODE=mock python -m topicforge
+```
+
+In your MCP client, you should see **8 tools** in `list_tools()`. If you only see 5, the upgrade didn't take effect ; verify with `python -c "import topicforge; print(topicforge.__version__)"` — should be `0.2.0`.
+
+For a real broker test, follow `docs/DDS_QUICKSTART.md §2`.
+
+---
+
+## 7. Rollback
+
+```bash
+pip install "topicforge==0.1.2"
+```
+
+v0.1.x and v0.2.0 share the same MCP wire surface for the 5 ROS2 tools, so a rollback is safe — clients see 5 tools instead of 8, the additive `TopicInfo` fields disappear (back to v0.1.x shape), env vars `TOPICFORGE_DDS_*` are silently ignored.
+
+If you migrated client code to import `MiddlewareAdapter`, switch the import back to `RosAdapter` — the v0.1.x name.
+
+---
+
+## 8. Full changelog
+
+See `CHANGELOG.md` section `[0.2.0] - 2026-05-14` for the complete list of changes, additions, soft-breaks, and notes.
+
+Issues or unexpected migration breaks : https://github.com/yaniswav/TopicForge/issues.