skcomms 0.2.2__tar.gz → 0.2.3__tar.gz

{skcomms-0.2.2 → skcomms-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skcomms
-Version: 0.2.2
+Version: 0.2.3
 Summary: Sovereign communications for AI agents — multi-channel transport + FQID realm addressing
 Author-email: smilinTux <chefboyrdave2.1@gmail.com>
 License: GPL-3.0-or-later

{skcomms-0.2.2 → skcomms-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skcomms"
-version = "0.2.2"
+version = "0.2.3"
 description = "Sovereign communications for AI agents — multi-channel transport + FQID realm addressing"
 readme = "README.md"
 license = {text = "GPL-3.0-or-later"}

{skcomms-0.2.2 → skcomms-0.2.3}/src/skcomms/__init__.py

@@ -15,7 +15,7 @@ FQID / realm layer (pre-alpha stubs, implementations landing in coord tasks):
     from skcomms.cluster import ...
 """
 
-__version__ = "0.1.7"
+__version__ = "0.2.3"
 
 from .core import SKComms, SKComm
 from .crypto import EnvelopeCrypto, KeyStore

{skcomms-0.2.2 → skcomms-0.2.3}/src/skcomms/api.py

@@ -224,6 +224,20 @@ async def lifespan(app: FastAPI):
         logger.exception("Failed to start depth-monitor loop")
         _depth_monitor_task = None
 
+    # Geo self-seed: opt-in (SKCOMMS_GEO_SEED_FLEET) upsert of the sovereign
+    # fleet nodes into the process-global geo store so the skmap pane
+    # (GET /api/v1/geo/units) shows units before a live CoT device connects.
+    # Fed through the real upsert_from_cot path; clearly labeled fleet:<node>
+    # seeds; superseded by real CoT once a feed is wired. See geo_seed.py.
+    try:
+        from .geo_seed import seed_fleet_if_enabled
+
+        seeded = seed_fleet_if_enabled()
+        if seeded:
+            logger.info("Geo store seeded with %d fleet unit(s): %s", len(seeded), seeded)
+    except Exception:
+        logger.exception("Failed to seed geo store")
+
     yield
 
     logger.info("Shutting down SKComms API server...")
@@ -777,6 +791,58 @@ async def get_capabilities():
     return build_capabilities(get_skcomms())
 
 
+@app.get("/api/v1/geo/units", tags=["geo"])
+async def get_geo_units(include_stale: bool = False, format: str = "units"):
+    """Current situational picture: live unit / marker / waypoint positions.
+
+    The backend half of the Flutter ``skmap`` pane. Source of truth is the live
+    CoT store in the separate ``skcot`` service process, exposed read-only over
+    HTTP (``skcot.geo_http``, default ``http://127.0.0.1:8091/geo/units``, env
+    ``SKCOT_GEO_URL``). When that bridge is reachable AND has units, its REAL
+    telemetry is returned. Otherwise this falls back to the process-global local
+    store (see :mod:`skcomms.geo_store`, the opt-in fleet seed). Both paths are
+    fail-soft: an empty or unreachable bridge yields the correct shape, never a
+    500.
+
+    Args:
+        include_stale: Include fixes past their CoT stale time / TTL. Default
+            ``False`` (only fresh positions, what a live map wants).
+        format: ``"units"`` (default) → ``{"units": [...], "count": N}`` where
+            each item is a flat GeoUnit dict (``uid``, ``callsign``, ``lat``,
+            ``lon``, ``cot_type``, ``last_seen``, ...); ``"geojson"`` → a
+            GeoJSON ``FeatureCollection``. Both are accepted by the app's
+            ``GeoUnit.fromJson`` (which reads ``features`` then ``units``).
+
+    Returns:
+        A dict the ``skmap`` client renders directly.
+    """
+    from .geo_store import fetch_skcot_geo, geo_payload_has_units, get_geo_store
+
+    fmt = "geojson" if format == "geojson" else "units"
+
+    # Prefer the live skcot store (real CoT). Blocking fetch off the event loop.
+    remote = await asyncio.to_thread(
+        fetch_skcot_geo, include_stale=include_stale, fmt=fmt
+    )
+    if remote is not None and geo_payload_has_units(remote):
+        return remote
+
+    # Fall back to the local in-process store (fleet seed) when skcot is
+    # unreachable OR reports zero units. Fail-soft: the local store wraps the
+    # shared skcot GeoStore, so if the skcot package is somehow absent this
+    # still yields the correct empty shape rather than a 500.
+    try:
+        store = get_geo_store()
+        if fmt == "geojson":
+            return store.to_feature_collection(include_stale=include_stale)
+        units = store.units_json(include_stale=include_stale)
+        return {"units": units, "count": len(units)}
+    except Exception:  # noqa: BLE001 - the map endpoint must never 500
+        if fmt == "geojson":
+            return {"type": "FeatureCollection", "features": []}
+        return {"units": [], "count": 0}
+
+
 class AccessTokenRequest(BaseModel):
     """Request to mint a capauth token for a single sk-access tool call.
 

{skcomms-0.2.2 → skcomms-0.2.3}/src/skcomms/capabilities.py

@@ -128,6 +128,7 @@ _TRANSPORT_PROBES: dict[str, int] = {
 _MODULE_HINTS: list[str] = [
     "chats",
     "spaces",
+    "skcode",
     "activity",
     "profile",
     "skmap",

skcomms-0.2.3/src/skcomms/geo_seed.py

@@ -0,0 +1,157 @@
+"""Fleet self-seed for the SKMap geo store (``GET /api/v1/geo/units``).
+
+Why this exists
+---------------
+The situational picture served by ``/api/v1/geo/units`` is fed by the CoT
+(Cursor-on-Target) plane. On this fleet the live CoT service (``skcot.service``,
+TAK/ATAK streaming on :8087/:8089/:6969) runs as a **separate process** with its
+own in-memory ``GeoStore``; it only fills up when a real ATAK/iTAK device (or a
+federated peer's CoT) actually beacons a position. Until a device connects, that
+store -- and therefore the ``skcomms-api`` process's own ``get_geo_store()`` -- is
+empty, so the Flutter ``skmap`` pane shows nothing.
+
+This module upserts the **sovereign fleet nodes** as CoT units so the map is not
+empty and the whole plumbing (``upsert_from_cot`` -> store -> endpoint ->
+``GeoUnit.fromJson``) is demonstrably working end to end. It is fed through the
+*real* :meth:`skcot.geo.GeoStore.upsert_from_cot` path (building genuine
+:class:`skcot.codec.CotEvent` atoms), not a shortcut, so it exercises exactly the
+code a live feed uses. On a deployment without ``skcot`` installed it falls back
+to the store's plain ``upsert`` so the seed still lands.
+
+Clearly a seed, not real telemetry
+-----------------------------------
+Every seeded entity is unmistakable as a placeholder:
+
+  * ``uid`` / ``callsign`` are prefixed ``fleet:`` (e.g. ``fleet:chiap08``),
+  * ``source`` is ``"seed:self"``,
+  * coordinates are **placeholders** -- these compute nodes have no GPS. They are
+    spread out only so the markers don't stack on the map.
+
+Replacing the seed with a real CoT feed
+---------------------------------------
+When a real position feed is wired (an ATAK/iTAK device connecting to
+``skcot.service``, or CoT federated in from a peer), those live units flow into
+the same store and supersede-by-``uid``. The seed units keep their ``fleet:``
+uids and simply coexist; set ``SKCOMMS_GEO_SEED_FLEET=0`` to turn the seed off
+entirely once real telemetry is present.
+
+Enablement
+----------
+Off by default (the empty-store contract stays intact for anything that doesn't
+opt in). Set ``SKCOMMS_GEO_SEED_FLEET`` to a truthy value (``1``/``true``/``yes``/
+``on``) to have the ``skcomms-api`` lifespan seed the fleet on startup.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# Env flag that opts the api-server lifespan into seeding the fleet on startup.
+SEED_ENV = "SKCOMMS_GEO_SEED_FLEET"
+
+# Attribution tag stored on each seeded unit's ``GeoUnit.source``.
+SEED_SOURCE = "seed:self"
+
+# CoT type for a friendly ground unit (atom -> classified as ``kind='unit'``).
+_FLEET_COT_TYPE = "a-f-G-U-C"
+
+
+# Known sovereign fleet nodes. ``lat``/``lon`` are PLACEHOLDERS (these nodes have
+# no GPS); they are only spread apart so seeded markers are individually visible.
+# ``hint`` is the tailscale/LAN address for human reference (not a GeoUnit field).
+_FLEET_NODES: list[dict[str, Any]] = [
+    {"name": "noroc2027", "hint": "100.108.59.57 / .158 dev+primary (this host)",
+     "lat": 39.0000, "lon": -77.0000},
+    {"name": "dot100", "hint": "192.168.0.100 RTX 5060 Ti / inference",
+     "lat": 39.0200, "lon": -77.0200},
+    {"name": "dot41", "hint": "100.86.156.5 / .41 tailscale-only heavy-build",
+     "lat": 38.9800, "lon": -77.0200},
+    {"name": "chiap08", "hint": "100.81.238.58 terminal node",
+     "lat": 39.0200, "lon": -76.9800},
+]
+
+
+def is_seed_enabled() -> bool:
+    """Whether the fleet self-seed is opted in via :data:`SEED_ENV`."""
+    return os.environ.get(SEED_ENV, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _upsert_node(store: Any, node: dict[str, Any]) -> Optional[str]:
+    """Upsert a single fleet node into *store*; return its uid or ``None``.
+
+    Feeds through the real ``upsert_from_cot`` path (a genuine CoT atom) when the
+    ``skcot`` plane is available, else falls back to the store's plain ``upsert``
+    (used by the in-process fallback store). Fails soft: logs and returns
+    ``None`` on any error so one bad node can't abort the whole seed.
+    """
+    name = node["name"]
+    uid = f"fleet:{name}"
+    lat, lon = float(node["lat"]), float(node["lon"])
+    try:
+        try:
+            # Real path: build a CoT atom and let the geo plane classify + store it.
+            from skcot.codec import CotEvent, CotPoint
+
+            cot = CotEvent(
+                uid=uid,
+                type=_FLEET_COT_TYPE,
+                how="m-g",
+                point=CotPoint(lat=lat, lon=lon),
+                callsign=uid,
+            )
+            unit = store.upsert_from_cot(cot, source=SEED_SOURCE)
+            # upsert_from_cot returns None only if it classified the event as
+            # non-mappable; an ``a-*`` atom with a real fix never does.
+            return getattr(unit, "uid", uid) if unit is not None else None
+        except (ImportError, NotImplementedError):
+            # Fallback store (no skcot): upsert a plain GeoUnit-shaped dict.
+            store.upsert(
+                {
+                    "uid": uid,
+                    "callsign": uid,
+                    "cot_type": _FLEET_COT_TYPE,
+                    "lat": lat,
+                    "lon": lon,
+                    "kind": "unit",
+                    "source": SEED_SOURCE,
+                }
+            )
+            return uid
+    except Exception as exc:  # noqa: BLE001 — one bad node must not abort the seed
+        logger.warning("geo seed: could not upsert %s (%s): %s", uid, node.get("hint"), exc)
+        return None
+
+
+def seed_fleet(store: Any = None) -> list[str]:
+    """Upsert the sovereign fleet nodes as seed CoT units into *store*.
+
+    Idempotent: entities are keyed by ``uid`` (``fleet:<name>``), so re-running
+    updates in place rather than duplicating. Returns the list of upserted uids.
+
+    Args:
+        store: The geo store to seed. Defaults to the process-global store from
+            :func:`skcomms.geo_store.get_geo_store` (the one the endpoint reads).
+    """
+    if store is None:
+        from .geo_store import get_geo_store
+
+        store = get_geo_store()
+    uids = [uid for node in _FLEET_NODES if (uid := _upsert_node(store, node))]
+    logger.info("geo seed: upserted %d fleet unit(s): %s", len(uids), uids)
+    return uids
+
+
+def seed_fleet_if_enabled(store: Any = None) -> list[str]:
+    """Seed the fleet only when :data:`SEED_ENV` is opted in; else a no-op.
+
+    The startup hook: safe to call unconditionally from the api-server lifespan.
+    Returns the upserted uids (empty when the seed is not enabled).
+    """
+    if not is_seed_enabled():
+        logger.info("geo seed: %s not set — fleet self-seed disabled", SEED_ENV)
+        return []
+    return seed_fleet(store)

skcomms-0.2.3/src/skcomms/geo_store.py

@@ -0,0 +1,231 @@
+"""Geo / situational-awareness store accessor for the SKComms daemon.
+
+Serves ``GET /api/v1/geo/units`` (the backend half of the Flutter ``skmap``
+pane). The situational picture, where every unit / marker / waypoint is, is
+produced by the CoT (Cursor-on-Target) bridge, which now lives in the extracted
+``skcot`` package. This module exposes a single **process-global** store that:
+
+  * the CoT bridge / service FEEDS  →
+        ``get_geo_store().upsert_from_cot(cot, source=...)``
+    (or ``.upsert(unit)`` for a pre-built / federated entity), and
+  * the ``/api/v1/geo/units`` endpoint READS →
+        ``get_geo_store().units_json(include_stale=...)``.
+
+That single accessor is the documented seam for wiring the real position feed:
+whoever runs the CoT service inside (or alongside) the daemon upserts into the
+store returned by :func:`get_geo_store`, and the endpoint publishes it.
+
+One shared type
+---------------
+There is a single ``GeoUnit`` / ``GeoStore`` type, and it lives in
+:mod:`skcot.geo` (the authoritative, CoT-fed store). This module does **not**
+reimplement it. :class:`SkcotGeoStore` is a *thin adapter* over that shared
+type: it holds a real :class:`skcot.geo.GeoStore` and delegates everything to
+it, adding only one skcomms-side convenience -- dict-coercion on ``upsert`` so
+the fleet self-seed (and tests) can feed plain GeoUnit-shaped dicts. All
+storage, staleness, GeoJSON serialization and CoT classification come from the
+shared skcot type, so the two processes agree on unit serialization by
+construction (a GeoUnit serialized by skcot deserializes identically here).
+
+The local adapter store is only ever the *fallback* the endpoint reads when the
+live skcot HTTP bridge (:func:`fetch_skcot_geo`) has no units; it is seeded with
+sovereign fleet placeholders that must not expire, so its inner store is built
+with an infinite TTL (the real freshness clock lives on the live skcot store
+behind the HTTP bridge).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import urllib.parse
+import urllib.request
+from typing import Any, Optional
+
+logger = logging.getLogger("skcomms.geo_store")
+
+# --------------------------------------------------------------------------
+# Live skcot bridge (source of truth = skcot's process, not this one).
+# --------------------------------------------------------------------------
+#
+# The real situational picture lives in the `skcot` service process (fed from
+# TCP/TLS/mesh CoT + federation). That process exposes it read-only over HTTP
+# (`skcot.geo_http`, default 127.0.0.1:8091). When that endpoint is reachable
+# AND has units, it is the source of truth; otherwise we fall back to this
+# process's local store (the opt-in fleet seed), so the map endpoint always
+# returns a valid shape and never 500s.
+
+SKCOT_GEO_URL_ENV = "SKCOT_GEO_URL"
+DEFAULT_SKCOT_GEO_URL = "http://127.0.0.1:8091/geo/units"
+SKCOT_GEO_TIMEOUT_ENV = "SKCOT_GEO_TIMEOUT_S"
+DEFAULT_SKCOT_GEO_TIMEOUT_S = 0.75
+
+
+def skcot_geo_url() -> Optional[str]:
+    """The skcot geo endpoint URL, or None if the bridge is disabled.
+
+    Defaults to :data:`DEFAULT_SKCOT_GEO_URL`. Set ``SKCOT_GEO_URL`` to an empty
+    string to disable the bridge and serve only the local in-process store.
+    """
+    url = os.environ.get(SKCOT_GEO_URL_ENV, DEFAULT_SKCOT_GEO_URL)
+    return url or None
+
+
+def _skcot_geo_timeout() -> float:
+    try:
+        return float(os.environ.get(SKCOT_GEO_TIMEOUT_ENV, DEFAULT_SKCOT_GEO_TIMEOUT_S))
+    except (TypeError, ValueError):
+        return DEFAULT_SKCOT_GEO_TIMEOUT_S
+
+
+def fetch_skcot_geo(*, include_stale: bool = False, fmt: str = "units") -> Optional[Any]:
+    """Fetch the live situational picture from skcot's HTTP endpoint.
+
+    Blocking (stdlib ``urllib``) with a short timeout; call from an async
+    handler via ``asyncio.to_thread`` so the event loop is never blocked.
+
+    Returns the parsed JSON payload (a ``{"units": [...], "count": N}`` dict for
+    ``fmt="units"``, a GeoJSON ``FeatureCollection`` for ``fmt="geojson"``), or
+    ``None`` on ANY failure (bridge disabled, connection refused, timeout,
+    non-200, unparseable body). Fail-soft: never raises to the caller.
+    """
+    url = skcot_geo_url()
+    if not url:
+        return None
+    params: dict[str, str] = {}
+    if include_stale:
+        params["include_stale"] = "1"
+    if fmt == "geojson":
+        params["format"] = "geojson"
+    if params:
+        sep = "&" if urllib.parse.urlsplit(url).query else "?"
+        url = url + sep + urllib.parse.urlencode(params)
+    try:
+        req = urllib.request.Request(url, method="GET")
+        with urllib.request.urlopen(req, timeout=_skcot_geo_timeout()) as resp:
+            if getattr(resp, "status", 200) != 200:
+                return None
+            body = resp.read()
+        return json.loads(body.decode("utf-8"))
+    except Exception as exc:  # noqa: BLE001 - map endpoint must never 500 on this
+        logger.debug("skcot geo fetch failed (%s): %s", url, exc)
+        return None
+
+
+def geo_payload_has_units(payload: Any) -> bool:
+    """Whether a skcot geo payload actually carries at least one unit.
+
+    Handles both response shapes: the flat ``{"units": [...], "count": N}`` and
+    the GeoJSON ``{"type": "FeatureCollection", "features": [...]}``.
+    """
+    if not isinstance(payload, dict):
+        return False
+    units = payload.get("units")
+    if isinstance(units, list):
+        return len(units) > 0
+    feats = payload.get("features")
+    if isinstance(feats, list):
+        return len(feats) > 0
+    return False
+
+# --------------------------------------------------------------------------
+# Thin adapter over the ONE shared skcot GeoStore type.
+# --------------------------------------------------------------------------
+
+
+class SkcotGeoStore:
+    """Thin skcomms-side adapter over the shared :class:`skcot.geo.GeoStore`.
+
+    This is **not** a reimplementation. It composes a real
+    :class:`skcot.geo.GeoStore` (the single shared type -- CoT classification,
+    staleness/TTL, GeoJSON serialization, federation envelopes all live there)
+    and delegates every attribute to it via :meth:`__getattr__`. The only thing
+    it adds is dict-coercion on :meth:`upsert`, so the fleet self-seed and the
+    API can feed plain GeoUnit-shaped dicts as well as real
+    :class:`skcot.geo.GeoUnit` objects.
+
+    ``skcot`` is imported lazily (in ``__init__``) rather than at module import
+    time: ``skcot`` depends on ``skcomms``, so a top-level import here would be a
+    packaging cycle. Because this module is itself imported lazily (only from the
+    endpoint / seed paths, after ``skcomms`` has fully loaded), the lazy import
+    resolves cleanly.
+
+    The inner store is built with an infinite TTL by default: the local store is
+    only the endpoint's *fallback* (fleet-seed placeholders that must not
+    expire); the authoritative freshness clock lives on the live skcot store
+    reached over the HTTP bridge.
+    """
+
+    def __init__(self, inner: Any = None, *, ttl_s: float = float("inf")) -> None:
+        if inner is None:
+            from skcot.geo import GeoStore  # type: ignore  # lazy: avoid dep cycle
+
+            inner = GeoStore(ttl_s=ttl_s)
+        self._inner = inner
+
+    def upsert(self, unit: Any) -> Any:
+        """Upsert a :class:`skcot.geo.GeoUnit` or a GeoUnit-shaped dict.
+
+        A dict is coerced into the shared :class:`skcot.geo.GeoUnit` (unknown
+        keys dropped) so the whole store speaks one type; then it is stored by
+        the shared store verbatim.
+        """
+        if isinstance(unit, dict):
+            from skcot.geo import GeoUnit  # type: ignore  # lazy: avoid dep cycle
+
+            fields = set(GeoUnit.model_fields)
+            unit = GeoUnit(**{k: v for k, v in unit.items() if k in fields})
+        return self._inner.upsert(unit)
+
+    def __getattr__(self, name: str) -> Any:
+        # Delegate everything else (upsert_from_cot, units_json,
+        # to_feature_collection, get_all, remove, clear, ...) to the shared
+        # skcot store. Only reached for names not defined on the adapter.
+        return getattr(self._inner, name)
+
+
+# --------------------------------------------------------------------------
+# Process-global accessor.
+# --------------------------------------------------------------------------
+
+_store_lock = threading.Lock()
+_store: Any = None
+
+
+def _new_store() -> Any:
+    """Construct the process-global local store: the shared skcot GeoStore,
+    wrapped in the thin :class:`SkcotGeoStore` adapter."""
+    return SkcotGeoStore()
+
+
+def get_geo_store() -> Any:
+    """Return the process-global geo store singleton (creating it on first use).
+
+    This is the **feed point**: the CoT service upserts into the returned store
+    (``upsert_from_cot`` / ``upsert``) and the endpoint reads from it. One store
+    per process keeps the daemon's map view and any co-resident agent tool
+    reading the same ground truth.
+    """
+    global _store
+    if _store is None:
+        with _store_lock:
+            if _store is None:
+                _store = _new_store()
+    return _store
+
+
+def set_geo_store(store: Any) -> None:
+    """Inject a store (used by the CoT service to share its own GeoStore, and
+    by tests to seed a known picture)."""
+    global _store
+    with _store_lock:
+        _store = store
+
+
+def reset_geo_store() -> None:
+    """Drop the singleton so the next :func:`get_geo_store` rebuilds it (tests)."""
+    global _store
+    with _store_lock:
+        _store = None

{skcomms-0.2.2 → skcomms-0.2.3}/src/skcomms/operator_probe.py

@@ -119,16 +119,36 @@ def _count_queue(pending_dir) -> int:
     return sum(1 for f in p.glob("*.json") if f.is_file())
 
 
+def queue_depth() -> int:
+    """The unified PersistentOutbox pending depth: the ONE backlog metric.
+
+    This is the single canonical outbox-depth probe (coord eb659f61 / roadmap
+    CR-5.3). It counts pending entries under the consolidated skcomms
+    :class:`~skcomms.outbox.PersistentOutbox` retry store
+    (``skcomms.paths.retry_outbox_dir()/pending``, honoring the
+    ``SKCOMMS_OUTBOX_DIR`` override). Both this module's ``QueueDrained``
+    condition and the skchat ``OutboxBounded`` condition (the skchat operator
+    CLI and Atlas's skchat adapter, "one probe, two consumers") read this same
+    function, so outbox depth is a single source of truth across the fleet.
+
+    Fails SAFE (returns 0 = drained) when the store cannot be read, so a probe
+    failure never raises a false 'outbox flooded' alarm.
+
+    Returns:
+        int: Number of pending entries in the unified retry store.
+    """
+    try:
+        return _count_queue(_pending_dir())
+    except Exception:
+        return 0
+
+
 def _default_probe() -> dict:
     """Best-effort skcomms health from real signals. Fails SAFE (healthy) when
     skcomms is unreachable, so an inability to probe never raises a false alarm."""
-    try:
-        depth = _count_queue(_pending_dir())
-    except Exception:
-        depth = 0
     return {
         "path_healthy": _probe_path_healthy(),
-        "queue_depth": depth,
+        "queue_depth": queue_depth(),
         "queue_limit": _QUEUE_LIMIT,
     }
 
@@ -243,4 +263,5 @@ __all__ = [
     "explain",
     "observe",
     "act",
+    "queue_depth",
 ]