crprotocol 2.0.0__py3-none-any.whl

crp/resources/resource_manager.py

@@ -0,0 +1,262 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Centralized resource manager — memory tracking, model registry, pressure (§audit R1).
+
+Tracks memory consumption, ML model lifecycle, session budgets,
+and provides pressure signals for adaptive dispatch behavior.
+
+Pressure levels:
+    "none"     : usage < 50% of budget → normal operation
+    "low"      : 50-70% → compaction eligible
+    "medium"   : 70-85% → aggressive compaction, idle model unload
+    "high"     : 85-95% → forced compaction, model unload, GC
+    "critical" : >95% → emergency cleanup, session pruning
+"""
+
+from __future__ import annotations
+
+import gc
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Budget defaults
+# ---------------------------------------------------------------------------
+
+DEFAULT_MEMORY_BUDGET_MB = 512
+PRESSURE_THRESHOLDS: list[tuple[str, float]] = [
+    ("critical", 0.95),
+    ("high", 0.85),
+    ("medium", 0.70),
+    ("low", 0.50),
+    ("none", 0.0),
+]
+
+# Estimated per-model memory footprint (MB).
+MODEL_ESTIMATES: dict[str, float] = {
+    "sentence-transformers": 150.0,
+    "cross-encoder": 200.0,
+    "gliner": 200.0,
+    "uie": 400.0,
+    "hnsw-index": 50.0,  # varies with fact count
+}
+
+# Average bytes per fact in warm store (empirical).
+_BYTES_PER_FACT = 500
+
+
+@dataclass
+class ResourceSnapshot:
+    """Point-in-time resource utilization snapshot."""
+
+    timestamp: float = 0.0
+    process_rss_mb: float = 0.0
+    crp_estimated_mb: float = 0.0
+    model_memory_mb: float = 0.0
+    fact_store_mb: float = 0.0
+    budget_mb: float = DEFAULT_MEMORY_BUDGET_MB
+    pressure_level: str = "none"
+    models_loaded: list[str] = field(default_factory=list)
+    fact_count: int = 0
+    session_count: int = 0
+
+    @property
+    def utilization_ratio(self) -> float:
+        if self.budget_mb <= 0:
+            return 0.0
+        return self.crp_estimated_mb / self.budget_mb
+
+
+@dataclass
+class ModelEntry:
+    """Registered ML model with lifecycle tracking."""
+
+    name: str
+    estimated_mb: float
+    loaded_at: float = 0.0
+    last_used_at: float = 0.0
+    use_count: int = 0
+    is_loaded: bool = False
+
+
+class ResourceManager:
+    """Centralized resource tracking and pressure management.
+
+    Usage::
+
+        rm = ResourceManager(budget_mb=512)
+        rm.register_model("sentence-transformers", 150)
+        rm.mark_model_loaded("sentence-transformers")
+        snap = rm.snapshot()
+        print(snap.pressure_level)
+    """
+
+    def __init__(self, budget_mb: float = DEFAULT_MEMORY_BUDGET_MB) -> None:
+        self._budget_mb = budget_mb
+        self._models: dict[str, ModelEntry] = {}
+        self._fact_count = 0
+        self._session_count = 0
+        self._created_at = time.time()
+        self._last_gc = 0.0
+        self._cleanup_count = 0
+
+    # -- Model lifecycle ---------------------------------------------------
+
+    def register_model(self, name: str, estimated_mb: float) -> None:
+        """Register an ML model (call at init, before loading)."""
+        self._models[name] = ModelEntry(name=name, estimated_mb=estimated_mb)
+
+    def mark_model_loaded(self, name: str) -> None:
+        """Mark a model as loaded into memory."""
+        if name in self._models:
+            self._models[name].is_loaded = True
+            self._models[name].loaded_at = time.time()
+            self._models[name].last_used_at = time.time()
+
+    def mark_model_used(self, name: str) -> None:
+        """Record model usage (resets idle timer)."""
+        if name in self._models:
+            self._models[name].last_used_at = time.time()
+            self._models[name].use_count += 1
+
+    def mark_model_unloaded(self, name: str) -> None:
+        """Mark a model as unloaded from memory."""
+        if name in self._models:
+            self._models[name].is_loaded = False
+
+    # -- Fact store tracking -----------------------------------------------
+
+    def update_fact_count(self, count: int) -> None:
+        self._fact_count = count
+
+    def update_session_count(self, count: int) -> None:
+        self._session_count = count
+
+    # -- Snapshot & pressure -----------------------------------------------
+
+    def snapshot(self) -> ResourceSnapshot:
+        """Take a point-in-time resource snapshot."""
+        model_mb = sum(m.estimated_mb for m in self._models.values() if m.is_loaded)
+        fact_mb = self._fact_count * _BYTES_PER_FACT / (1024 * 1024)
+        crp_mb = model_mb + fact_mb
+
+        rss_mb = _get_process_rss_mb()
+        pressure = self._compute_pressure(crp_mb)
+        loaded = [m.name for m in self._models.values() if m.is_loaded]
+
+        return ResourceSnapshot(
+            timestamp=time.time(),
+            process_rss_mb=round(rss_mb, 1),
+            crp_estimated_mb=round(crp_mb, 1),
+            model_memory_mb=round(model_mb, 1),
+            fact_store_mb=round(fact_mb, 3),
+            budget_mb=self._budget_mb,
+            pressure_level=pressure,
+            models_loaded=loaded,
+            fact_count=self._fact_count,
+            session_count=self._session_count,
+        )
+
+    def _compute_pressure(self, crp_mb: float) -> str:
+        if self._budget_mb <= 0:
+            return "none"
+        ratio = crp_mb / self._budget_mb
+        for name, threshold in PRESSURE_THRESHOLDS:
+            if ratio >= threshold:
+                return name
+        return "none"
+
+    # -- Cleanup actions ---------------------------------------------------
+
+    def should_cleanup(self) -> bool:
+        snap = self.snapshot()
+        return snap.pressure_level in ("medium", "high", "critical")
+
+    def run_gc(self) -> int:
+        collected = gc.collect()
+        self._last_gc = time.time()
+        self._cleanup_count += 1
+        logger.debug("GC collected %d objects (run #%d)", collected, self._cleanup_count)
+        return collected
+
+    def get_idle_models(self, idle_seconds: float = 300.0) -> list[str]:
+        now = time.time()
+        return [
+            m.name for m in self._models.values()
+            if m.is_loaded and (now - m.last_used_at) > idle_seconds
+        ]
+
+    def mark_unloaded(self, model_name: str) -> None:
+        """Mark a model as unloaded (freed from memory)."""
+        if model_name in self._models:
+            self._models[model_name].is_loaded = False
+            logger.info("Model marked unloaded: %s", model_name)
+
+    def trigger_gc(self) -> int:
+        """Run GC if pressure warrants it (alias for should_cleanup + run_gc)."""
+        if self.should_cleanup():
+            return self.run_gc()
+        return 0
+
+    # -- Summary -----------------------------------------------------------
+
+    def summary(self) -> dict:
+        snap = self.snapshot()
+        return {
+            "budget_mb": self._budget_mb,
+            "crp_estimated_mb": snap.crp_estimated_mb,
+            "model_memory_mb": snap.model_memory_mb,
+            "fact_store_mb": snap.fact_store_mb,
+            "process_rss_mb": snap.process_rss_mb,
+            "pressure_level": snap.pressure_level,
+            "utilization_pct": round(snap.utilization_ratio * 100, 1),
+            "models_loaded": snap.models_loaded,
+            "fact_count": snap.fact_count,
+            "gc_runs": self._cleanup_count,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _get_process_rss_mb() -> float:
+    """Get process RSS in MB (best-effort, returns 0 on failure)."""
+    try:
+        if os.name == "nt":
+            import ctypes
+            import ctypes.wintypes
+
+            class PROCESS_MEMORY_COUNTERS(ctypes.Structure):
+                _fields_ = [
+                    ("cb", ctypes.wintypes.DWORD),
+                    ("PageFaultCount", ctypes.wintypes.DWORD),
+                    ("PeakWorkingSetSize", ctypes.c_size_t),
+                    ("WorkingSetSize", ctypes.c_size_t),
+                    ("QuotaPeakPagedPoolUsage", ctypes.c_size_t),
+                    ("QuotaPagedPoolUsage", ctypes.c_size_t),
+                    ("QuotaPeakNonPagedPoolUsage", ctypes.c_size_t),
+                    ("QuotaNonPagedPoolUsage", ctypes.c_size_t),
+                    ("PagefileUsage", ctypes.c_size_t),
+                    ("PeakPagefileUsage", ctypes.c_size_t),
+                ]
+
+            pmc = PROCESS_MEMORY_COUNTERS()
+            pmc.cb = ctypes.sizeof(pmc)
+            kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+            handle = kernel32.GetCurrentProcess()
+            psapi = ctypes.windll.psapi  # type: ignore[attr-defined]
+            if psapi.GetProcessMemoryInfo(handle, ctypes.byref(pmc), pmc.cb):
+                return pmc.WorkingSetSize / (1024 * 1024)
+        else:
+            with open("/proc/self/status") as f:
+                for line in f:
+                    if line.startswith("VmRSS:"):
+                        return int(line.split()[1]) / 1024
+    except Exception:
+        pass
+    return 0.0

crp/schemas/__init__.py

@@ -0,0 +1,20 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""JSON Schema loader for CRP data contracts."""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+from typing import Any
+
+
+def load_schema(name: str) -> dict[str, Any]:
+    """Load a JSON Schema by name (without .json extension).
+
+    >>> schema = load_schema("task-intent")
+    >>> schema["type"]
+    'object'
+    """
+    ref = resources.files("crp.schemas").joinpath(f"{name}.json")
+    return json.loads(ref.read_text(encoding="utf-8"))  # type: ignore[arg-type]

