topicforge 0.5.6__tar.gz → 0.6.0__tar.gz

{topicforge-0.5.6 → topicforge-0.6.0}/CHANGELOG.md

@@ -5,6 +5,67 @@ All notable changes to TopicForge are documented in this file.
 The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-10-05
+
+`sample_messages` (live) rewritten after the OmniSim team's report (count
+ignored, empty results on latched topics, wrong timestamps and shifted columns
+on simulated time).
+
+### Breaking
+
+- `sample_messages` payloads are nested named fields (`payload.header.stamp.sec`,
+  `payload.ranges`) instead of positional `col_0`, `col_1`, ... columns. The
+  verbatim row under `_raw_text` is gone: it is present only when a message could
+  not be parsed.
+- `_truncated_after_columns` and `_truncated_columns` are replaced by
+  `_truncated_fields`, a list of dotted field paths (`["ranges", "intensities"]`)
+  for arrays, strings or bytes cut at `max_array_length`. A cut array no longer
+  carries the CLI's `'...'` element.
+- `nan`, `inf` and `-inf` floats are returned as the strings `"nan"`, `"inf"`,
+  `"-inf"`.
+- `MiddlewareAdapter.sample_messages` returns a `SampleResult` instead of a list
+  of `MessageSample` and takes `timeout_s`. `parse_csv_echo` and `parse_echo_yaml`
+  are removed.
+- `pyyaml>=6` is a runtime dependency.
+- A failing `ros2 topic echo` (non-zero exit with no message, or a CLI that cannot
+  be started) raises an MCP error instead of returning an empty list. `count` 0 now
+  validates the topic in live mode too, as it already did in the mock.
+
+### Added
+
+- `sample_messages` parameter `timeout_s` (1..45, default 10): a wall deadline for
+  the whole call, topic lookup included. The call returns within about `timeout_s`
+  plus 2 s (stopping the CLI, decoding what arrived).
+- `MessageSample.stamp_source` (`header` or `none`) and `received_ns` (wall clock
+  when TopicForge read the message).
+- A short result carries a `note` (`N of M messages within T s`) that tells "no
+  publisher is announced" from "a publisher exists but nothing arrived in time",
+  hints `count` 1 for a latched topic, and gives the exit code and stderr when the
+  CLI exited early.
+- A message over the per-message size cap (`TOPICFORGE_MAX_SAMPLE_BYTES`, 1 MiB) is
+  dropped while it streams and counted in the `note`, so a large `Image` no longer
+  costs tens of seconds of YAML decoding. Decoding uses libyaml when available and
+  stops at the call deadline.
+- `count` above 50 is capped with a note, and the tool schema declares the
+  maximum.
+
+### Fixed
+
+- `sample_messages` honours `count`: it streams `ros2 topic echo` and stops at
+  `count` messages or the deadline, then stops the process tree (SIGINT then
+  SIGKILL on POSIX, `taskkill /F /T` on Windows) (OmniSim D3). The echo is
+  started with explicit `--qos-reliability` and `--qos-durability` taken from the
+  publishers, so a latched (`transient_local`) topic is no longer returned empty
+  because the CLI picked its QoS against a cold daemon.
+- Stopping the CLI kills the whole process tree even when the launcher already
+  exited (POSIX: always signals the process group; Windows: a Job Object), so no
+  orphan `ros2` process keeps running. The CLI is started with UTF-8 output.
+- The mock `sample_messages` matches the live shape: headerless messages have
+  `timestamp_ns` 0 and `stamp_source` `none`.
+- `timestamp_ns` is the top-level `header.stamp` whatever its value, so a
+  simulated clock (seconds since the simulation start) no longer falls back to 0
+  and shifts every following column by two (OmniSim D4).
+
 ## [0.5.6] - 2026-10-02
 
 Fixes from a live run of 0.5.3 and 0.5.5 against OmniSim's simulated
@@ -1202,7 +1263,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.6...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/yaniswav/TopicForge/compare/v0.5.6...v0.6.0
 [0.5.6]: https://github.com/yaniswav/TopicForge/compare/v0.5.5...v0.5.6
 [0.5.5]: https://github.com/yaniswav/TopicForge/compare/v0.5.4...v0.5.5
 [0.5.4]: https://github.com/yaniswav/TopicForge/compare/v0.5.3...v0.5.4

