crprotocol 2.0.0__py3-none-any.whl

crp/continuation/voice.py

@@ -0,0 +1,157 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Voice profile — tone, terminology, style extraction from first window (§04 §3.5.1)."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+
+
+@dataclass
+class VoiceProfile:
+    """Captured voice characteristics from the first generation window."""
+
+    tone: str  # e.g. "formal", "casual", "technical", "mixed"
+    avg_sentence_length: float
+    vocabulary_level: str  # "basic", "intermediate", "advanced", "technical"
+    person: str  # "first", "second", "third", "mixed"
+    active_voice_ratio: float  # 0.0–1.0
+    key_terminology: list[str]  # domain terms used
+    style_markers: dict[str, object] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "tone": self.tone,
+            "avg_sentence_length": self.avg_sentence_length,
+            "vocabulary_level": self.vocabulary_level,
+            "person": self.person,
+            "active_voice_ratio": self.active_voice_ratio,
+            "key_terminology": self.key_terminology,
+            "style_markers": self.style_markers,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> VoiceProfile:
+        return cls(
+            tone=str(data.get("tone", "neutral")),
+            avg_sentence_length=float(data.get("avg_sentence_length", 0)),  # type: ignore[arg-type]
+            vocabulary_level=str(data.get("vocabulary_level", "intermediate")),
+            person=str(data.get("person", "third")),
+            active_voice_ratio=float(data.get("active_voice_ratio", 0.5)),  # type: ignore[arg-type]
+            key_terminology=list(data.get("key_terminology", [])),  # type: ignore[call-overload]
+            style_markers=dict(data.get("style_markers", {})),  # type: ignore[call-overload]
+        )
+
+
+# ── Extraction helpers ───────────────────────────────────────────
+
+_FORMAL_MARKERS = {
+    "therefore", "consequently", "furthermore", "moreover", "nevertheless",
+    "notwithstanding", "henceforth", "whereby", "wherein", "herein",
+    "accordingly", "albeit", "hitherto", "therein",
+}
+
+_CASUAL_MARKERS = {
+    "okay", "ok", "cool", "awesome", "basically", "literally",
+    "gonna", "wanna", "kinda", "sorta", "yeah", "nope", "stuff",
+    "thing", "actually", "pretty much", "like",
+}
+
+_TECHNICAL_TERMS_PATTERN = re.compile(
+    r"\b[A-Z][a-z]+(?:[A-Z][a-z]+)+\b"  # CamelCase
+    r"|\b[a-z]+_[a-z]+\b"  # snake_case
+    r"|\b[A-Z]{2,}\b"  # ACRONYMS
+    r"|\b\w+(?:tion|ment|ness|ity|ism|ize|ify)\b"  # nominalizations
+)
+
+_PASSIVE_PATTERN = re.compile(
+    r"\b(?:is|are|was|were|be|been|being)\s+(?:\w+\s+)*?\w+(?:ed|en)\b",
+    re.IGNORECASE,
+)
+
+_FIRST_PERSON = re.compile(r"\b(?:I|me|my|mine|we|us|our|ours)\b", re.IGNORECASE)
+_SECOND_PERSON = re.compile(r"\b(?:you|your|yours)\b", re.IGNORECASE)
+_THIRD_PERSON = re.compile(r"\b(?:he|she|it|they|him|her|them|his|its|their)\b", re.IGNORECASE)
+
+
+def extract_voice_profile(text: str) -> VoiceProfile:
+    """Extract a voice profile from the first window's output (§04 §3.5.1)."""
+    words = text.lower().split()
+    word_count = max(1, len(words))
+    word_set = set(words)
+
+    sentences = [s.strip() for s in re.split(r"[.!?]+\s*", text) if s.strip()]
+    sentence_count = max(1, len(sentences))
+
+    # Tone classification
+    formal_count = len(word_set & _FORMAL_MARKERS)
+    casual_count = len(word_set & _CASUAL_MARKERS)
+    tech_matches = _TECHNICAL_TERMS_PATTERN.findall(text)
+
+    if len(tech_matches) > word_count * 0.05:
+        tone = "technical"
+    elif formal_count > casual_count:
+        tone = "formal"
+    elif casual_count > formal_count:
+        tone = "casual"
+    else:
+        tone = "neutral"
+
+    # Average sentence length
+    avg_sentence_length = word_count / sentence_count
+
+    # Vocabulary level
+    unique_ratio = len(word_set) / word_count
+    avg_word_len = sum(len(w) for w in words) / word_count
+    if avg_word_len > 7 and unique_ratio > 0.6:
+        vocabulary_level = "advanced"
+    elif avg_word_len > 5.5 or unique_ratio > 0.5:
+        vocabulary_level = "intermediate"
+    elif len(tech_matches) > 5:
+        vocabulary_level = "technical"
+    else:
+        vocabulary_level = "basic"
+
+    # Person detection
+    first = len(_FIRST_PERSON.findall(text))
+    second = len(_SECOND_PERSON.findall(text))
+    third = len(_THIRD_PERSON.findall(text))
+    total_person = first + second + third
+    if total_person == 0:
+        person = "third"
+    elif first > second and first > third:
+        person = "first"
+    elif second > first and second > third:
+        person = "second"
+    elif first > 0 and second > 0:
+        person = "mixed"
+    else:
+        person = "third"
+
+    # Active voice ratio
+    passive_count = len(_PASSIVE_PATTERN.findall(text))
+    active_ratio = 1.0 - (passive_count / sentence_count) if sentence_count > 0 else 0.5
+    active_ratio = max(0.0, min(1.0, active_ratio))
+
+    # Key terminology (most frequent technical-looking terms)
+    term_counter: Counter[str] = Counter()
+    for match in tech_matches:
+        term_counter[match] += 1
+    key_terms = [t for t, _ in term_counter.most_common(20)]
+
+    return VoiceProfile(
+        tone=tone,
+        avg_sentence_length=round(avg_sentence_length, 1),
+        vocabulary_level=vocabulary_level,
+        person=person,
+        active_voice_ratio=round(active_ratio, 2),
+        key_terminology=key_terms,
+        style_markers={
+            "formal_markers": formal_count,
+            "casual_markers": casual_count,
+            "tech_terms": len(tech_matches),
+            "unique_word_ratio": round(unique_ratio, 3),
+        },
+    )