crp/schemas/cost-estimate.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CostEstimate",
+  "description": "Returned by estimate_session(). Provides pre-flight cost estimation without performing any LLM calls.",
+  "type": "object",
+  "required": ["estimated_windows", "estimated_input_tokens", "estimated_output_tokens"],
+  "properties": {
+    "estimated_windows": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Estimated total windows (dispatches + continuations)."
+    },
+    "estimated_input_tokens": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Estimated cumulative input tokens across all windows."
+    },
+    "estimated_output_tokens": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Estimated cumulative output tokens across all windows."
+    },
+    "estimated_cost_usd": {
+      "type": ["number", "null"],
+      "description": "Estimated cost in USD. NULL if provider pricing not supplied."
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["high", "medium", "low"],
+      "description": "Estimation confidence. 'high' = known task pattern, 'low' = novel task."
+    }
+  }
+}

crp/schemas/crp-error.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CRPError",
+  "description": "Standard error format for all CRP operations. Error codes are inspired by JSON-RPC 2.0 and gRPC status codes.",
+  "type": "object",
+  "required": ["code", "message", "details"],
+  "properties": {
+    "code": {
+      "type": "integer",
+      "minimum": 1001,
+      "maximum": 1031,
+      "description": "Error code from the CRP error taxonomy (§6.10.4). Range: 1001-1031."
+    },
+    "message": {
+      "type": "string",
+      "description": "Human-readable error description."
+    },
+    "details": {
+      "type": "object",
+      "description": "Error-specific structured diagnostic data."
+    }
+  },
+  "$defs": {
+    "ErrorCodes": {
+      "description": "CRP error code reference",
+      "enum": [
+        { "const": 1001, "title": "BudgetExhaustedError", "description": "Any cost cap (windows, tokens, rate) exceeded" },
+        { "const": 1002, "title": "RateLimitExceeded", "description": "Per-session rate limit hit" },
+        { "const": 1003, "title": "SessionExpired", "description": "Session timeout reached" },
+        { "const": 1004, "title": "SessionLimitExceeded", "description": "Max concurrent sessions reached" },
+        { "const": 1005, "title": "SessionClosed", "description": "Operation on closed session" },
+        { "const": 1010, "title": "ValidationError", "description": "Structural validation failure (§22.3.1)" },
+        { "const": 1011, "title": "SecurityInvariantError", "description": "Attempted violation of security invariant" },
+        { "const": 1012, "title": "SignatureInvalid", "description": "Request HMAC signature verification failed" },
+        { "const": 1013, "title": "RBACDenied", "description": "Operation not permitted for current role" },
+        { "const": 1020, "title": "ProviderError", "description": "LLM provider returned an error" },
+        { "const": 1021, "title": "ProviderTimeout", "description": "LLM provider did not respond within timeout" },
+        { "const": 1030, "title": "StateCorrupted", "description": "Cold state integrity verification failed" },
+        { "const": 1031, "title": "ChainVerificationFailed", "description": "Fact chain signature verification failed" }
+      ]
+    }
+  }
+}