{topicforge-0.5.6 → topicforge-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topicforge
-Version: 0.5.6
+Version: 0.6.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
@@ -42,6 +42,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: mcp<2,>=1.0.0
 Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6
 Provides-Extra: all
 Requires-Dist: cyclonedds>=0.10; extra == 'all'
 Provides-Extra: bags
@@ -108,8 +109,8 @@ Every response except `health_check` carries `mode_effective` (`"live"` or `"moc
 | `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` recording or `rosbag2_*` directory (via `ros2 bag info`)      |
+| `sample_messages`       | Peek recent messages on a ROS2 topic (count capped at 50)                                        |
+| `analyze_bag`           | Summarize a `.mcap` / `.db3` recording or `rosbag2_*` directory (via `ros2 bag info`)            |
 | `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   |
@@ -159,12 +160,12 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 
 - 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 returns count 0 and a note that the topic is announced on the bus; no traffic is read. `topic_metrics` therefore has data only for the builtin discovery topics and says so in its `status`. It is a discovery-layer probe, not a publish-rate monitor.
-- Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned for 0.5.6. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
+- Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
 - 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`.
 - Single domain: the server observes the domain it joined at startup; changing it needs a restart.
 - DDS Security is not handled. A participant without credentials sees an empty secure bus. `detect_qos_mismatches` checks Partition, type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership (kind), DestinationOrder and DataRepresentation (History as a risk); Presentation, XTypes assignability and runtime behavior are not checked, and the result lists them in `policies_unchecked`. It returns a `MismatchScan` envelope: read `reports` for the mismatches.
 - Fast DDS serves no `list_endpoints`.
-- `sample_messages` (live) runs `ros2 topic echo --csv --once` with a short timeout, so it returns at most one message, and 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. Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_after_columns`.
+- `sample_messages` (live) streams `ros2 topic echo` until `count` messages arrive or `timeout_s` (1..45, default 10, for the whole call) runs out, and returns what arrived with a `note` (`N of M messages within T s`, saying whether a publisher exists). QoS is matched to the publishers, so latched topics work. The payload has nested named fields (`payload.header.stamp.sec`); `timestamp_ns` is `header.stamp` (the publisher's clock, sim time on a simulation) or 0 for headerless types, with `stamp_source` and `received_ns` (wall clock when the CLI printed it). Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_fields`. `nan` and `inf` come back as strings. `count` above 50 is capped with a note.
 - `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. 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.
@@ -188,7 +189,7 @@ When on, each tool call emits one event with exactly six fields:
 | `tool_name`  | `"list_topics"` | One of the twelve 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.6"`       | TopicForge server version                                   |
+| `version`    | `"0.6.0"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

{topicforge-0.5.6 → topicforge-0.6.0}/README.md

@@ -49,8 +49,8 @@ Every response except `health_check` carries `mode_effective` (`"live"` or `"moc
 | `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` recording or `rosbag2_*` directory (via `ros2 bag info`)      |
+| `sample_messages`       | Peek recent messages on a ROS2 topic (count capped at 50)                                        |
+| `analyze_bag`           | Summarize a `.mcap` / `.db3` recording or `rosbag2_*` directory (via `ros2 bag info`)            |
 | `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   |
@@ -100,12 +100,12 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 
 - 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 returns count 0 and a note that the topic is announced on the bus; no traffic is read. `topic_metrics` therefore has data only for the builtin discovery topics and says so in its `status`. It is a discovery-layer probe, not a publish-rate monitor.
-- Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned for 0.5.6. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
+- Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
 - 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`.
 - Single domain: the server observes the domain it joined at startup; changing it needs a restart.
 - DDS Security is not handled. A participant without credentials sees an empty secure bus. `detect_qos_mismatches` checks Partition, type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership (kind), DestinationOrder and DataRepresentation (History as a risk); Presentation, XTypes assignability and runtime behavior are not checked, and the result lists them in `policies_unchecked`. It returns a `MismatchScan` envelope: read `reports` for the mismatches.
 - Fast DDS serves no `list_endpoints`.
-- `sample_messages` (live) runs `ros2 topic echo --csv --once` with a short timeout, so it returns at most one message, and 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. Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_after_columns`.
+- `sample_messages` (live) streams `ros2 topic echo` until `count` messages arrive or `timeout_s` (1..45, default 10, for the whole call) runs out, and returns what arrived with a `note` (`N of M messages within T s`, saying whether a publisher exists). QoS is matched to the publishers, so latched topics work. The payload has nested named fields (`payload.header.stamp.sec`); `timestamp_ns` is `header.stamp` (the publisher's clock, sim time on a simulation) or 0 for headerless types, with `stamp_source` and `received_ns` (wall clock when the CLI printed it). Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_fields`. `nan` and `inf` come back as strings. `count` above 50 is capped with a note.
 - `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. 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.
@@ -129,7 +129,7 @@ When on, each tool call emits one event with exactly six fields:
 | `tool_name`  | `"list_topics"` | One of the twelve 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.6"`       | TopicForge server version                                   |
+| `version`    | `"0.6.0"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

{topicforge-0.5.6 → topicforge-0.6.0}/docs/TESTING.md

@@ -15,7 +15,7 @@ How to get a working ROS2 environment to point TopicForge at, and how to wire it
 ```bash
 python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
 pip install topicforge
-python -m topicforge --version                      # -> topicforge 0.5.6
+python -m topicforge --version                      # -> topicforge 0.6.0
 TOPICFORGE_MODE=mock python -m topicforge           # blocks on stdio; MCP clients spawn it
 ```
 
@@ -41,7 +41,7 @@ python3 -m venv ~/topicforge-venv && source ~/topicforge-venv/bin/activate
 pip install topicforge          # Ubuntu 22.04 ships Python 3.10, which is enough
 ```
 
-Then run live mode with three terminals. In the first, `ros2 run demo_nodes_cpp talker` publishes `/chatter` at about 1 Hz. In the second, `ros2 topic list` should show `/chatter`. In the third, source ROS2, activate the venv and run `TOPICFORGE_MODE=live python -m topicforge`. The startup line reads `topicforge 0.5.6 ready (mode=live, requested_mode=live, adapter=ros2_cli, telemetry=off)`; `mode=mock` means `ros2` was not found and the server fell back to fixtures.
+Then run live mode with three terminals. In the first, `ros2 run demo_nodes_cpp talker` publishes `/chatter` at about 1 Hz. In the second, `ros2 topic list` should show `/chatter`. In the third, source ROS2, activate the venv and run `TOPICFORGE_MODE=live python -m topicforge`. The startup line reads `topicforge 0.6.0 ready (mode=live, requested_mode=live, adapter=ros2_cli, telemetry=off)`; `mode=mock` means `ros2` was not found and the server fell back to fixtures.
 
 ## Linux native
 
@@ -77,7 +77,7 @@ TopicForge resolves the `ros2` launcher with `shutil.which` (normally `ros2.exe`
 
 Discover the graph. Ask "What topics are currently being published, and what message types do they carry?" TopicForge calls `list_topics`. Live mode shows `/chatter` plus `/rosout` and `/parameter_events`; mock mode shows `/cmd_vel`, `/odom`, `/scan`, `/tf` and `/camera/image_raw`.
 
-Inspect and sample. Ask "Show me the latest message on /chatter." TopicForge calls `get_topic_info` then `sample_messages`. The payload exposes fields as positional CSV columns (`col_0`, `col_1`, ...) plus `_raw_text`, the verbatim row from `ros2 topic echo --csv --once`. `timestamp_ns` is `0` for headerless types such as `std_msgs/String`.
+Inspect and sample. Ask "Show me the latest message on /chatter." TopicForge calls `get_topic_info` then `sample_messages`. The payload has the message fields as nested named values. `timestamp_ns` is the `header.stamp` and `0` for headerless types such as `std_msgs/String` (`stamp_source` says which).
 
 Record and analyze a bag.
 

{topicforge-0.5.6 → topicforge-0.6.0}/docs/TROUBLESHOOTING.md

@@ -63,12 +63,12 @@ The adapter was written against the 2.6.x binding and has never run against a bu
 - `lookback_seconds must be in 1..86400` (`participant_events`): default 300. The lifecycle buffer keeps at most 200 events, newest first, regardless of window.
 - `window_seconds must be in 1..3600` (`topic_metrics`): default 60. The buffer holds 1000 samples per topic, drop-oldest, so frequency is computed from buffered samples, not a true rolling window.
 - `DDS topic name is malformed`: DDS names match `^[A-Za-z_/][A-Za-z0-9_/:]*$` (builtin names like `DCPSParticipant` and `::` separators are allowed; whitespace and dashes are not). ROS2 names start with `/` and use `_`, so `my-topic` becomes `/my_topic`.
-- `sample_messages` and `peek_*` silently clamp `count` to 50; the `count` field of the result is what was actually returned.
+- `sample_messages` caps `count` at 50 and says so in `note`; `peek_*` clamp silently. The `count` field of the result is what was actually returned.
 
 ## Other
 
 - `topicforge: command not found`: the entry point is not on PATH. Re-activate the venv, or use `python -m topicforge`.
-- `sample_messages` returns no samples: live mode runs `ros2 topic echo --once` with a 3 second timeout; a topic with no active publisher returns nothing. Check `ros2 topic info -v <topic>`.
+- `sample_messages` returns fewer samples than asked: live mode waits `timeout_s` seconds (default 10, max 60, counted from the start of the `ros2` CLI, which can take a few seconds on a slow machine) and `note` says `N of M messages` and whether a publisher exists. Raise `timeout_s` for a topic slower than 1 Hz; check `ros2 topic info -v <topic>`.
 - `analyze_bag` says the path does not exist: the path is resolved in the shell where TopicForge runs. Under WSL use `/mnt/c/demos/run.mcap`, not `C:\demos\run.mcap`. In mock mode only `.mcap`, `.db3`, `.bag` or extensionless paths are accepted.
 - Claude Desktop shows no tools: check Help -> View Logs -> MCP, confirm `topicforge --version` runs from the same environment (or use the absolute path of the binary in the config), and validate the config with `python -m json.tool claude_desktop_config.json`, since a JSON error silently drops the whole file.
 - First live call is slow: `ros2 topic list -t` initializes the DDS middleware, a 1-2 second warm-up.

{topicforge-0.5.6 → topicforge-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "topicforge"
-version = "0.5.6"
+version = "0.6.0"
 description = "ROS Topic Inspector & Bag Analyzer MCP server for AI agents"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -25,6 +25,7 @@ classifiers = [
 dependencies = [
     "mcp>=1.0.0,<2",
     "pydantic>=2.6",
+    "pyyaml>=6",
 ]
 
 [project.optional-dependencies]

{topicforge-0.5.6 → topicforge-0.6.0}/src/topicforge/__init__.py

@@ -1,5 +1,5 @@
 """TopicForge: ROS Topic Inspector & Bag Analyzer MCP server."""
 
-__version__ = "0.5.6"
+__version__ = "0.6.0"
 
 __all__ = ["__version__"]

{topicforge-0.5.6 → topicforge-0.6.0}/src/topicforge/adapters/base.py

@@ -9,11 +9,10 @@ from __future__ import annotations
 
 from typing import Literal, Protocol, runtime_checkable
 
-from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH
+from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH, DEFAULT_SAMPLE_TIMEOUT_S
 from topicforge.models import (
     BagAnalysis,
     EndpointListing,
-    MessageSample,
     MismatchScan,
     ParticipantEvent,
     ParticipantInfo,
@@ -96,7 +95,8 @@ class MiddlewareAdapter(Protocol):
         *,
         max_array_length: int | None = DEFAULT_MAX_ARRAY_LENGTH,
         arrays_summary_only: bool = False,
-    ) -> list[MessageSample]: ...
+        timeout_s: float = DEFAULT_SAMPLE_TIMEOUT_S,
+    ) -> SampleResult: ...
 
     def analyze_bag(self, path: str) -> BagAnalysis: ...
 

{topicforge-0.5.6 → topicforge-0.6.0}/src/topicforge/adapters/composite.py

@@ -15,11 +15,10 @@ from __future__ import annotations
 from typing import Any
 
 from topicforge.adapters.base import AdapterName, EffectiveMode, MiddlewareAdapter
-from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH
+from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH, DEFAULT_SAMPLE_TIMEOUT_S
 from topicforge.models import (
     BagAnalysis,
     EndpointListing,
-    MessageSample,
     MismatchScan,
     ParticipantEvent,
     ParticipantInfo,
@@ -69,12 +68,14 @@ class CompositeAdapter:
         *,
         max_array_length: int | None = DEFAULT_MAX_ARRAY_LENGTH,
         arrays_summary_only: bool = False,
-    ) -> list[MessageSample]:
+        timeout_s: float = DEFAULT_SAMPLE_TIMEOUT_S,
+    ) -> SampleResult:
         return self._ros.sample_messages(
             topic,
             count,
             max_array_length=max_array_length,
             arrays_summary_only=arrays_summary_only,
+            timeout_s=timeout_s,
         )
 
     def analyze_bag(self, path: str) -> BagAnalysis:

{topicforge-0.5.6 → topicforge-0.6.0}/src/topicforge/adapters/dds_cyclone/adapter.py

@@ -63,7 +63,7 @@ from topicforge.adapters.common import (
 from topicforge.adapters.common import (
     cyclone_extract_topic_name as _extract_topic_name,
 )
-from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH
+from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH, DEFAULT_SAMPLE_TIMEOUT_S
 from topicforge.models import (
     BagAnalysis,
     EndpointListing,
@@ -334,7 +334,8 @@ class CycloneDdsAdapter:
         *,
         max_array_length: int | None = DEFAULT_MAX_ARRAY_LENGTH,
         arrays_summary_only: bool = False,
-    ) -> list[MessageSample]:
+        timeout_s: float = DEFAULT_SAMPLE_TIMEOUT_S,
+    ) -> SampleResult:
         raise AdapterError(DDS_ONLY_ERROR_MSG)
 
     def analyze_bag(self, path: str) -> BagAnalysis:

{topicforge-0.5.6 → topicforge-0.6.0}/src/topicforge/adapters/dds_dust/adapter.py

@@ -12,11 +12,10 @@ import logging
 
 from topicforge.adapters.base import AdapterError, AdapterName, EffectiveMode
 from topicforge.adapters.common import validate_domain_id
-from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH
+from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH, DEFAULT_SAMPLE_TIMEOUT_S
 from topicforge.models import (
     BagAnalysis,
     EndpointListing,
-    MessageSample,
     MismatchScan,
     ParticipantEvent,
     ParticipantInfo,
@@ -66,7 +65,8 @@ class DustDdsAdapter:
         *,
         max_array_length: int | None = DEFAULT_MAX_ARRAY_LENGTH,
         arrays_summary_only: bool = False,
-    ) -> list[MessageSample]:
+        timeout_s: float = DEFAULT_SAMPLE_TIMEOUT_S,
+    ) -> SampleResult:
         raise AdapterError(_DUST_ROADMAP_MSG)
 
     def analyze_bag(self, path: str) -> BagAnalysis:

{topicforge-0.5.6 → topicforge-0.6.0}/src/topicforge/adapters/dds_fast/adapter.py

@@ -52,7 +52,7 @@ from topicforge.adapters.common import (
 from topicforge.adapters.common import (
     is_removal as _is_removal,
 )
-from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH
+from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH, DEFAULT_SAMPLE_TIMEOUT_S
 from topicforge.models import (
     BagAnalysis,
     EndpointListing,
@@ -241,7 +241,8 @@ class FastDdsAdapter:
         *,
         max_array_length: int | None = DEFAULT_MAX_ARRAY_LENGTH,
         arrays_summary_only: bool = False,
-    ) -> list[MessageSample]:
+        timeout_s: float = DEFAULT_SAMPLE_TIMEOUT_S,
+    ) -> SampleResult:
         raise AdapterError(DDS_ONLY_ERROR_MSG)
 
     def analyze_bag(self, path: str) -> BagAnalysis:

{topicforge-0.5.6 → topicforge-0.6.0}/src/topicforge/adapters/dds_opendds/adapter.py

@@ -16,11 +16,10 @@ import logging
 
 from topicforge.adapters.base import AdapterError, AdapterName, EffectiveMode
 from topicforge.adapters.common import validate_domain_id
-from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH
+from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH, DEFAULT_SAMPLE_TIMEOUT_S
 from topicforge.models import (
     BagAnalysis,
     EndpointListing,
-    MessageSample,
     MismatchScan,
     ParticipantEvent,
     ParticipantInfo,
@@ -72,7 +71,8 @@ class OpenDdsAdapter:
         *,
         max_array_length: int | None = DEFAULT_MAX_ARRAY_LENGTH,
         arrays_summary_only: bool = False,
-    ) -> list[MessageSample]:
+        timeout_s: float = DEFAULT_SAMPLE_TIMEOUT_S,
+    ) -> SampleResult:
         raise AdapterError(_OPENDDS_ROADMAP_MSG)
 
     def analyze_bag(self, path: str) -> BagAnalysis: