topicforge 0.1.0__py3-none-any.whl

topicforge/__init__.py

@@ -0,0 +1,5 @@
+"""TopicForge — ROS Topic Inspector & Bag Analyzer MCP server."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

topicforge/__main__.py

@@ -0,0 +1,68 @@
+"""Console entrypoint: `python -m topicforge` and the `topicforge` script."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from topicforge import __version__
+from topicforge.config import load_settings
+from topicforge.server import build_app
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="topicforge",
+        description=(
+            "ROS Topic Inspector & Bag Analyzer MCP server. "
+            "Runs on stdio so MCP clients (Claude Desktop, Claude Code, etc.) "
+            "can spawn it directly."
+        ),
+        epilog=(
+            "Configuration is read from environment variables: "
+            "TOPICFORGE_MODE (mock|live|auto, default auto), "
+            "TOPICFORGE_LOG_LEVEL (DEBUG|INFO|WARNING|ERROR, default INFO), "
+            "TOPICFORGE_ROS2_BIN (default 'ros2')."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"topicforge {__version__}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Build the MCP app from environment settings and run it on stdio."""
+    _build_arg_parser().parse_args(argv)
+
+    try:
+        settings = load_settings()
+    except ValueError as exc:
+        print(f"topicforge: configuration error: {exc}", file=sys.stderr)
+        return 2
+
+    logging.basicConfig(
+        level=settings.log_level,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+    log = logging.getLogger("topicforge")
+    log.info("starting (mode=%s)", settings.effective_mode)
+
+    app = build_app(settings)
+    try:
+        app.run()
+    except KeyboardInterrupt:
+        log.info("interrupted by user")
+        return 0
+    except Exception:
+        log.exception("topicforge crashed while serving MCP requests")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

topicforge/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Adapters — the only layer that knows how to talk to a specific backend."""
+
+from topicforge.adapters.base import AdapterError, RosAdapter
+
+__all__ = ["AdapterError", "RosAdapter"]

topicforge/adapters/base.py

@@ -0,0 +1,44 @@
+"""Adapter protocol.
+
+Adapters are the *only* place in the codebase that may know how to talk to a
+specific backend (mock fixtures, the `ros2` CLI, or a future `rclpy` adapter).
+Services depend on this protocol; tools depend on services. That separation
+is what makes the codebase testable without ROS2 installed.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Protocol, runtime_checkable
+
+from topicforge.models import BagAnalysis, MessageSample, TopicInfo
+
+AdapterName = Literal["mock", "live"]
+
+
+class AdapterError(RuntimeError):
+    """Raised when an adapter cannot fulfill a request.
+
+    Carries a clear, user-facing message; tool handlers translate this into
+    a structured error envelope returned to the MCP client.
+    """
+
+
+@runtime_checkable
+class RosAdapter(Protocol):
+    """Uniform read-only interface over a ROS2 environment.
+
+    Implementations must be safe to construct lazily — `is_available()` is
+    the contract for "can this adapter actually serve requests right now?".
+    """
+
+    name: AdapterName
+
+    def is_available(self) -> bool: ...
+
+    def list_topics(self) -> list[TopicInfo]: ...
+
+    def get_topic_info(self, topic: str) -> TopicInfo: ...
+
+    def sample_messages(self, topic: str, count: int) -> list[MessageSample]: ...
+
+    def analyze_bag(self, path: str) -> BagAnalysis: ...

topicforge/adapters/ros2_live/__init__.py

@@ -0,0 +1,5 @@
+"""Live adapter — thin wrappers over the `ros2` CLI."""
+
+from topicforge.adapters.ros2_live.adapter import Ros2CliAdapter
+
+__all__ = ["Ros2CliAdapter"]

topicforge/adapters/ros2_live/adapter.py

@@ -0,0 +1,283 @@
+"""Live adapter — defensive wrappers over the `ros2` CLI.
+
+Why CLI and not `rclpy`?
+  * `rclpy` is hard to depend on portably — distro-pinned, requires a sourced
+    setup file, and ships with the ROS2 install rather than from PyPI.
+  * The `ros2` CLI is stable, widely available wherever ROS2 is installed,
+    and trivial to mock in tests by stubbing `subprocess.run`.
+  * A richer `rclpy`-backed adapter can ship later behind the same protocol.
+    See `# TODO(roadmap): rclpy-backed adapter` below.
+
+Public methods never raise raw subprocess errors. They raise `AdapterError`
+with a message that is safe to surface to an MCP client.
+
+The pure parsers at module level are split out from the adapter class so
+they can be unit-tested without a running ROS2 install.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from topicforge.adapters.base import AdapterError, AdapterName
+from topicforge.models import BagAnalysis, BagTopicStats, MessageSample, TopicInfo
+
+log = logging.getLogger(__name__)
+
+_DEFAULT_TIMEOUT_SEC = 8.0
+_SAMPLE_TIMEOUT_SEC = 3.0
+
+
+class Ros2CliAdapter:
+    """Adapter that shells out to the `ros2` CLI."""
+
+    name: AdapterName = "live"
+
+    def __init__(self, executable: str = "ros2") -> None:
+        self._exe = executable
+
+    def is_available(self) -> bool:
+        return shutil.which(self._exe) is not None
+
+    # ----------------------------- topics --------------------------------
+
+    def list_topics(self) -> list[TopicInfo]:
+        out = self._run([self._exe, "topic", "list", "-t"])
+        topics: list[TopicInfo] = []
+        for name, msg_type in parse_topic_list(out):
+            pub_count, sub_count = self._safe_counts(name)
+            topics.append(
+                TopicInfo(
+                    name=name,
+                    message_type=msg_type,
+                    publisher_count=pub_count,
+                    subscriber_count=sub_count,
+                )
+            )
+        return topics
+
+    def get_topic_info(self, topic: str) -> TopicInfo:
+        out = self._run([self._exe, "topic", "info", topic, "--verbose"])
+        info = parse_topic_info(out, fallback_name=topic)
+        if info is None:
+            raise AdapterError(f"Topic not found or empty info: {topic!r}")
+        return info
+
+    def sample_messages(self, topic: str, count: int) -> list[MessageSample]:
+        # `ros2 topic echo` blocks indefinitely; --once + bounded timeout is the
+        # safe MVP shape. Richer windowed sampling is a roadmap item.
+        # TODO(roadmap): rclpy-backed adapter — windowed echo, time-range,
+        # better deserialization of complex message payloads.
+        if count <= 0:
+            return []
+
+        info = self.get_topic_info(topic)
+        try:
+            out = self._run(
+                [self._exe, "topic", "echo", "--once", topic],
+                timeout=_SAMPLE_TIMEOUT_SEC,
+            )
+        except AdapterError as exc:
+            log.info("sample_messages on %s returned no data: %s", topic, exc)
+            return []
+
+        return [
+            MessageSample(
+                topic=topic,
+                message_type=info.message_type,
+                timestamp_ns=0,
+                payload=parse_echo_yaml(out),
+            )
+        ]
+
+    # ------------------------------ bag ----------------------------------
+
+    def analyze_bag(self, path: str) -> BagAnalysis:
+        bag_path = Path(path)
+        if not bag_path.exists():
+            raise AdapterError(f"Bag path does not exist: {path}")
+
+        out = self._run([self._exe, "bag", "info", str(bag_path)])
+        return parse_bag_info(out, fallback_path=str(bag_path))
+
+    # ---------------------------- internals ------------------------------
+
+    def _safe_counts(self, topic: str) -> tuple[int, int]:
+        """Return (pub_count, sub_count) for a topic, defaulting to (0, 0).
+
+        Failing to fetch counts for a single topic must not break `list_topics`.
+        """
+        try:
+            text = self._run([self._exe, "topic", "info", topic])
+        except AdapterError:
+            return (0, 0)
+        return parse_pub_sub_counts(text)
+
+    def _run(self, cmd: list[str], timeout: float = _DEFAULT_TIMEOUT_SEC) -> str:
+        # Resolve the executable to a full path so Windows .cmd/.bat shims work
+        # without shell=True.
+        resolved = shutil.which(cmd[0]) if cmd[0] == self._exe else cmd[0]
+        if resolved is None:
+            raise AdapterError(f"`{self._exe}` not found on PATH. Source your ROS2 setup file.")
+        full_cmd = [resolved, *cmd[1:]]
+
+        log.debug("ros2 cmd: %s", " ".join(full_cmd))
+        try:
+            result = subprocess.run(
+                full_cmd,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                check=False,
+            )
+        except FileNotFoundError as exc:
+            raise AdapterError(
+                f"`{self._exe}` not found on PATH. Source your ROS2 setup file."
+            ) from exc
+        except subprocess.TimeoutExpired as exc:
+            raise AdapterError(f"`{' '.join(cmd)}` timed out after {timeout}s") from exc
+
+        if result.returncode != 0:
+            stderr_tail = ""
+            if result.stderr:
+                lines = [line for line in result.stderr.strip().splitlines() if line]
+                if lines:
+                    stderr_tail = lines[-1]
+            raise AdapterError(
+                f"`{' '.join(cmd)}` failed (exit {result.returncode}): {stderr_tail or 'no stderr'}"
+            )
+        return result.stdout
+
+
+# ---------------------------------------------------------------------------
+# Pure parsers — unit-testable without ROS2 present.
+# ---------------------------------------------------------------------------
+
+_LIST_LINE = re.compile(r"^(\S+)\s+\[(.+)\]\s*$")
+_TYPE_LINE = re.compile(r"^\s*Type:\s*(.+)$")
+_PUB_COUNT = re.compile(r"^\s*Publisher count:\s*(\d+)\s*$")
+_SUB_COUNT = re.compile(r"^\s*Subscription count:\s*(\d+)\s*$")
+_BAG_DUR = re.compile(r"Duration:\s*([\d.]+)\s*s")
+_BAG_COUNT = re.compile(r"Messages:\s*(\d+)")
+_BAG_STORAGE = re.compile(r"Storage id:\s*(\S+)")
+_BAG_TOPIC = re.compile(
+    r"Topic:\s*(\S+)\s*\|\s*Type:\s*(\S+)\s*\|\s*Count:\s*(\d+)\s*\|\s*Serialization Format:"
+)
+
+
+def parse_topic_list(stdout: str) -> list[tuple[str, str]]:
+    """Parse `ros2 topic list -t` output. Returns (name, type) pairs."""
+    pairs: list[tuple[str, str]] = []
+    for raw in stdout.splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        m = _LIST_LINE.match(line)
+        if m:
+            pairs.append((m.group(1), m.group(2)))
+    return pairs
+
+
+def parse_pub_sub_counts(stdout: str) -> tuple[int, int]:
+    """Parse publisher / subscription counts from `ros2 topic info` output."""
+    pub = sub = 0
+    for line in stdout.splitlines():
+        if m := _PUB_COUNT.match(line):
+            pub = int(m.group(1))
+        elif m := _SUB_COUNT.match(line):
+            sub = int(m.group(1))
+    return pub, sub
+
+
+def parse_topic_info(stdout: str, *, fallback_name: str) -> TopicInfo | None:
+    """Parse `ros2 topic info <topic> --verbose` output into a TopicInfo.
+
+    Returns None if no message type was found, which the adapter treats as
+    "topic not found".
+    """
+    msg_type: str | None = None
+    pub = sub = 0
+    for line in stdout.splitlines():
+        if m := _TYPE_LINE.match(line):
+            msg_type = m.group(1).strip()
+        elif m := _PUB_COUNT.match(line):
+            pub = int(m.group(1))
+        elif m := _SUB_COUNT.match(line):
+            sub = int(m.group(1))
+    if msg_type is None:
+        return None
+    return TopicInfo(
+        name=fallback_name,
+        message_type=msg_type,
+        publisher_count=pub,
+        subscriber_count=sub,
+    )
+
+
+# TODO(roadmap): rclpy-backed adapter will return native typed payloads
+# and make this parser obsolete. See docs/product-plan.md Phase 1.
+def parse_echo_yaml(stdout: str) -> dict[str, object]:
+    """Best-effort parse of `ros2 topic echo --once` YAML-ish output.
+
+    We deliberately avoid a hard YAML dependency for the MVP — instead we emit
+    a flat `{key: value}` dict (top-level keys only) plus the raw text under
+    a reserved `_raw_text` key. LLMs can still reason over the raw text, and
+    downstream tools can upgrade this parser without changing the contract.
+
+    `_raw_text` is intentionally not dunder-named (no leading/trailing `__`):
+    a dunder key signals Python special-attribute semantics, which this is
+    not. A single leading underscore is enough to flag it as parser metadata
+    while keeping it a plain dict key.
+    """
+    flat: dict[str, object] = {}
+    for raw in stdout.splitlines():
+        line = raw.rstrip()
+        stripped = line.lstrip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        # Top-level keys only (no indentation).
+        if line == stripped and ":" in line:
+            key, _, value = line.partition(":")
+            flat[key.strip()] = value.strip()
+    flat["_raw_text"] = stdout
+    return flat
+
+
+def parse_bag_info(stdout: str, *, fallback_path: str) -> BagAnalysis:
+    """Parse `ros2 bag info <path>` text output into a BagAnalysis."""
+    duration = 0.0
+    msg_count = 0
+    storage: str | None = None
+    topics: list[BagTopicStats] = []
+
+    for line in stdout.splitlines():
+        if m := _BAG_DUR.search(line):
+            duration = float(m.group(1))
+        if m := _BAG_COUNT.search(line):
+            msg_count = int(m.group(1))
+        if m := _BAG_STORAGE.search(line):
+            storage = m.group(1)
+        if m := _BAG_TOPIC.search(line):
+            name, msg_type, count = m.group(1), m.group(2), int(m.group(3))
+            freq = (count / duration) if duration > 0 else None
+            topics.append(
+                BagTopicStats(
+                    name=name,
+                    message_type=msg_type,
+                    message_count=count,
+                    frequency_hz=freq,
+                )
+            )
+
+    return BagAnalysis(
+        path=fallback_path,
+        storage_format=storage,
+        duration_seconds=duration,
+        message_count=msg_count,
+        topics=topics,
+        anomalies=[],
+    )

topicforge/adapters/ros2_mock/__init__.py

@@ -0,0 +1,5 @@
+"""Deterministic mock adapter for development, tests, and demos."""
+
+from topicforge.adapters.ros2_mock.adapter import MockAdapter
+
+__all__ = ["MockAdapter"]

topicforge/adapters/ros2_mock/adapter.py

@@ -0,0 +1,68 @@
+"""Mock adapter — deterministic fixtures for development, tests, and demos.
+
+Always available. Outputs are stable across runs so tests can assert on
+exact values.
+"""
+
+from __future__ import annotations
+
+from pathlib import PurePosixPath, PureWindowsPath
+
+from topicforge.adapters.base import AdapterError, AdapterName
+from topicforge.adapters.ros2_mock import fixtures
+from topicforge.models import BagAnalysis, MessageSample, TopicInfo
+
+# Extensions the live `ros2 bag info` accepts. The mock mirrors this list so
+# a test that passes `/tmp/demo.txt` fails in mock the same way it would in
+# live — otherwise mock mode would hide a real-world UX problem until the
+# first ROS2 install.
+_BAG_EXTENSIONS: frozenset[str] = frozenset({".mcap", ".db3", ".bag"})
+
+
+class MockAdapter:
+    name: AdapterName = "mock"
+
+    def is_available(self) -> bool:
+        return True
+
+    def list_topics(self) -> list[TopicInfo]:
+        return list(fixtures.MOCK_TOPICS)
+
+    def get_topic_info(self, topic: str) -> TopicInfo:
+        for t in fixtures.MOCK_TOPICS:
+            if t.name == topic:
+                return t
+        raise AdapterError(f"Unknown topic: {topic!r}")
+
+    def sample_messages(self, topic: str, count: int) -> list[MessageSample]:
+        if count < 0:
+            raise AdapterError("count must be >= 0")
+        # Validate the topic exists first so the error is the same as `get_topic_info`.
+        self.get_topic_info(topic)
+        return fixtures.mock_samples_for(topic, count)
+
+    def analyze_bag(self, path: str) -> BagAnalysis:
+        _reject_non_bag_path(path)
+        # The fixture is frozen; produce a copy with the caller's path.
+        return fixtures.MOCK_BAG_ANALYSIS.model_copy(update={"path": path})
+
+
+def _reject_non_bag_path(path: str) -> None:
+    """Reject paths the live `ros2 bag info` would obviously refuse.
+
+    Accepts: `.mcap` / `.db3` / `.bag` files, and any extensionless path
+    (which could legitimately be a `rosbag2_*` directory). Rejects every
+    other extension so mock demos surface the same shape of error a
+    real ROS2 install would produce on, e.g., `/tmp/note.txt`.
+    """
+    # `PurePosixPath` handles `/tmp/foo.mcap`; `PureWindowsPath` handles
+    # `C:\demos\foo.mcap`. The longest suffix wins.
+    posix_suffix = PurePosixPath(path).suffix.lower()
+    win_suffix = PureWindowsPath(path).suffix.lower()
+    suffix = posix_suffix or win_suffix
+    if suffix and suffix not in _BAG_EXTENSIONS:
+        raise AdapterError(
+            f"path does not look like a ROS2 bag (got suffix {suffix!r}); "
+            f"expected one of {sorted(_BAG_EXTENSIONS)} or a "
+            "`rosbag2_*` directory"
+        )

topicforge/adapters/ros2_mock/fixtures.py

@@ -0,0 +1,172 @@
+"""Deterministic fake-robot fixtures used by `MockAdapter`.
+
+These model a small differential-drive mobile robot with a 2D LIDAR, an
+RGB camera, and a TF tree. The data is rich enough to make demos and
+screenshots believable, and stable enough for tests to assert on exact
+values.
+
+If you change a value here, expect to update tests under `tests/`.
+"""
+
+from __future__ import annotations
+
+from topicforge.models import BagAnalysis, BagTopicStats, MessageSample, TopicInfo
+
+MOCK_TOPICS: tuple[TopicInfo, ...] = (
+    TopicInfo(
+        name="/cmd_vel",
+        message_type="geometry_msgs/msg/Twist",
+        publisher_count=1,
+        subscriber_count=1,
+        qos_reliability="reliable",
+    ),
+    TopicInfo(
+        name="/odom",
+        message_type="nav_msgs/msg/Odometry",
+        publisher_count=1,
+        subscriber_count=2,
+        qos_reliability="reliable",
+    ),
+    TopicInfo(
+        name="/scan",
+        message_type="sensor_msgs/msg/LaserScan",
+        publisher_count=1,
+        subscriber_count=1,
+        qos_reliability="best_effort",
+    ),
+    TopicInfo(
+        name="/tf",
+        message_type="tf2_msgs/msg/TFMessage",
+        publisher_count=3,
+        subscriber_count=2,
+        qos_reliability="reliable",
+    ),
+    TopicInfo(
+        name="/camera/image_raw",
+        message_type="sensor_msgs/msg/Image",
+        publisher_count=1,
+        subscriber_count=1,
+        qos_reliability="best_effort",
+    ),
+)
+
+
+_BASE_TS_NS = 1_700_000_000_000_000_000
+
+
+_MOCK_SAMPLES: dict[str, list[MessageSample]] = {
+    "/cmd_vel": [
+        MessageSample(
+            topic="/cmd_vel",
+            message_type="geometry_msgs/msg/Twist",
+            timestamp_ns=_BASE_TS_NS + i * 100_000_000,
+            payload={
+                "linear": {"x": 0.20 + i * 0.01, "y": 0.0, "z": 0.0},
+                "angular": {"x": 0.0, "y": 0.0, "z": 0.05 * i},
+            },
+        )
+        for i in range(5)
+    ],
+    "/odom": [
+        MessageSample(
+            topic="/odom",
+            message_type="nav_msgs/msg/Odometry",
+            timestamp_ns=_BASE_TS_NS + i * 100_000_000,
+            payload={
+                "header": {"frame_id": "odom", "stamp_sec": 1_700_000_000 + i},
+                "pose": {"position": {"x": 0.1 * i, "y": 0.0, "z": 0.0}},
+                "twist": {"linear": {"x": 0.2}, "angular": {"z": 0.0}},
+            },
+        )
+        for i in range(5)
+    ],
+    "/scan": [
+        MessageSample(
+            topic="/scan",
+            message_type="sensor_msgs/msg/LaserScan",
+            timestamp_ns=_BASE_TS_NS + i * 50_000_000,
+            payload={
+                "header": {"frame_id": "laser", "stamp_sec": 1_700_000_000 + i},
+                "angle_min": -3.14,
+                "angle_max": 3.14,
+                "range_min": 0.05,
+                "range_max": 12.0,
+                "ranges_summary": {"min": 0.32, "max": 11.5, "n": 720},
+            },
+        )
+        for i in range(3)
+    ],
+    "/tf": [
+        MessageSample(
+            topic="/tf",
+            message_type="tf2_msgs/msg/TFMessage",
+            timestamp_ns=_BASE_TS_NS + i * 100_000_000,
+            payload={
+                "transforms": [
+                    {"frame_id": "odom", "child_frame_id": "base_link"},
+                    {"frame_id": "base_link", "child_frame_id": "laser"},
+                ]
+            },
+        )
+        for i in range(2)
+    ],
+    "/camera/image_raw": [
+        MessageSample(
+            topic="/camera/image_raw",
+            message_type="sensor_msgs/msg/Image",
+            timestamp_ns=_BASE_TS_NS,
+            payload={
+                "header": {"frame_id": "camera", "stamp_sec": 1_700_000_000},
+                "width": 640,
+                "height": 480,
+                "encoding": "rgb8",
+                "data_summary": "<binary 921600 bytes elided>",
+            },
+        )
+    ],
+}
+
+
+def mock_samples_for(topic: str, count: int) -> list[MessageSample]:
+    """Return up to `count` deterministic samples for `topic`. Empty if unknown."""
+    return list(_MOCK_SAMPLES.get(topic, [])[:count])
+
+
+MOCK_BAG_ANALYSIS = BagAnalysis(
+    path="<mock>",
+    storage_format="mcap",
+    duration_seconds=42.5,
+    message_count=1287,
+    topics=[
+        BagTopicStats(
+            name="/cmd_vel",
+            message_type="geometry_msgs/msg/Twist",
+            message_count=425,
+            frequency_hz=10.0,
+        ),
+        BagTopicStats(
+            name="/odom",
+            message_type="nav_msgs/msg/Odometry",
+            message_count=425,
+            frequency_hz=10.0,
+        ),
+        BagTopicStats(
+            name="/scan",
+            message_type="sensor_msgs/msg/LaserScan",
+            message_count=425,
+            frequency_hz=10.0,
+        ),
+        BagTopicStats(
+            name="/tf",
+            message_type="tf2_msgs/msg/TFMessage",
+            message_count=12,
+            frequency_hz=0.28,
+        ),
+    ],
+    # TODO(roadmap): bag anomaly detection — replace these canned strings with
+    # output from a real anomaly detector (clock jumps, frame drops, TF gaps).
+    anomalies=[
+        "/scan: 3 frames dropped between t=10.1s and t=10.4s",
+        "/tf: static transforms only — no dynamic updates during recording",
+    ],
+)

topicforge/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration & runtime mode resolution."""
+
+from topicforge.config.settings import Mode, ResolvedMode, Settings, load_settings
+
+__all__ = ["Mode", "ResolvedMode", "Settings", "load_settings"]