crp/schemas/envelope-preview.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "EnvelopePreview",
+  "description": "Returned by preview_envelope(). Inspect what the envelope would contain without dispatching.",
+  "type": "object",
+  "required": ["total_tokens", "envelope_tokens", "facts_included", "saturation"],
+  "properties": {
+    "total_tokens": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total tokens (system_prompt + envelope + task_input + generation_reserve)."
+    },
+    "envelope_tokens": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Tokens consumed by the envelope content."
+    },
+    "generation_reserve": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Tokens reserved for LLM generation output."
+    },
+    "facts_included": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of facts included in the envelope."
+    },
+    "facts_available": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total facts available in warm + cold state."
+    },
+    "saturation": {
+      "type": "number",
+      "minimum": 0.0,
+      "maximum": 1.0,
+      "description": "Fraction of available envelope space used (0.0–1.0)."
+    }
+  }
+}

crp/schemas/persisted-state-header.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "PersistedStateHeader",
+  "description": "Header for all persisted CRP data structures (cold state, event log, exported state). Enables schema migration across versions.",
+  "type": "object",
+  "required": ["schema_version", "protocol_version", "created_at", "checksum"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "SemVer for the persisted format (e.g., '2.0.0'). Implementations MUST read state from the same Major version."
+    },
+    "protocol_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "CRP protocol version that wrote this state."
+    },
+    "created_at": {
+      "type": "number",
+      "description": "Timestamp of state creation (seconds since epoch)."
+    },
+    "checksum": {
+      "type": "string",
+      "description": "BLAKE3 integrity hash of the payload. If verification fails, implementations MUST raise StateCorrupted (code 1030)."
+    }
+  }
+}

