topicforge 0.1.0__py3-none-any.whl

topicforge/config/settings.py

@@ -0,0 +1,68 @@
+"""Runtime settings, resolved from environment variables.
+
+Settings are immutable and constructed once at startup. The `auto` mode is
+resolved against the current environment by `Settings.effective_mode` —
+keeping that decision in one place avoids drift between callers.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from dataclasses import dataclass
+from typing import Literal
+
+Mode = Literal["mock", "live", "auto"]
+ResolvedMode = Literal["mock", "live"]
+
+_VALID_MODES: tuple[Mode, ...] = ("mock", "live", "auto")
+_VALID_LOG_LEVELS: tuple[str, ...] = ("DEBUG", "INFO", "WARNING", "ERROR")
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """Immutable runtime configuration."""
+
+    mode: Mode
+    log_level: str
+    ros2_executable: str
+
+    @property
+    def effective_mode(self) -> ResolvedMode:
+        """Resolve `auto` against the current environment.
+
+        `live` and `mock` are returned as-is; `auto` becomes `live` when the
+        configured ROS2 executable is on PATH, otherwise `mock`. The factory
+        in `services/factory.py` is responsible for final fallback if a live
+        adapter cannot actually start.
+
+        Predictive resolution only. Final operational fallback (when the live
+        adapter is instantiable but cannot actually start) lives in
+        `services/factory.py:build_adapter`.
+        """
+        if self.mode == "auto":
+            return "live" if shutil.which(self.ros2_executable) else "mock"
+        return self.mode
+
+
+def load_settings(env: dict[str, str] | os._Environ[str] | None = None) -> Settings:
+    """Build a Settings from the given environment (defaults to `os.environ`).
+
+    The `env` parameter is injectable so tests can avoid leaking process
+    state and pin behavior deterministically.
+    """
+    src = env if env is not None else os.environ
+
+    raw_mode = src.get("TOPICFORGE_MODE", "auto").strip().lower()
+    if raw_mode not in _VALID_MODES:
+        raise ValueError(f"Invalid TOPICFORGE_MODE={raw_mode!r}; expected one of {_VALID_MODES}")
+
+    raw_log = src.get("TOPICFORGE_LOG_LEVEL", "INFO").strip().upper()
+    if raw_log not in _VALID_LOG_LEVELS:
+        raise ValueError(
+            f"Invalid TOPICFORGE_LOG_LEVEL={raw_log!r}; expected one of {_VALID_LOG_LEVELS}"
+        )
+
+    ros2_exe = src.get("TOPICFORGE_ROS2_BIN", "ros2").strip() or "ros2"
+
+    return Settings(mode=raw_mode, log_level=raw_log, ros2_executable=ros2_exe)

topicforge/models/__init__.py

@@ -0,0 +1,19 @@
+"""Pydantic schemas — the contract between TopicForge and MCP clients."""
+
+from topicforge.models.schemas import (
+    BagAnalysis,
+    BagTopicStats,
+    HealthReport,
+    MessageSample,
+    SampleResult,
+    TopicInfo,
+)
+
+__all__ = [
+    "BagAnalysis",
+    "BagTopicStats",
+    "HealthReport",
+    "MessageSample",
+    "SampleResult",
+    "TopicInfo",
+]

topicforge/models/schemas.py

@@ -0,0 +1,158 @@
+"""Tool input/output schemas.
+
+Models are deliberately small, frozen, and JSON-friendly so MCP clients
+(particularly LLMs) can reason about them without ambiguity. `extra="forbid"`
+keeps adapters honest — an accidental extra key fails fast in tests rather
+than silently propagating to clients.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+_CONFIG = ConfigDict(extra="forbid", frozen=True)
+
+
+class TopicInfo(BaseModel):
+    """Description of a single ROS2 topic."""
+
+    model_config = _CONFIG
+
+    name: str = Field(description="Fully qualified topic name, e.g. `/cmd_vel`.")
+    message_type: str = Field(description="ROS2 message type, e.g. `geometry_msgs/msg/Twist`.")
+    publisher_count: int = Field(ge=0, description="Publishers known to the graph.")
+    subscriber_count: int = Field(ge=0, description="Subscribers known to the graph.")
+    qos_reliability: str | None = Field(
+        default=None,
+        description="QoS reliability policy if known: `reliable` or `best_effort`.",
+    )
+
+
+class MessageSample(BaseModel):
+    """A single sampled message on a topic."""
+
+    model_config = _CONFIG
+
+    topic: str = Field(
+        description="Fully qualified topic name the sample was taken from, e.g. `/cmd_vel`."
+    )
+    message_type: str = Field(
+        description="ROS2 message type of this sample, e.g. `geometry_msgs/msg/Twist`."
+    )
+    timestamp_ns: int = Field(
+        description=(
+            "Receive timestamp in nanoseconds since epoch. **Always 0 in the MVP "
+            "live adapter** (which shells out to `ros2 topic echo --once` and has "
+            "no access to the original receive time); a future rclpy-backed "
+            "adapter will populate this. Mock mode emits monotonically "
+            "increasing values for deterministic ordering."
+        )
+    )
+    payload: dict[str, object] = Field(
+        default_factory=dict,
+        description=(
+            "Structured message payload. **In live mode the MVP parser only "
+            "extracts top-level keys**; nested fields and the full YAML text "
+            "are preserved verbatim under the reserved `_raw_text` key for the "
+            "client to handle. In mock mode the payload is fully structured "
+            "and `_raw_text` is absent. Large messages (e.g. images) may be "
+            "summarized to keep tool output bounded."
+        ),
+    )
+
+
+class BagTopicStats(BaseModel):
+    """Per-topic statistics inside a bag analysis result."""
+
+    model_config = _CONFIG
+
+    name: str = Field(description="Fully qualified topic name as recorded in the bag.")
+    message_type: str = Field(description="ROS2 message type recorded for this topic.")
+    message_count: int = Field(
+        ge=0, description="Number of messages recorded on this topic across the bag."
+    )
+    frequency_hz: float | None = Field(
+        default=None,
+        ge=0,
+        description="Average rate (messages / bag duration) when computable, else `null`.",
+    )
+
+
+class BagAnalysis(BaseModel):
+    """Structured summary of a ROS2 bag."""
+
+    model_config = _CONFIG
+
+    path: str = Field(
+        description=(
+            "Path to the analyzed bag, as supplied by the caller. May point to a "
+            "file (`.mcap`, `.db3`, `.bag`) or to a `rosbag2_*` directory."
+        )
+    )
+    storage_format: str | None = Field(
+        default=None,
+        description="`mcap`, `sqlite3`, or other storage identifier when known.",
+    )
+    duration_seconds: float = Field(
+        ge=0,
+        description="Total bag duration, in seconds (wall clock between first and last message).",
+    )
+    message_count: int = Field(
+        ge=0, description="Total number of messages across all recorded topics."
+    )
+    topics: list[BagTopicStats] = Field(
+        description="Per-topic statistics for every topic present in the bag."
+    )
+    anomalies: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Human-readable notes about gaps, clock jumps, or other oddities. "
+            "MVP populates this in mock mode; live anomaly detection is roadmap."
+        ),
+    )
+
+
+class SampleResult(BaseModel):
+    """Envelope returned by the `sample_messages` tool."""
+
+    model_config = _CONFIG
+
+    topic: str = Field(description="Topic the samples were taken from, echoed from the request.")
+    count: int = Field(
+        ge=0,
+        description=(
+            "Number of samples actually returned. May be 0 (no publisher active "
+            "in live mode, or empty mock fixture), less than the requested count "
+            "(topic yielded fewer messages within the timeout), or capped by the "
+            "MVP's silent maximum of 50 — request `count > 50` and you will "
+            "receive at most 50 without warning."
+        ),
+    )
+    samples: list[MessageSample] = Field(
+        description="The sampled messages, ordered as received from the backend."
+    )
+
+
+class HealthReport(BaseModel):
+    """Result of `health_check`. Always succeeds, even when the host is unhealthy."""
+
+    model_config = _CONFIG
+
+    mode: str = Field(description="Effective runtime mode: `mock` or `live`.")
+    requested_mode: str = Field(description="Mode requested via configuration (may be `auto`).")
+    ros2_available: bool = Field(description="Whether a `ros2` CLI is on PATH.")
+    ros2_distro: str | None = Field(
+        default=None, description="Value of `ROS_DISTRO` if set in the environment."
+    )
+    server_version: str = Field(
+        description="TopicForge server version (matches the PyPI release of the `topicforge` package)."
+    )
+    max_sample_count: int = Field(
+        ge=0,
+        description=(
+            "Server-side cap on the number of samples returned per "
+            "`sample_messages` call. Requests above this limit are silently "
+            "clamped; the value is exposed here so a client can size its "
+            "requests proactively. Constant in v0.1.0."
+        ),
+    )