crp/core/__init__.py

@@ -0,0 +1,69 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Core protocol — orchestrator, task intent, windows, sessions, config, errors."""
+
+from crp.core.batch import BatchResult, dispatch_batch, ingest_batch
+from crp.core.config import ConfigurationResolver, CRPConfig
+from crp.core.errors import (
+    BudgetExhaustedError,
+    CRPError,
+    ProviderError,
+    SessionClosedError,
+    SessionExpiredError,
+)
+from crp.core.idempotency import CachedResult, RequestDeduplicator, SessionLock
+from crp.core.orchestrator import (
+    CRPOrchestrator,
+    ExtractionResult,
+    StreamEvent,
+)
+from crp.core.session import (
+    CostEstimate,
+    EnvelopePreview,
+    QualityReport,
+    RemainingBudget,
+    SecurityFlags,
+    SessionHandle,
+    SessionStatus,
+)
+from crp.core.task_intent import TaskIntent
+from crp.core.window import WindowDAG, WindowMetrics, WindowNode, WindowState
+
+__all__ = [
+    # Orchestrator
+    "CRPOrchestrator",
+    "ExtractionResult",
+    "StreamEvent",
+    # Config
+    "ConfigurationResolver",
+    "CRPConfig",
+    # Session
+    "SessionHandle",
+    "SessionStatus",
+    "CostEstimate",
+    "EnvelopePreview",
+    "QualityReport",
+    "RemainingBudget",
+    "SecurityFlags",
+    # Task
+    "TaskIntent",
+    # Window
+    "WindowDAG",
+    "WindowMetrics",
+    "WindowNode",
+    "WindowState",
+    # Errors
+    "CRPError",
+    "BudgetExhaustedError",
+    "ProviderError",
+    "SessionClosedError",
+    "SessionExpiredError",
+    # Batch
+    "BatchResult",
+    "dispatch_batch",
+    "ingest_batch",
+    # Idempotency
+    "CachedResult",
+    "RequestDeduplicator",
+    "SessionLock",
+]

crp/core/batch.py

@@ -0,0 +1,77 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Batch dispatch and ingest operations (§6.6).
+
+dispatch_batch: Fan-out multiple intents in parallel.
+ingest_batch: Batch ingestion with boundary reconciliation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class BatchResult:
+    """Result for one item in a batch operation."""
+
+    index: int = 0
+    output: str = ""
+    success: bool = True
+    error: str | None = None
+    facts_extracted: int = 0
+
+
+def dispatch_batch(
+    intents: list[dict[str, str]],
+    dispatch_fn: Callable[[str, str], tuple[str, Any]] | None = None,
+) -> list[BatchResult]:
+    """Batch dispatch with sequential execution (parallel fan-out ready).
+
+    Each intent should have keys: "system_prompt", "task_input".
+    """
+    results: list[BatchResult] = []
+    for i, intent in enumerate(intents):
+        sys_prompt = intent.get("system_prompt", "")
+        task_input = intent.get("task_input", "")
+        if dispatch_fn:
+            try:
+                output, report = dispatch_fn(sys_prompt, task_input)
+                results.append(BatchResult(index=i, output=output))
+            except Exception as exc:
+                results.append(BatchResult(
+                    index=i, success=False, error=str(exc),
+                ))
+        else:
+            results.append(BatchResult(
+                index=i, output="[no dispatch_fn]",
+            ))
+    return results
+
+
+def ingest_batch(
+    texts: list[str],
+    extract_fn: Callable[[str, str], list[Any]] | None = None,
+    task_intent: str = "",
+) -> list[BatchResult]:
+    """Batch ingestion with per-item extraction.
+
+    Returns extraction results per text item.
+    """
+    results: list[BatchResult] = []
+    for i, text in enumerate(texts):
+        if extract_fn:
+            try:
+                facts = extract_fn(text, task_intent)
+                results.append(BatchResult(
+                    index=i, facts_extracted=len(facts),
+                ))
+            except Exception as exc:
+                results.append(BatchResult(
+                    index=i, success=False, error=str(exc),
+                ))
+        else:
+            results.append(BatchResult(index=i, facts_extracted=0))
+    return results

crp/core/circuit_breaker.py

@@ -0,0 +1,116 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Circuit breaker for LLM provider calls (§audit H4).
+
+Implements the CLOSED → OPEN → HALF-OPEN pattern to prevent
+cascading failures when a provider is unavailable.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from dataclasses import dataclass
+from enum import Enum
+
+logger = logging.getLogger("crp.core.circuit_breaker")
+
+
+class CircuitState(Enum):
+    CLOSED = "closed"        # Normal operation
+    OPEN = "open"            # Failing — reject calls immediately
+    HALF_OPEN = "half_open"  # Testing recovery — allow one probe call
+
+
+@dataclass
+class CircuitBreakerConfig:
+    """Configuration for the circuit breaker."""
+    failure_threshold: int = 5       # consecutive failures to trip OPEN
+    recovery_timeout: float = 30.0   # seconds before OPEN → HALF-OPEN
+    success_threshold: int = 2       # successes in HALF-OPEN to close
+
+
+class CircuitBreaker:
+    """Thread-safe circuit breaker for LLM providers."""
+
+    def __init__(self, config: CircuitBreakerConfig | None = None) -> None:
+        self._config = config or CircuitBreakerConfig()
+        self._state = CircuitState.CLOSED
+        self._failure_count = 0
+        self._success_count = 0
+        self._last_failure_time: float = 0.0
+        self._lock = threading.Lock()
+        self._half_open_probing = False  # Only allow one probe (§audit2 CB-M10)
+
+    @property
+    def state(self) -> CircuitState:
+        """Current circuit state (may transition OPEN → HALF-OPEN on read)."""
+        with self._lock:
+            if self._state == CircuitState.OPEN:
+                elapsed = time.monotonic() - self._last_failure_time
+                if elapsed >= self._config.recovery_timeout:
+                    self._state = CircuitState.HALF_OPEN
+                    self._success_count = 0
+                    self._half_open_probing = False
+                    logger.info("Circuit breaker → HALF-OPEN (recovery timeout elapsed)")
+            return self._state
+
+    def allow_request(self) -> bool:
+        """Check if a request should be allowed through."""
+        with self._lock:
+            current = self._state
+            if current == CircuitState.OPEN:
+                elapsed = time.monotonic() - self._last_failure_time
+                if elapsed >= self._config.recovery_timeout:
+                    self._state = CircuitState.HALF_OPEN
+                    self._success_count = 0
+                    self._half_open_probing = False
+                    current = CircuitState.HALF_OPEN
+            if current == CircuitState.CLOSED:
+                return True
+            if current == CircuitState.HALF_OPEN:
+                if self._half_open_probing:
+                    return False  # Only one probe at a time (§audit2 CB-M10)
+                self._half_open_probing = True
+                return True
+            return False  # OPEN — reject
+
+    def record_success(self) -> None:
+        """Record a successful call."""
+        with self._lock:
+            if self._state == CircuitState.HALF_OPEN:
+                self._success_count += 1
+                self._half_open_probing = False
+                if self._success_count >= self._config.success_threshold:
+                    self._state = CircuitState.CLOSED
+                    self._failure_count = 0
+                    logger.info("Circuit breaker → CLOSED (recovery confirmed)")
+            else:
+                self._failure_count = 0
+
+    def record_failure(self) -> None:
+        """Record a failed call."""
+        with self._lock:
+            self._failure_count += 1
+            self._last_failure_time = time.monotonic()
+
+            if self._state == CircuitState.HALF_OPEN:
+                # Single failure in half-open immediately trips back to open
+                self._state = CircuitState.OPEN
+                self._half_open_probing = False
+                logger.warning("Circuit breaker → OPEN (half-open probe failed)")
+            elif self._failure_count >= self._config.failure_threshold:
+                self._state = CircuitState.OPEN
+                logger.warning(
+                    "Circuit breaker → OPEN after %d consecutive failures",
+                    self._failure_count,
+                )
+
+    def reset(self) -> None:
+        """Reset to closed state."""
+        with self._lock:
+            self._state = CircuitState.CLOSED
+            self._failure_count = 0
+            self._success_count = 0
+            self._half_open_probing = False