crp/schemas/quality-report.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "QualityReport",
+  "description": "Returned by dispatch() alongside the LLM output. MUST always be provided.",
+  "type": "object",
+  "required": ["session_id", "window_id", "output", "facts_extracted", "security_flags"],
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "UUID v4 identifying the session. MUST be stable across all windows in a session."
+    },
+    "window_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "UUID v4 identifying this specific window invocation."
+    },
+    "output": {
+      "type": "string",
+      "description": "The complete, unmodified LLM output (Axiom 9 — Output Integrity). MUST NOT be filtered, summarized, or truncated by CRP."
+    },
+    "facts_extracted": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of facts extracted from this window's output."
+    },
+    "continuation_windows": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of continuation windows triggered (0 if output fit in one window)."
+    },
+    "envelope_saturation": {
+      "type": "number",
+      "minimum": 0.0,
+      "maximum": 1.0,
+      "description": "Fraction of available envelope space used (0.0–1.0). SHOULD be > 0.9 for non-trivial tasks."
+    },
+    "quality_tier": {
+      "type": "string",
+      "enum": ["S", "A", "B", "C", "D"],
+      "description": "CRP quality tier for this task based on window count (§10)."
+    },
+    "security_flags": {
+      "$ref": "#/$defs/SecurityFlags",
+      "description": "Security observations for this window. MUST always be present."
+    },
+    "telemetry": {
+      "type": ["object", "null"],
+      "description": "Performance telemetry. MAY be omitted if telemetry is disabled."
+    }
+  },
+  "$defs": {
+    "SecurityFlags": {
+      "type": "object",
+      "properties": {
+        "injection_markers_detected": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Count of injection pattern matches detected in input."
+        },
+        "injection_marker_details": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "offset": { "type": "integer", "description": "Character offset of the match." },
+              "pattern_name": { "type": "string", "description": "Name of the matched injection pattern." },
+              "matched_text": { "type": "string", "description": "The text that matched the pattern." }
+            }
+          },
+          "description": "Details of each injection pattern match."
+        },
+        "unicode_normalized": {
+          "type": "boolean",
+          "description": "Whether Unicode normalization was applied to input."
+        },
+        "control_chars_stripped": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Count of control characters removed from input."
+        },
+        "input_truncated": {
+          "type": "boolean",
+          "description": "Whether input was truncated to fit max_task_input_bytes."
+        },
+        "integrity_violations": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Count of fact integrity chain verification failures."
+        }
+      }
+    }
+  }
+}