topicforge/server/__init__.py

@@ -0,0 +1,5 @@
+"""MCP server bootstrap & lifecycle."""
+
+from topicforge.server.app import build_app
+
+__all__ = ["build_app"]

topicforge/server/app.py

@@ -0,0 +1,43 @@
+"""MCP server bootstrap.
+
+Wires settings → adapter → services → tools → FastMCP. This module is the
+only place that knows the full dependency graph; everything else stays
+narrowly scoped.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from mcp.server.fastmcp import FastMCP
+
+from topicforge import __version__
+from topicforge.config import Settings, load_settings
+from topicforge.services import HealthService, Inspector, build_adapter
+from topicforge.tools import register_tools
+
+log = logging.getLogger(__name__)
+
+
+def build_app(settings: Settings | None = None) -> FastMCP:
+    """Construct a fully wired FastMCP application.
+
+    `settings` is optional so tests can build the app with deterministic
+    configuration; production callers (`python -m topicforge`) pass nothing
+    and pick up settings from the environment.
+    """
+    settings = settings or load_settings()
+    adapter = build_adapter(settings)
+    inspector = Inspector(adapter)
+    health = HealthService(settings)
+
+    mcp = FastMCP("topicforge")
+    register_tools(mcp, inspector, health)
+
+    log.info(
+        "topicforge %s ready (mode=%s, adapter=%s)",
+        __version__,
+        settings.effective_mode,
+        adapter.name,
+    )
+    return mcp

topicforge/services/__init__.py

@@ -0,0 +1,7 @@
+"""Domain services — orchestration between tool handlers and adapters."""
+
+from topicforge.services.factory import build_adapter
+from topicforge.services.health import HealthService
+from topicforge.services.inspector import Inspector
+
+__all__ = ["HealthService", "Inspector", "build_adapter"]

topicforge/services/factory.py

@@ -0,0 +1,39 @@
+"""Adapter selection.
+
+This is the only place that knows how to map a `Settings` to a concrete
+adapter, and where graceful degradation from `live` → `mock` happens.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from topicforge.adapters.base import RosAdapter
+from topicforge.adapters.ros2_live import Ros2CliAdapter
+from topicforge.adapters.ros2_mock import MockAdapter
+from topicforge.config import Settings
+
+log = logging.getLogger(__name__)
+
+
+def build_adapter(settings: Settings) -> RosAdapter:
+    """Return the adapter matching the effective runtime mode.
+
+    If `live` is requested but the `ros2` CLI is missing, falls back to mock
+    and logs a warning. This is intentional: it keeps the MCP server usable
+    on a developer laptop without ROS2 installed.
+
+    Predictive resolution (mode `auto` → live or mock based on PATH) lives in
+    `config/settings.py:Settings.effective_mode`.
+    """
+    mode = settings.effective_mode
+    if mode == "live":
+        adapter = Ros2CliAdapter(executable=settings.ros2_executable)
+        if not adapter.is_available():
+            log.warning(
+                "live mode requested but %r not on PATH; falling back to mock",
+                settings.ros2_executable,
+            )
+            return MockAdapter()
+        return adapter
+    return MockAdapter()

