devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/rep_network/sync.py

@@ -0,0 +1,207 @@
+"""
+REP ledger push/pull synchronization.
+
+Protocol:
+  PUSH: POST /rep/entries  body: {entries: [...REPEnvelope dicts...], sender_id: str}
+  PULL: GET  /rep/entries?since=<index_or_0>  → {entries: [...], node_id: str}
+
+Sync is one-directional per call (push OR pull). Full sync = push then pull.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import List
+
+from devtorch_core.rep import REPEnvelope, REPLedger
+from devtorch_core.rep_network.node import NodeRegistry, PeerEntry
+
+
+@dataclass
+class SyncResult:
+    """Result of a push/pull sync operation with a single peer."""
+    peer_node_id: str
+    peer_url: str
+    pushed_count: int = 0
+    pulled_count: int = 0
+    errors: List[str] = field(default_factory=list)
+    success: bool = True
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _timestamp() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _read_entries_from(ledger: REPLedger, since_index: int) -> List[dict]:
+    """Return ledger records (as dicts) with sequence_id > since_index."""
+    all_records = ledger.read_all()
+    return [r for r in all_records if r.get("sequence_id", 0) > since_index]
+
+
+def _pulled_ids_path(ledger: REPLedger):
+    return ledger.rep_dir / "pulled_ids.json"
+
+
+def _envelope_ids_in_ledger(ledger: REPLedger) -> set:
+    """Return set of envelope_ids already pulled (persisted sidecar + ledger records)."""
+    ids: set = set()
+    # Read from sidecar file (persists across calls)
+    p = _pulled_ids_path(ledger)
+    if p.exists():
+        try:
+            ids = set(json.loads(p.read_text(encoding="utf-8")))
+        except Exception:
+            pass
+    # Also check envelope.payload_hash in stored records for additional dedup
+    for record in ledger.read_all():
+        env = record.get("envelope", {})
+        eid = env.get("envelope_id")
+        if eid:
+            ids.add(eid)
+    return ids
+
+
+def _persist_pulled_id(ledger: REPLedger, eid: str) -> None:
+    """Persist an envelope_id to the sidecar so future pulls skip it."""
+    p = _pulled_ids_path(ledger)
+    try:
+        existing: set = set(json.loads(p.read_text(encoding="utf-8"))) if p.exists() else set()
+        existing.add(eid)
+        p.write_text(json.dumps(list(existing)), encoding="utf-8")
+    except Exception:
+        pass
+
+
+def _post_json(url: str, payload: dict, timeout: int = 10) -> dict:
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=data,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def _get_json(url: str, timeout: int = 10) -> dict:
+    req = urllib.request.Request(url, method="GET")
+    with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+        return json.loads(resp.read().decode("utf-8"))
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def push_to_peer(
+    ledger: REPLedger,
+    peer: PeerEntry,
+    since_index: int = 0,
+) -> SyncResult:
+    """POST entries from ledger to peer.  Never raises."""
+    result = SyncResult(peer_node_id=peer.node_id, peer_url=peer.url)
+    try:
+        records = _read_entries_from(ledger, since_index)
+        entries = [r.get("envelope", {}) for r in records]
+        if not entries:
+            result.pushed_count = 0
+            return result
+
+        identity_path = ledger.rep_dir / "node_id"
+        sender_id = identity_path.read_text().strip() if identity_path.exists() else ""
+
+        url = f"{peer.url.rstrip('/')}/rep/entries"
+        _post_json(url, {"entries": entries, "sender_id": sender_id})
+        result.pushed_count = len(entries)
+    except Exception as exc:  # noqa: BLE001
+        result.success = False
+        result.errors.append(str(exc))
+    return result
+
+
+def pull_from_peer(
+    ledger: REPLedger,
+    peer: PeerEntry,
+    since_index: int = 0,
+) -> SyncResult:
+    """GET entries from peer and append new ones to ledger.  Never raises."""
+    result = SyncResult(peer_node_id=peer.node_id, peer_url=peer.url)
+    try:
+        url = f"{peer.url.rstrip('/')}/rep/entries?since={since_index}"
+        response = _get_json(url)
+        entries = response.get("entries", [])
+        if not entries:
+            return result
+
+        existing_ids = _envelope_ids_in_ledger(ledger)
+        pulled = 0
+        for entry_dict in entries:
+            eid = entry_dict.get("envelope_id")
+            if eid and eid in existing_ids:
+                continue
+            # Build envelope from the dict; tolerate extra keys
+            try:
+                envelope = REPEnvelope.from_dict(entry_dict)
+            except Exception:  # noqa: BLE001
+                continue
+            ts = entry_dict.get("timestamp", _timestamp())
+            ledger.append(envelope, timestamp=ts)
+            if eid:
+                existing_ids.add(eid)
+                _persist_pulled_id(ledger, eid)
+            pulled += 1
+
+        result.pulled_count = pulled
+    except Exception as exc:  # noqa: BLE001
+        result.success = False
+        result.errors.append(str(exc))
+    return result
+
+
+def sync_with_peer(ledger: REPLedger, peer: PeerEntry) -> SyncResult:
+    """Push then pull with a single peer; merge into one SyncResult."""
+    push_result = push_to_peer(ledger, peer)
+    pull_result = pull_from_peer(ledger, peer)
+
+    merged = SyncResult(
+        peer_node_id=peer.node_id,
+        peer_url=peer.url,
+        pushed_count=push_result.pushed_count,
+        pulled_count=pull_result.pulled_count,
+        errors=push_result.errors + pull_result.errors,
+        success=push_result.success and pull_result.success,
+    )
+    return merged
+
+
+def sync_all_peers(
+    ledger: REPLedger,
+    registry: NodeRegistry,
+) -> List[SyncResult]:
+    """Sync with every peer in registry.  Never raises."""
+    results: List[SyncResult] = []
+    try:
+        peers = registry.list_peers()
+    except Exception:  # noqa: BLE001
+        return results
+
+    for peer in peers:
+        try:
+            results.append(sync_with_peer(ledger, peer))
+        except Exception as exc:  # noqa: BLE001
+            results.append(SyncResult(
+                peer_node_id=peer.node_id,
+                peer_url=peer.url,
+                success=False,
+                errors=[str(exc)],
+            ))
+    return results

devtorch_core/sensitivity.py

@@ -0,0 +1,182 @@
+"""
+Sprint 3 – Sensitivity schema and storage.
+
+SensitivityEvent captures a single sensitivity observation emitted by a
+reasoning node, including an optional numerical value, confidence, and a
+disclosure level (PUBLIC / PROTECTED / PRIVATE).
+
+SensitivityStore persists events as an append-only JSONL file under
+`.GCC/sensitivities/events.jsonl` and maintains a concept-keyed index at
+`.GCC/sensitivities/index.json` so callers can filter without full scans.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as _dt
+import json
+import uuid
+from pathlib import Path
+from typing import List, Optional
+
+
+DISCLOSURE_LEVELS = ("PUBLIC", "PROTECTED", "PRIVATE")
+
+
+@dataclasses.dataclass
+class SensitivityEvent:
+    """
+    A single sensitivity observation.
+
+    Fields
+    ------
+    source_node       : Identifier of the reasoning node that emitted this event.
+    target_concept    : The concept/variable whose sensitivity is being reported.
+    counterfactuals   : Free-text description of the counterfactual question.
+    confidence        : Confidence in the sensitivity estimate; float in [0, 1].
+    disclosure_level  : One of PUBLIC, PROTECTED, PRIVATE.
+    numerical_value   : Optional point-estimate of the sensitivity magnitude.
+    uncertainty       : Optional ±uncertainty for numerical_value.
+    message           : Human-readable annotation.
+    event_id          : UUID assigned on creation.
+    created_at        : ISO-8601 UTC timestamp.
+    """
+
+    source_node: str
+    target_concept: str
+    counterfactuals: str
+    confidence: float
+    disclosure_level: str
+    numerical_value: Optional[float] = None
+    uncertainty: Optional[float] = None
+    message: str = ""
+    event_id: str = dataclasses.field(
+        default_factory=lambda: str(uuid.uuid4())
+    )
+    created_at: str = dataclasses.field(
+        default_factory=lambda: _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+    )
+    agent_id: Optional[str] = None
+    session_id: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if self.disclosure_level not in DISCLOSURE_LEVELS:
+            raise ValueError(
+                f"disclosure_level must be one of {DISCLOSURE_LEVELS}, "
+                f"got '{self.disclosure_level}'"
+            )
+        if not (0.0 <= self.confidence <= 1.0):
+            raise ValueError(
+                f"confidence must be in [0, 1], got {self.confidence}"
+            )
+        if not self.source_node.strip():
+            raise ValueError("source_node must not be empty.")
+        if not self.target_concept.strip():
+            raise ValueError("target_concept must not be empty.")
+
+    def to_dict(self) -> dict:
+        return dataclasses.asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SensitivityEvent":
+        known = {f.name for f in dataclasses.fields(cls)}
+        return cls(**{k: v for k, v in d.items() if k in known})
+
+
+class SensitivityStore:
+    """
+    Append-only storage for SensitivityEvent objects.
+
+    Layout (relative to the `.GCC/sensitivities/` directory):
+      events.jsonl  – one JSON object per line, ordered by insertion.
+      index.json    – concept_name → [event_id, …], rebuilt on every write.
+    """
+
+    EVENTS_FILE = "events.jsonl"
+    INDEX_FILE = "index.json"
+
+    def __init__(self, sensitivities_dir: Path) -> None:
+        self.dir = sensitivities_dir
+
+    def _ensure_dir(self) -> None:
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def events_path(self) -> Path:
+        return self.dir / self.EVENTS_FILE
+
+    @property
+    def index_path(self) -> Path:
+        return self.dir / self.INDEX_FILE
+
+    # ------------------------------------------------------------------
+    # Internal index helpers
+    # ------------------------------------------------------------------
+
+    def _load_index(self) -> dict:
+        if not self.index_path.exists():
+            return {}
+        try:
+            return json.loads(self.index_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return {}
+
+    def _save_index(self, index: dict) -> None:
+        self.index_path.write_text(
+            json.dumps(index, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def add(self, event: SensitivityEvent) -> str:
+        """Persist *event* and update the concept index. Returns event_id."""
+        self._ensure_dir()
+        with self.events_path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(event.to_dict(), sort_keys=True) + "\n")
+
+        index = self._load_index()
+        index.setdefault(event.target_concept, []).append(event.event_id)
+        self._save_index(index)
+        return event.event_id
+
+    def list_all(self) -> List[SensitivityEvent]:
+        """Return all stored events in insertion order."""
+        if not self.events_path.exists():
+            return []
+        events: List[SensitivityEvent] = []
+        with self.events_path.open("r", encoding="utf-8") as fh:
+            for raw in fh:
+                line = raw.strip()
+                if not line:
+                    continue
+                try:
+                    events.append(SensitivityEvent.from_dict(json.loads(line)))
+                except (json.JSONDecodeError, TypeError, ValueError):
+                    pass
+        return events
+
+    def filter(
+        self,
+        concept: Optional[str] = None,
+        disclosure_level: Optional[str] = None,
+        source_node: Optional[str] = None,
+    ) -> List[SensitivityEvent]:
+        """
+        Return events that match *all* provided filter criteria.
+        Any criterion that is None is treated as a wildcard.
+        """
+        events = self.list_all()
+        if concept is not None:
+            events = [e for e in events if e.target_concept == concept]
+        if disclosure_level is not None:
+            events = [e for e in events if e.disclosure_level == disclosure_level]
+        if source_node is not None:
+            events = [e for e in events if e.source_node == source_node]
+        return events
+
+    def concepts(self) -> List[str]:
+        """Return all distinct concept names seen so far."""
+        return sorted(self._load_index().keys())

devtorch_core/serve.py

@@ -0,0 +1,258 @@
+"""
+Sprint 25 — Unified local dev server: `devtorch serve`.
+
+Combines the existing FastAPI apps into a single local server:
+  - Proxy      (mounted at /proxy)
+  - Dashboard  (mounted at /dashboard)
+  - Broadcast  (mounted at /broadcast)
+  - MCP        (spawned as a stdio subprocess)
+
+Usage:
+    from devtorch_core.serve import serve_all
+    serve_all(host="127.0.0.1", port=8765)
+
+Or via the CLI helper (intended for integration in devtorch_cli/main.py):
+    from devtorch_core.serve import cmd_serve
+    cmd_serve(args)
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+from devtorch_core.broadcast.broadcaster import create_broadcast_app, EventBroadcaster
+from devtorch_core.dashboard_api import create_app as create_dashboard_app
+from devtorch_core.proxy.server import create_app as create_proxy_app
+from devtorch_core.proxy.server import find_gcc_repo as proxy_find_gcc_repo
+
+try:
+    from fastapi import FastAPI
+    import uvicorn
+
+    _HAS_FASTAPI = True
+except ImportError:  # pragma: no cover
+    _HAS_FASTAPI = False
+
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8765
+
+
+# ---------------------------------------------------------------------------
+# GCC repository resolution
+# ---------------------------------------------------------------------------
+
+
+def _resolve_gcc_repo(gcc_path: Optional[str] = None) -> Optional[Any]:
+    """
+    Resolve an initialised GCCRepository.
+
+    Search order:
+    1. Explicit `gcc_path` argument.
+    2. DEVTORCH_GCC_PATH environment variable.
+    3. Walk upward from cwd (proxy server discovery).
+    """
+    from devtorch_core import GCCRepository
+
+    candidates: list[str] = []
+    if gcc_path is not None:
+        candidates.append(str(gcc_path))
+    explicit = os.environ.get("DEVTORCH_GCC_PATH", "").strip()
+    if explicit:
+        candidates.append(explicit)
+
+    for candidate in candidates:
+        try:
+            repo = GCCRepository.at(Path(candidate))
+            if repo.is_initialized():
+                return repo
+        except Exception:
+            continue
+
+    return proxy_find_gcc_repo()
+
+
+def _repo_path(repo: Optional[Any]) -> Optional[Path]:
+    """Best-effort extraction of a Path from a GCCRepository-like object."""
+    if repo is None:
+        return None
+    if hasattr(repo, "root"):
+        return Path(repo.root)
+    if hasattr(repo, "path"):
+        return Path(repo.path)
+    return Path(repo)
+
+
+# ---------------------------------------------------------------------------
+# App factory
+# ---------------------------------------------------------------------------
+
+
+def build_app(
+    gcc_repo: Optional[Any] = None,
+    broadcaster: Optional[EventBroadcaster] = None,
+    mcp_process: Optional[subprocess.Popen] = None,
+) -> "FastAPI":
+    """
+    Build a single FastAPI app combining proxy, dashboard, and broadcast.
+
+    Parameters
+    ----------
+    gcc_repo:
+        An initialised GCCRepository used by the proxy and dashboard.
+    broadcaster:
+        Optional EventBroadcaster instance; a fresh one is created if None.
+    mcp_process:
+        Optional subprocess.Popen handle for the stdio MCP server. If provided,
+        the unified /health endpoint reports its runtime status.
+    """
+    if not _HAS_FASTAPI:
+        raise ImportError(
+            "FastAPI and uvicorn are required for the unified server. "
+            "Install them with: pip install fastapi uvicorn"
+        )
+
+    app = FastAPI(
+        title="DevTorch Unified Local Server",
+        version="0.1.0",
+        description=(
+            "Local dev server that unifies the DevTorch proxy, dashboard API, "
+            "SSE broadcaster, and MCP server into a single process."
+        ),
+    )
+
+    # Proxy app (mounted at /proxy)
+    proxy_app = create_proxy_app(gcc_repo)
+    app.mount("/proxy", proxy_app)
+
+    # Dashboard app (mounted at /dashboard)
+    dashboard_path = _repo_path(gcc_repo)
+    dashboard_app = create_dashboard_app(dashboard_path)
+    app.mount("/dashboard", dashboard_app)
+
+    # Broadcast app (mounted at /broadcast)
+    broadcast_broadcaster = broadcaster or EventBroadcaster()
+    broadcast_app = create_broadcast_app(broadcast_broadcaster)
+    if broadcast_app is not None:
+        app.mount("/broadcast", broadcast_app)
+
+    # Keep the MCP subprocess handle accessible to the health endpoint.
+    if mcp_process is not None:
+        app.state.mcp_process = mcp_process
+
+    @app.get("/health")
+    def health() -> dict:
+        """Aggregate health check for all mounted sub-services."""
+        mcp_status = "not_started"
+        mcp_proc = getattr(app.state, "mcp_process", None)
+        if mcp_proc is not None:
+            try:
+                mcp_status = "running" if mcp_proc.poll() is None else "stopped"
+            except Exception:
+                mcp_status = "unknown"
+
+        return {
+            "status": "ok",
+            "proxy": "ok",
+            "dashboard": "ok",
+            "broadcast": "ok",
+            "mcp": mcp_status,
+        }
+
+    return app
+
+
+# ---------------------------------------------------------------------------
+# Server runner
+# ---------------------------------------------------------------------------
+
+
+def serve_all(
+    host: str = DEFAULT_HOST,
+    port: int = DEFAULT_PORT,
+    gcc_path: Optional[str] = None,
+) -> None:
+    """
+    Start the unified FastAPI app and spawn the stdio MCP server as a subprocess.
+
+    The MCP server is launched with `python -m devtorch_core.mcp.server` using
+    the same interpreter and inherits the current environment. If a GCC repo
+    is resolved, DEVTORCH_GCC_PATH is set so the MCP server can find it.
+
+    Parameters
+    ----------
+    host:
+        Host interface to bind (default 127.0.0.1).
+    port:
+        Port to bind (default 8765).
+    gcc_path:
+        Optional project root containing an initialised `.GCC/` directory.
+    """
+    if not _HAS_FASTAPI:
+        raise ImportError(
+            "FastAPI and uvicorn are required for the unified server. "
+            "Install them with: pip install fastapi uvicorn"
+        )
+
+    repo = _resolve_gcc_repo(gcc_path)
+
+    env = dict(os.environ)
+    if repo is not None:
+        repo_path = _repo_path(repo)
+        if repo_path is not None:
+            env["DEVTORCH_GCC_PATH"] = str(repo_path)
+    elif gcc_path is not None:
+        env["DEVTORCH_GCC_PATH"] = str(gcc_path)
+
+    mcp_cmd = [sys.executable, "-m", "devtorch_core.mcp.server"]
+    mcp_process = subprocess.Popen(
+        mcp_cmd,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+    )
+
+    app = build_app(gcc_repo=repo, mcp_process=mcp_process)
+
+    print(f"DevTorch unified server listening on http://{host}:{port}")
+    print(f"  Proxy:      http://{host}:{port}/proxy")
+    print(f"  Dashboard:  http://{host}:{port}/dashboard")
+    print(f"  Broadcast:  http://{host}:{port}/broadcast")
+    print(f"  MCP (stdio): spawned pid={mcp_process.pid}")
+
+    try:
+        uvicorn.run(app, host=host, port=port, log_level="warning")
+    finally:
+        if mcp_process.poll() is None:
+            mcp_process.terminate()
+            try:
+                mcp_process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                mcp_process.kill()
+                mcp_process.wait()
+
+
+# ---------------------------------------------------------------------------
+# CLI helper (for later integration in devtorch_cli/main.py)
+# ---------------------------------------------------------------------------
+
+
+def cmd_serve(args: Any) -> int:
+    """
+    Adapter to call `serve_all` from the CLI argument parser.
+
+    Expected attributes on `args`:
+        - host (str)
+        - port (int)
+        - gcc_path (Optional[str])
+    Missing attributes fall back to defaults.
+    """
+    host = getattr(args, "host", DEFAULT_HOST)
+    port = int(getattr(args, "port", DEFAULT_PORT))
+    gcc_path = getattr(args, "gcc_path", None)
+    serve_all(host=host, port=port, gcc_path=gcc_path)
+    return 0

devtorch_core/session/__init__.py

@@ -0,0 +1,39 @@
+"""Multi-agent session support: planning, disagreement resolution, and what-if simulation."""
+
+from .models import (
+    ACTIVE,
+    COMPLETED,
+    FAILED,
+    PENDING,
+    PAUSED,
+    PLANNING,
+    AgentAssignment,
+    Session,
+    SessionStatus,
+    Subtask,
+    is_terminal_status,
+)
+from .orchestrator import SessionOrchestrator
+from .planner import SubtaskPlanner
+from .disagreement import DisagreementRecord, DisagreementResolver
+from .simulator import SimulationResult, WhatIfSimulator
+
+__all__ = [
+    "SessionStatus",
+    "PENDING",
+    "PLANNING",
+    "ACTIVE",
+    "PAUSED",
+    "COMPLETED",
+    "FAILED",
+    "AgentAssignment",
+    "Subtask",
+    "Session",
+    "is_terminal_status",
+    "SessionOrchestrator",
+    "SubtaskPlanner",
+    "DisagreementRecord",
+    "DisagreementResolver",
+    "SimulationResult",
+    "WhatIfSimulator",
+]