crp/schemas/session-handle.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "SessionHandle",
+  "description": "Returned by init(). Note: session_key is NEVER included in JSON serialization — it exists only in memory.",
+  "type": "object",
+  "required": ["session_id", "protocol_version", "capabilities", "created_at", "expires_at"],
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "UUID v4 — unique per session."
+    },
+    "protocol_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "SemVer protocol version (e.g., '2.0.0')."
+    },
+    "capabilities": {
+      "type": "array",
+      "items": { "type": "string" },
+      "uniqueItems": true,
+      "description": "Granted RBAC permissions (e.g., 'dispatch', 'configure', 'session_status')."
+    },
+    "created_at": {
+      "type": "number",
+      "description": "Monotonic timestamp (seconds since epoch) of session creation."
+    },
+    "expires_at": {
+      "type": "number",
+      "description": "Session expiry timestamp (seconds since epoch)."
+    }
+  }
+}

crp/schemas/session-status.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "SessionStatus",
+  "description": "Returned by session_status(). MUST always be available for OBSERVER role or above.",
+  "type": "object",
+  "required": ["session_id", "windows_completed", "total_input_tokens", "total_output_tokens", "facts_in_warm_state", "overhead_ratio"],
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "UUID v4 identifying the session."
+    },
+    "windows_completed": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total windows completed in this session (including continuations)."
+    },
+    "total_input_tokens": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Cumulative input tokens sent to the LLM across all windows."
+    },
+    "total_output_tokens": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Cumulative output tokens received from the LLM across all windows."
+    },
+    "facts_in_warm_state": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Current fact count in warm state (Tier 2)."
+    },
+    "overhead_ratio": {
+      "type": "number",
+      "minimum": 0.0,
+      "description": "Current overhead windows / productive windows ratio."
+    },
+    "remaining_budget": {
+      "type": ["object", "null"],
+      "description": "Remaining budget against cost caps. NULL if no caps set.",
+      "properties": {
+        "windows_remaining": {
+          "type": ["integer", "null"],
+          "description": "Windows remaining before max_windows_per_session cap."
+        },
+        "input_tokens_remaining": {
+          "type": ["integer", "null"],
+          "description": "Input tokens remaining before max_total_input_tokens cap."
+        },
+        "output_tokens_remaining": {
+          "type": ["integer", "null"],
+          "description": "Output tokens remaining before max_total_output_tokens cap."
+        }
+      }
+    }
+  }
+}

crp/schemas/stream-event.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "StreamEvent",
+  "description": "Events emitted by dispatch_stream(). The stream MUST emit exactly one 'done' event as the final event (or one 'error').",
+  "type": "object",
+  "required": ["event_type", "data"],
+  "properties": {
+    "event_type": {
+      "type": "string",
+      "enum": ["token", "extraction", "continuation", "window_complete", "done", "error"],
+      "description": "Discriminator for the event type. Concatenating all 'token' data values MUST produce the same string as non-streaming dispatch() output."
+    },
+    "data": {
+      "description": "Event payload. Type depends on event_type: token=string, extraction=ExtractionProgress, continuation=ContinuationInfo, window_complete=WindowSummary, done=QualityReport, error=CRPError."
+    }
+  },
+  "discriminator": { "propertyName": "event_type" }
+}