topicgate 1.2.2__tar.gz → 1.3.0__tar.gz

{topicgate-1.2.2/src/topicgate.egg-info → topicgate-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topicgate
-Version: 1.2.2
+Version: 1.3.0
 Summary: Secure local access to your MQTT topics
 License-Expression: MIT
 Project-URL: Repository, https://github.com/Dumdart/TopicGate
@@ -49,7 +49,6 @@ Dynamic: license-file
   <a href="#get-started">Get started</a> ·
   <a href="#connect-an-agent">Connect an agent</a> ·
   <a href="#how-observations-work">Understand observations</a> ·
-  <a href="docs/desktop-workflow.md">Desktop workflow</a>
 </p>
 
 <p align="center">
@@ -60,6 +59,12 @@ TopicGate gives you a local, intentional view of MQTT data. Configure broker pro
 
 It is built for a practical boundary: broker credentials stay on your machine, observed state is persisted locally, and the MCP server starts in **read-only mode**. MQTT control—connecting, changing subscriptions, refreshing observations, or publishing—requires an explicit opt-in.
 
+## Demo
+
+See TopicGate connect to an MQTT broker, inspect live topic state, answer an agent query with provenance, and enforce the boundary between observation and authorized control.
+
+[Watch the TopicGate demo →](https://www.youtube.com/watch?v=_Qtc01kABkg)
+
 ## What it does
 
 | Desktop | MCP server |

{topicgate-1.2.2 → topicgate-1.3.0}/README.md

@@ -11,7 +11,6 @@
   <a href="#get-started">Get started</a> ·
   <a href="#connect-an-agent">Connect an agent</a> ·
   <a href="#how-observations-work">Understand observations</a> ·
-  <a href="docs/desktop-workflow.md">Desktop workflow</a>
 </p>
 
 <p align="center">
@@ -22,6 +21,12 @@ TopicGate gives you a local, intentional view of MQTT data. Configure broker pro
 
 It is built for a practical boundary: broker credentials stay on your machine, observed state is persisted locally, and the MCP server starts in **read-only mode**. MQTT control—connecting, changing subscriptions, refreshing observations, or publishing—requires an explicit opt-in.
 
+## Demo
+
+See TopicGate connect to an MQTT broker, inspect live topic state, answer an agent query with provenance, and enforce the boundary between observation and authorized control.
+
+[Watch the TopicGate demo →](https://www.youtube.com/watch?v=_Qtc01kABkg)
+
 ## What it does
 
 | Desktop | MCP server |

{topicgate-1.2.2 → topicgate-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "topicgate"
-version = "1.2.2"
+version = "1.3.0"
 description = "Secure local access to your MQTT topics"
 readme = "README.md"
 license = "MIT"
@@ -62,7 +62,6 @@ test = [
 testpaths = ["tests"]
 pythonpath = ["."]
 cache_dir = ".pytest_cache"
-addopts = "--basetemp=.pytest-tmp"
 asyncio_mode = "auto"
 
 [project.scripts]

{topicgate-1.2.2 → topicgate-1.3.0}/src/topicgate/app/app_dependencies.py

@@ -1,6 +1,5 @@
 from pathlib import Path
-from uuid import UUID
-
+from topicgate.app.services.observation_query_service import ObservationQueryService
 from topicgate.app.services.service_item import ServiceItem
 from topicgate.app.services.persistence_lifecycle import PersistenceLifecycle
 from topicgate.app.services.broker_profile_service import BrokerProfileService
@@ -9,14 +8,13 @@ from topicgate.app.services.observation_retention_policy_service import (
     ObservationRetentionPolicyService,
 )
 from topicgate.app.services.broker_snapshot_service import BrokerSnapshotService
+from topicgate.app.services.broker_resolver import BrokerResolver
 from topicgate.app.services.control_operation_service import ControlOperationService
 from topicgate.app.services.mcp_setup_service import McpSetupService
 from topicgate.app.broker_runtime_state import BrokerRuntimeState
 from topicgate.app.topicgate_runtime import TopicGateRuntime
 from topicgate.core.interfaces.observer_repository import ObserverRepository
 from topicgate.core.models.broker_profile import BrokerProfile
-from topicgate.core.models.mqtt_observation import MqttObservation
-from topicgate.core.models.topic_message import TopicMessage
 from topicgate.infrastructure.database.database_context import DatabaseContext
 from topicgate.infrastructure.credentials.credential_store import CredentialStore
 from topicgate.infrastructure.credentials.os_credential_store import OSCredentialStore
@@ -64,7 +62,9 @@ class AppDependencies:
         self.observation_cache = ObservationCacheService(
             self.topic_messages,
             self.retention_policy,
+            administrator=self.topic_messages,
         )
+        self.observation_query = ObservationQueryService(self.topic_messages)
         self.control_operations = ControlOperationService(
             self._db_context,
             control_owner,
@@ -90,13 +90,19 @@ class AppDependencies:
 
         self.runtime = TopicGateRuntime(
             self.broker_profiles,
-             self.broker_runtime_state.repositories,
+            self.broker_runtime_state.repositories,
             profile.id,
-            self._create_observer_repository,
-            self.observation_cache,
-            self.control_operations,
+            mqtt_repository_factory=self._create_observer_repository,
+            observation_cache=self.observation_cache,
+            observation_query=self.observation_query,
+            current_topics=self.topic_messages,
+            control_operations=self.control_operations,
+        )
+        self.broker_resolver = BrokerResolver(self.runtime)
+        self.snapshot_service = BrokerSnapshotService(
+            self.runtime,
+            resolver=self.broker_resolver,
         )
-        self.snapshot_service = BrokerSnapshotService(self.runtime)
         self.mcp_setup = McpSetupService(
             self.runtime,
             self.snapshot_service,
@@ -118,31 +124,8 @@ class AppDependencies:
         return ObserverMqttRepository(
             profile.config,
             list(profile.workspace.subscriptions),
-            profile.workspace.model,
             retention_policy=self.retention_policy.get,
-            observation_sink=lambda observation: self._persist_observation(
-                profile.id,
-                observation,
-            ),
-        )
-
-    def _persist_observation(
-        self,
-        broker_id: UUID,
-        observation: MqttObservation,
-    ) -> None:
-        if observation.observation_id is None:
-            raise ValueError("A live observation requires an observation ID.")
-        self.topic_messages.update_message(
-            TopicMessage(
-                broker_id=broker_id,
-                topic=observation.topic,
-                payload=observation.payload,
-                qos=observation.qos,
-                retain=observation.retain,
-                received_at=observation.received_at,
-                payload_size=observation.payload_size or len(observation.payload),
-                message_count=observation.message_count,
-                observation_id=observation.observation_id,
-            )
+            broker_id=profile.id,
+            message_recorder=self.topic_messages,
+            current_topics=self.topic_messages,
         )

{topicgate-1.2.2 → topicgate-1.3.0}/src/topicgate/app/broker_runtime_state.py

@@ -1,27 +1,18 @@
 from uuid import UUID
 
 from topicgate.core.interfaces.observer_repository import ObserverRepository
-from topicgate.core.models.observer_model import ObserverModel
 from topicgate.core.models.broker_profile import BrokerProfile
 
 
 class BrokerRuntimeState:
-    """In-memory observer models and repositories, keyed by broker identity."""
+    """In-memory repositories and profile metadata, keyed by broker identity."""
 
     def __init__(self) -> None:
-        self._models: dict[UUID, ObserverModel] = {}
         self._repositories: dict[UUID, ObserverRepository] = {}
         self._profile_handles: dict[UUID, BrokerProfile] = {}
         self._config_ids: dict[UUID, int | None] = {}
 
-    def get_model(self, broker_id: UUID) -> ObserverModel | None:
-        return self._models.get(broker_id)
-
-    def set_model(self, broker_id: UUID, model: ObserverModel) -> None:
-        self._models[broker_id] = model
-
     def remove(self, broker_id: UUID) -> None:
-        self._models.pop(broker_id, None)
         self._repositories.pop(broker_id, None)
         self._profile_handles.pop(broker_id, None)
         self._config_ids.pop(broker_id, None)

topicgate-1.3.0/src/topicgate/app/models/broker_inspection.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+
+from topicgate.app.models.broker_snapshot import BrokerSnapshot
+from topicgate.core.models.broker_summary import BrokerSummary
+from topicgate.core.models.observation_cache_administration import BrokerCacheUsage
+from topicgate.core.models.subscription import Subscription
+
+
+@dataclass(frozen=True)
+class BrokerConnectionState:
+    status: str
+    dropped_message_count: int
+    topic_update_interval: float
+
+
+@dataclass(frozen=True)
+class BrokerInspection:
+    identity: BrokerSummary
+    connection: BrokerConnectionState
+    subscriptions: tuple[Subscription, ...]
+    cache: BrokerCacheUsage
+    snapshot: BrokerSnapshot | None

topicgate-1.3.0/src/topicgate/app/services/broker_inspection_service.py

@@ -0,0 +1,67 @@
+from uuid import UUID
+
+from topicgate.app.models.broker_inspection import (
+    BrokerConnectionState,
+    BrokerInspection,
+)
+from topicgate.app.services.broker_resolver import BrokerResolver
+from topicgate.app.services.broker_snapshot_service import (
+    DEFAULT_SNAPSHOT_RESULT_LIMIT,
+    BrokerSnapshotService,
+)
+from topicgate.app.topicgate_runtime import TopicGateRuntime
+from topicgate.core.models.observation_cache_administration import BrokerCacheUsage
+from topicgate.core.payload_limits import MAX_RENDERED_PAYLOAD_BYTES
+
+
+class BrokerInspectionService:
+    """Compose passive broker reads into one presentation-neutral response."""
+
+    def __init__(
+        self,
+        runtime: TopicGateRuntime,
+        snapshot_service: BrokerSnapshotService,
+        resolver: BrokerResolver,
+    ) -> None:
+        self._runtime = runtime
+        self._snapshot_service = snapshot_service
+        self._resolver = resolver
+
+    def inspect(
+        self,
+        broker: UUID | str,
+        *,
+        include_snapshot: bool = False,
+        snapshot_limit: int = DEFAULT_SNAPSHOT_RESULT_LIMIT,
+        payload_limit_bytes: int = MAX_RENDERED_PAYLOAD_BYTES,
+    ) -> BrokerInspection:
+        resolved = self._resolver.resolve(broker)
+        cache_summary = self._runtime.get_observation_storage_summary(resolved.id)
+        cache = next(
+            iter(cache_summary.brokers),
+            BrokerCacheUsage(resolved.id, 0, 0, None, None),
+        )
+        snapshot = (
+            self._snapshot_service.build_current(
+                resolved.id,
+                result_limit=snapshot_limit,
+                payload_limit_bytes=payload_limit_bytes,
+            )
+            if include_snapshot
+            else None
+        )
+        return BrokerInspection(
+            identity=resolved,
+            connection=BrokerConnectionState(
+                status=str(self._runtime.get_connection_status(resolved.id)),
+                dropped_message_count=self._runtime.get_dropped_message_count(
+                    resolved.id
+                ),
+                topic_update_interval=self._runtime.get_topic_update_interval(
+                    resolved.id
+                ),
+            ),
+            subscriptions=self._runtime.list_subscriptions(resolved.id),
+            cache=cache,
+            snapshot=snapshot,
+        )

{topicgate-1.2.2 → topicgate-1.3.0}/src/topicgate/app/services/broker_profile_service.py

@@ -5,12 +5,7 @@ from topicgate.app.broker_runtime_state import BrokerRuntimeState
 from topicgate.core.config.app_config import AppConfig
 from topicgate.core.config.mqtt_config import MqttConfig
 from topicgate.core.models.broker_profile import BrokerProfile
-from topicgate.core.models.observer_model import ObserverModel
-from topicgate.core.models.mqtt_observation import (
-    MqttObservation,
-    ObservationSource,
-)
-from topicgate.core.interfaces.topic_message_store import TopicMessageStore
+from topicgate.core.interfaces.topic_message_recorder import TopicMessageRecorder
 from topicgate.core.models.observer_workspace import ObserverWorkspace
 from topicgate.infrastructure.credentials.credential_store import CredentialStore
 from topicgate.infrastructure.database.database_context import DatabaseContext
@@ -21,7 +16,6 @@ from topicgate.infrastructure.repository.broker_repository import BrokerReposito
 from topicgate.infrastructure.repository.subscription_repository import (
     SubscriptionRepository,
 )
-from topicgate.processors.observer_model_processor import ObserverModelProcessor
 
 
 class BrokerProfileService:
@@ -34,7 +28,7 @@ class BrokerProfileService:
         *,
         credential_store: CredentialStore,
         runtime_state: BrokerRuntimeState | None = None,
-        topic_messages: TopicMessageStore | None = None,
+        topic_messages: TopicMessageRecorder | None = None,
     ) -> None:
         if isinstance(settings, DatabaseContext):
             self._db = settings
@@ -49,7 +43,7 @@ class BrokerProfileService:
         self.brokers = BrokerRepository(self._db)
         self.configs = BrokerConfigRepository(self._db)
         self.subscriptions = SubscriptionRepository(self._db)
-        self._topic_messages = topic_messages
+        self._topic_message_recorder = topic_messages
         self._settings_id = supplied_settings.id if supplied_settings else None
 
         identities = self.brokers.list_profiles()
@@ -81,13 +75,9 @@ class BrokerProfileService:
             id=self._runtime_state.get_config_id(identity.id, config.id),
         )
         subscriptions = self.subscriptions.list_for_workspace(identity.workspace_id)
-        model = self._runtime_state.get_model(identity.id)
-        if model is None:
-            model = self._hydrate_observer_model(identity.id, subscriptions)
         workspace = ObserverWorkspace(
             id=identity.workspace_id,
             profile_id=identity.id,
-            model=model,
             subscriptions=subscriptions,
         )
         return BrokerProfile(
@@ -140,6 +130,8 @@ class BrokerProfileService:
             profile_id
         )
         self.brokers.delete_profile(profile_id)
+        if self._topic_message_recorder is not None:
+            self._topic_message_recorder.remove_current_broker(profile_id)
         self._delete_password(profile_id)
         self._runtime_state.remove(profile_id)
         self.save()
@@ -164,13 +156,6 @@ class BrokerProfileService:
     def update_observer_workspace(self, workspace: ObserverWorkspace) -> None:
         self.replace_subscriptions(workspace.id, workspace.subscriptions)
 
-    def update_observer_model(self, model: ObserverModel) -> None:
-        self._runtime_state.set_model(self.brokers.get_profile().id, model)
-        self.save()
-
-    def get_observer_model(self) -> ObserverModel:
-        return self.get_profile().workspace.model
-
     def get_observer_workspace(self) -> ObserverWorkspace:
         return self.get_profile().workspace
 
@@ -209,31 +194,6 @@ class BrokerProfileService:
         self._store_password(identity.id, config.password)
         self._runtime_state.set_config_id(identity.id, config.id)
 
-    def _hydrate_observer_model(self, broker_id: UUID, subscriptions) -> ObserverModel:
-        model = ObserverModelProcessor.add_topics(
-            ObserverModel(root_stats=[]),
-            (item.topic_filter for item in subscriptions),
-        )
-        if self._topic_messages is None:
-            return model
-        for message in self._topic_messages.get_latest_messages(broker_id):
-            node = ObserverModelProcessor.find_or_create_node(model, message.topic)
-            state = MqttObservation(
-                name=node.segment,
-                topic=message.topic,
-                payload=message.payload,
-                qos=message.qos,
-                retain=message.retain,
-                recieved_at=message.received_at,
-                payload_size=message.payload_size,
-                message_count=message.message_count,
-                source=ObservationSource.STORED,
-                observation_id=message.observation_id,
-            )
-            node.state = state
-            model.topic_states[message.topic] = state
-        return model
-
     def _store_password(self, profile_id: UUID, password: str) -> None:
         if password:
             self._credentials.set_password(profile_id, password)

{topicgate-1.2.2 → topicgate-1.3.0}/src/topicgate/app/services/broker_snapshot_service.py

@@ -21,10 +21,14 @@ from topicgate.app.models.broker_snapshot import (
 )
 from topicgate.app.services.broker_resolver import BrokerResolver
 from topicgate.app.topicgate_runtime import TopicGateRuntime
+from topicgate.core.interfaces.current_topic_reader import CurrentTopicReader
 from topicgate.core.models.broker_summary import BrokerSummary
 from topicgate.core.models.connection_status import ConnectionStatus
-from topicgate.core.models.mqtt_observation import MqttObservation, ObservationSource
+from topicgate.core.models.current_topic import CurrentTopic
+from topicgate.core.models.mqtt_observation import ObservationSource
+from topicgate.core.models.observation_status import ObservationStatus
 from topicgate.core.models.subscription import Subscription
+from topicgate.core.models.topic_message import TopicMessage
 from topicgate.core.mqtt_topics import mqtt_filter_matches
 from topicgate.core.observer_limits import MAX_OBSERVED_TOPICS
 from topicgate.core.payload_limits import MAX_RENDERED_PAYLOAD_BYTES
@@ -46,12 +50,14 @@ class BrokerSnapshotService:
         self,
         runtime: TopicGateRuntime,
         *,
+        current_topics: CurrentTopicReader | None = None,
         resolver: BrokerResolver | None = None,
         clock: Clock | None = None,
         monotonic_clock: MonotonicClock | None = None,
         sleep: Sleep | None = None,
     ) -> None:
         self._runtime = runtime
+        self._current_topics = current_topics or runtime
         self._resolver = resolver or BrokerResolver(runtime)
         self._clock = clock or (lambda: datetime.now(timezone.utc))
         self._monotonic_clock = monotonic_clock or time.monotonic
@@ -142,22 +148,24 @@ class BrokerSnapshotService:
         actual_wait_seconds: float,
     ) -> BrokerSnapshot:
         captured_at = self._as_utc(self._clock())
-        model = self._runtime.get_observer_model(resolved.id)
         matching = sorted(
             (
-                state
-                for state in model.topic_states.values()
-                if mqtt_filter_matches(topic_filter, state.topic)
+                current
+                for current in self._current_topics.get_current_topics(resolved.id)
+                if mqtt_filter_matches(topic_filter, current.message.topic)
             ),
-            key=lambda state: state.topic,
+            key=lambda current: current.message.topic,
         )
         aged = tuple(
-            (state, self._age_seconds(captured_at, state.received_at))
-            for state in matching
+            (
+                current,
+                self._age_seconds(captured_at, current.message.received_at),
+            )
+            for current in matching
         )
         fresh = tuple(
-            (state, age)
-            for state, age in aged
+            (current, age)
+            for current, age in aged
             if max_age_seconds is None or age <= max_age_seconds
         )
         stale_count = len(aged) - len(fresh)
@@ -173,12 +181,12 @@ class BrokerSnapshotService:
         )
         topics = tuple(
             self._topic_snapshot(
-                state,
+                current,
                 age,
                 payload_limit_bytes,
                 observation_started_at=observation_started_at,
             )
-            for state, age in selected
+            for current, age in selected
         )
 
         observed_for_seconds = (
@@ -240,47 +248,53 @@ class BrokerSnapshotService:
     @classmethod
     def _topic_snapshot(
         cls,
-        state: MqttObservation,
+        current: CurrentTopic,
         age_seconds: float,
         payload_limit_bytes: int,
         *,
         observation_started_at: datetime | None,
     ) -> SnapshotTopicState:
+        message = current.message
         return SnapshotTopicState(
-            topic=state.topic,
-            payload=cls._render_payload(state, payload_limit_bytes),
-            qos=state.qos,
-            retain=state.retain,
-            received_at=cls._as_utc(state.received_at),
+            topic=message.topic,
+            payload=cls._render_payload(message, payload_limit_bytes),
+            qos=message.qos,
+            retain=message.retain,
+            received_at=cls._as_utc(message.received_at),
             age_seconds=age_seconds,
-            message_count=state.message_count,
-            source=state.source,
-            status=cls._topic_status(state, observation_started_at),
+            message_count=message.message_count,
+            source=(
+                ObservationSource.STORED
+                if current.status is ObservationStatus.CACHED
+                else ObservationSource.LIVE
+            ),
+            status=cls._topic_status(current, observation_started_at),
         )
 
     @classmethod
     def _topic_status(
         cls,
-        state: MqttObservation,
+        current: CurrentTopic,
         observation_started_at: datetime | None,
     ) -> SnapshotTopicStatus:
+        message = current.message
         if (
             observation_started_at is not None
-            and cls._as_utc(state.received_at)
+            and cls._as_utc(message.received_at)
             < cls._as_utc(observation_started_at)
         ):
             return SnapshotTopicStatus.STALE
-        if state.source == ObservationSource.STORED:
+        if current.status is ObservationStatus.CACHED:
             return SnapshotTopicStatus.CACHED
         return SnapshotTopicStatus.LIVE
 
     @staticmethod
     def _render_payload(
-        state: MqttObservation,
+        message: TopicMessage,
         payload_limit_bytes: int,
     ) -> SnapshotPayload:
-        available = bytes(state.payload)
-        original_size = max(state.payload_size or 0, len(available))
+        available = bytes(message.payload)
+        original_size = max(message.payload_size, len(available))
         rendered = available[:payload_limit_bytes]
         try:
             available.decode("utf-8")
@@ -310,7 +324,7 @@ class BrokerSnapshotService:
     def _limitations(
         *,
         status: object,
-        matching: list[MqttObservation],
+        matching: list[CurrentTopic],
         topics: tuple[SnapshotTopicState, ...],
         observation_started_at: datetime | None,
         dropped_message_count: int,
@@ -325,7 +339,9 @@ class BrokerSnapshotService:
             limitations.append(SnapshotLimitation.BROKER_DISCONNECTED)
         if observation_started_at is None:
             limitations.append(SnapshotLimitation.OBSERVATION_NOT_STARTED)
-        if any(state.source == ObservationSource.STORED for state in matching):
+        if any(
+            current.status is ObservationStatus.CACHED for current in matching
+        ):
             limitations.append(
                 SnapshotLimitation.STORED_STATE_PREDATES_OBSERVATION
             )