topicforge/services/health.py

@@ -0,0 +1,32 @@
+"""Health service — environment & mode introspection."""
+
+from __future__ import annotations
+
+import os
+import shutil
+
+from topicforge import __version__
+from topicforge.config import Settings
+from topicforge.models import HealthReport
+from topicforge.services.inspector import MAX_SAMPLE_COUNT
+
+
+class HealthService:
+    def __init__(self, settings: Settings) -> None:
+        self._settings = settings
+
+    def report(self) -> HealthReport:
+        """Build a HealthReport for the current environment.
+
+        Never raises. `health_check` is the tool a user will reach for when
+        things look broken, so it must always answer.
+        """
+        ros2_path = shutil.which(self._settings.ros2_executable)
+        return HealthReport(
+            mode=self._settings.effective_mode,
+            requested_mode=self._settings.mode,
+            ros2_available=ros2_path is not None,
+            ros2_distro=os.environ.get("ROS_DISTRO"),
+            server_version=__version__,
+            max_sample_count=MAX_SAMPLE_COUNT,
+        )

topicforge/services/inspector.py

@@ -0,0 +1,92 @@
+"""Inspector — the domain layer between MCP tool handlers and adapters.
+
+Tools call the Inspector. The Inspector validates inputs, delegates to the
+adapter, and ensures outputs are well-formed regardless of backend.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from topicforge.adapters.base import AdapterError, AdapterName, RosAdapter
+from topicforge.models import BagAnalysis, MessageSample, TopicInfo
+
+DEFAULT_SAMPLE_COUNT = 5
+MAX_SAMPLE_COUNT = 50
+
+# Strict allowlist mirroring ROS2 topic-name conventions:
+#   * must start with `/`
+#   * one or more segments separated by single `/`
+#   * each segment starts with a letter or underscore, then [A-Za-z0-9_]*
+# This rejects `//`, trailing `/`, digit-leading segments, dashes, dots, and
+# every shell metacharacter before any value reaches the `ros2` CLI.
+_TOPIC_NAME_RE = re.compile(r"^/[A-Za-z_][A-Za-z0-9_]*(?:/[A-Za-z_][A-Za-z0-9_]*)*$")
+
+
+class Inspector:
+    """Validation and orchestration layer between MCP tool handlers and ROS adapters.
+
+    All MCP-level input normalization happens here (topic name format, count clamping,
+    path validation) so adapters can assume well-formed inputs. Today some methods are
+    thin pass-throughs to the adapter; they remain in this layer to keep the contract
+    surface symmetric — every tool goes through the same gate.
+    """
+
+    def __init__(self, adapter: RosAdapter) -> None:
+        self._adapter = adapter
+
+    @property
+    def backend_name(self) -> AdapterName:
+        return self._adapter.name
+
+    def list_topics(self) -> list[TopicInfo]:
+        return self._adapter.list_topics()
+
+    def get_topic_info(self, topic: str) -> TopicInfo:
+        _validate_topic_name(topic)
+        return self._adapter.get_topic_info(topic)
+
+    def sample_messages(self, topic: str, count: int | None = None) -> list[MessageSample]:
+        _validate_topic_name(topic)
+        n = DEFAULT_SAMPLE_COUNT if count is None else count
+        if n < 0:
+            raise AdapterError("count must be >= 0")
+        return self._adapter.sample_messages(topic, min(n, MAX_SAMPLE_COUNT))
+
+    def analyze_bag(self, path: str) -> BagAnalysis:
+        return self._adapter.analyze_bag(_validate_bag_path(path))
+
+
+def _validate_topic_name(topic: str) -> None:
+    if not topic or not topic.strip():
+        raise AdapterError("topic must be a non-empty string")
+    if not topic.startswith("/"):
+        raise AdapterError(f"topic must start with '/' (got {topic!r})")
+    if not _TOPIC_NAME_RE.match(topic):
+        raise AdapterError(
+            f"topic name is malformed (got {topic!r}); each `/`-separated "
+            "segment must start with a letter or underscore and contain only "
+            "letters, digits, and underscores (no `//`, no trailing `/`)"
+        )
+
+
+def _validate_bag_path(path: str) -> str:
+    """Validate and normalize a bag path before it reaches an adapter.
+
+    Returns the stripped path. Raises `AdapterError` for empty, blank,
+    null-byte-containing, or otherwise malformed paths. Does NOT check
+    existence or extension — that is the live adapter's responsibility.
+    """
+    if not isinstance(path, str):
+        raise AdapterError("path must be a string")
+    if not path or not path.strip():
+        raise AdapterError("path must be a non-empty string")
+    clean = path.strip()
+    if "\x00" in clean:
+        raise AdapterError("path must not contain null bytes")
+    try:
+        Path(clean)
+    except (ValueError, OSError) as exc:
+        raise AdapterError(f"path is not a valid filesystem path: {exc}") from exc
+    return clean

topicforge/tools/__init__.py

@@ -0,0 +1,5 @@
+"""MCP tool registration."""
+
+from topicforge.tools.handlers import register_tools
+
+__all__ = ["register_tools"]

topicforge/tools/handlers.py

@@ -0,0 +1,146 @@
+"""MCP tool handlers.
+
+Handlers are deliberately thin: they delegate to services and let FastMCP
+serialize the returned Pydantic models. They never touch ROS2 directly.
+
+`AdapterError` (and any other unexpected exception) is allowed to bubble up.
+FastMCP translates it into an MCP-native error response (`isError: true`
+in the JSON-RPC payload), which every compliant MCP client knows how to
+handle. We deliberately do **not** wrap errors in a custom envelope: that
+pattern masks failures as successful tool results and forces the client to
+parse the body to discover something went wrong.
+
+Future tools (URDF inspection, bag anomaly detection, dataset export) plug
+in here behind the same shape:
+
+    @mcp.tool(description="...")
+    def my_tool(...) -> MyResult:
+        return service.do_thing(...)
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import Field
+
+from topicforge.models import (
+    BagAnalysis,
+    HealthReport,
+    SampleResult,
+    TopicInfo,
+)
+from topicforge.services import HealthService, Inspector
+
+_TOPIC_PARAM_DESC = (
+    "Fully qualified ROS2 topic name starting with `/`, e.g. `/cmd_vel` or "
+    "`/camera/image_raw`. Each `/`-separated segment must start with a "
+    "letter or underscore and contain only letters, digits, and "
+    "underscores; everything else (whitespace, quotes, shell "
+    "metacharacters, `//`, trailing `/`) is rejected before reaching the "
+    "`ros2` CLI."
+)
+
+_COUNT_PARAM_DESC = (
+    "Maximum number of recent messages to return. Defaults to 5; silently "
+    "clamped to 50 (the hard cap that keeps tool output bounded — read it "
+    "from `health_check.max_sample_count`). Negative values raise an error. "
+    "The returned `SampleResult.count` reflects the actual number of "
+    "samples produced — it can be lower than the request (empty topic, "
+    "timeout, mock fixture shorter than requested)."
+)
+
+_PATH_PARAM_DESC = (
+    "Path to a ROS2 bag: a file ending in `.mcap`, `.db3`, or `.bag`, or a "
+    "`rosbag2_*` directory. Leading/trailing whitespace is stripped. Null "
+    "bytes and otherwise malformed filesystem paths are rejected. Existence "
+    "and bag format are validated by the live adapter (mock mode accepts "
+    "any well-formed path)."
+)
+
+
+def register_tools(
+    mcp: FastMCP,
+    inspector: Inspector,
+    health: HealthService,
+) -> None:
+    """Register the MVP tool set on `mcp`."""
+
+    @mcp.tool(
+        description=(
+            "Report TopicForge's effective runtime mode, whether ROS2 tooling is "
+            "available, the server version, and the server-side sample cap. "
+            "Always succeeds — call this first when something looks wrong."
+        )
+    )
+    def health_check() -> HealthReport:
+        return health.report()
+
+    @mcp.tool(
+        description=(
+            "List all ROS2 topics known to the current graph (or the mock graph "
+            "if running in mock mode). Returns name, message type, and "
+            "publisher/subscriber counts for each topic."
+        )
+    )
+    def list_topics() -> list[TopicInfo]:
+        return inspector.list_topics()
+
+    @mcp.tool(
+        description=(
+            "Return detailed info for a single ROS2 topic. `topic` must be a "
+            "fully qualified topic name, e.g. `/cmd_vel`. Raises an MCP error "
+            "if the topic name is malformed or the topic is unknown."
+        )
+    )
+    def get_topic_info(
+        topic: Annotated[str, Field(description=_TOPIC_PARAM_DESC)],
+    ) -> TopicInfo:
+        return inspector.get_topic_info(topic)
+
+    @mcp.tool(
+        description=(
+            "Return up to `count` recent messages from `topic`. `topic` must be "
+            "a fully qualified ROS2 name; see the `topic` parameter description "
+            "for the exact accepted shape. `count` defaults to 5 and is silently "
+            "clamped to 50 — request more and you receive at most 50 without "
+            "warning. Returns a `SampleResult` envelope `{topic, count, samples}` "
+            "where `count` is the actual number of samples returned (may be 0). "
+            "In live mode the MVP shells out to `ros2 topic echo --once` with a "
+            "short timeout, so the result is empty when no publisher is "
+            "currently active, and every `samples[i].timestamp_ns` is 0 (the "
+            "CLI does not expose receive times). The live parser only extracts "
+            "top-level YAML keys into `samples[i].payload`; nested fields and "
+            "the verbatim CLI output land under the reserved `_raw_text` key, "
+            "so a client can reason over the raw bytes when it needs more than "
+            "the flat view. In mock mode returns deterministic samples with "
+            "monotonically increasing timestamps for the fictional demo robot "
+            "(and no `_raw_text` key, since the payload is already structured)."
+        )
+    )
+    def sample_messages(
+        topic: Annotated[str, Field(description=_TOPIC_PARAM_DESC)],
+        count: Annotated[int, Field(description=_COUNT_PARAM_DESC, ge=0)] = 5,
+    ) -> SampleResult:
+        samples = inspector.sample_messages(topic, count)
+        return SampleResult(topic=topic, count=len(samples), samples=samples)
+
+    @mcp.tool(
+        description=(
+            "Inspect a ROS2 bag at `path` and return a structured summary: "
+            "duration, message count, per-topic stats, and any detected "
+            "anomalies. Supports `.mcap`, `.db3`, and `.bag` paths via "
+            "`ros2 bag info` in live mode. Returns rich fixture data in mock "
+            "mode."
+        )
+    )
+    def analyze_bag(
+        path: Annotated[str, Field(description=_PATH_PARAM_DESC, min_length=1)],
+    ) -> BagAnalysis:
+        return inspector.analyze_bag(path)
+
+    # TODO(roadmap): URDF tools — validate / inspect / generate URDF & xacro.
+    # TODO(roadmap): bag anomaly detection — clock jumps, frame drops, TF gaps.
+    # TODO(roadmap): dataset export — rosbag → COCO / Hugging Face Datasets.
+    # TODO(roadmap): synthetic data pipeline — Blender / Gazebo / Isaac control.