proseforge-agent 0.2.0__py3-none-any.whl

proseforge_agent/agent/audit.py

@@ -0,0 +1,198 @@
+"""Agent audit trail recording, export, and replay."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from ..chat.transcript import append_jsonl, read_jsonl
+from ..errors import ConfigurationError
+
+UTC = timezone.utc
+
+
+_SENSITIVE_KEY_EXACT = {"api_key", "apikey", "token", "secret", "password", "authorization"}
+_ASSIGNMENT_RE = re.compile(r"(?i)\b(api[_-]?key|token|secret|password|authorization)=\S+")
+_SECRET_TOKEN_RE = re.compile(r"\b(?:sk|tok)-[A-Za-z0-9_-]+")
+
+
+@dataclass(frozen=True)
+class AuditStep:
+    """One recorded agent decision step."""
+
+    session_id: str
+    step: int
+    input: str = ""
+    intent: dict[str, Any] = field(default_factory=dict)
+    system_prompt_version: str = ""
+    evidence_pack: list[dict[str, Any]] = field(default_factory=list)
+    tool_choice: str = ""
+    tool_args: dict[str, Any] = field(default_factory=dict)
+    tool_result: dict[str, Any] = field(default_factory=dict)
+    provider: dict[str, Any] = field(default_factory=dict)
+    latency_ms: int = 0
+    token_usage: dict[str, Any] = field(default_factory=dict)
+    model_output: str = ""
+    final_action: str = ""
+    trace_id: str = ""
+    created_at: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class ReplayResult:
+    """Deterministic replay summary from an audit session."""
+
+    session_id: str
+    step_count: int
+    final_output: str
+    actions: list[str]
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class AuditTrailStore:
+    """Append-only per-session audit log."""
+
+    def __init__(self, root: str | Path) -> None:
+        self.root = Path(root)
+
+    def record_turn(self, session_id: str, payload: dict[str, Any]) -> AuditStep:
+        existing, _warnings = read_jsonl(self._path(session_id))
+        sanitized = _redact(payload)
+        step = AuditStep(
+            session_id=session_id,
+            step=len(existing) + 1,
+            input=str(sanitized.get("input", "")),
+            intent=dict(sanitized.get("intent") or {}),
+            system_prompt_version=str(sanitized.get("system_prompt_version", "")),
+            evidence_pack=list(sanitized.get("evidence_pack") or []),
+            tool_choice=str(sanitized.get("tool_choice", "")),
+            tool_args=dict(sanitized.get("tool_args") or {}),
+            tool_result=dict(sanitized.get("tool_result") or {}),
+            provider=dict(sanitized.get("provider") or {}),
+            latency_ms=int(sanitized.get("latency_ms") or 0),
+            token_usage=dict(sanitized.get("token_usage") or {}),
+            model_output=str(sanitized.get("model_output", "")),
+            final_action=str(sanitized.get("final_action", "")),
+            trace_id=str(sanitized.get("trace_id", "")),
+            created_at=str(sanitized.get("created_at") or datetime.now(UTC).isoformat()),
+        )
+        append_jsonl(self._path(session_id), step.to_dict())
+        return step
+
+    def list_session(self, session_id: str) -> list[AuditStep]:
+        rows, warnings = read_jsonl(self._path(session_id))
+        if warnings:
+            raise ConfigurationError("; ".join(warnings))
+        return [_step_from_dict(row) for row in rows]
+
+    def get_step(self, session_id: str, step: int) -> AuditStep:
+        for record in self.list_session(session_id):
+            if record.step == step:
+                return record
+        raise ConfigurationError(f"audit step {step} not found for session {session_id!r}")
+
+    def export_json(self, session_id: str) -> str:
+        return json.dumps(
+            [step.to_dict() for step in self.list_session(session_id)],
+            ensure_ascii=False,
+            indent=2,
+            sort_keys=True,
+        )
+
+    def export_markdown(self, session_id: str) -> str:
+        lines = [f"# Audit Session {session_id}", ""]
+        for step in self.list_session(session_id):
+            lines.extend(
+                [
+                    f"## Step {step.step}",
+                    "",
+                    f"- intent: {step.intent.get('name', '')}",
+                    f"- provider: {step.provider.get('name', '')}",
+                    f"- prompt: {step.system_prompt_version or '(unknown)'}",
+                    f"- final_action: {step.final_action or '(unknown)'}",
+                    "",
+                    "### Input",
+                    step.input or "(empty)",
+                    "",
+                    "### Output",
+                    step.model_output or "(empty)",
+                    "",
+                ]
+            )
+        return "\n".join(lines).rstrip() + "\n"
+
+    def replay(self, session_id: str) -> ReplayResult:
+        steps = self.list_session(session_id)
+        final_output = steps[-1].model_output if steps else ""
+        actions = [step.final_action or step.intent.get("name", "") for step in steps]
+        return ReplayResult(
+            session_id=session_id,
+            step_count=len(steps),
+            final_output=final_output,
+            actions=actions,
+        )
+
+    def _path(self, session_id: str) -> Path:
+        return self.root / "audit" / f"{session_id}.jsonl"
+
+
+def _step_from_dict(payload: dict[str, Any]) -> AuditStep:
+    return AuditStep(
+        session_id=str(payload.get("session_id", "")),
+        step=int(payload.get("step") or 0),
+        input=str(payload.get("input", "")),
+        intent=dict(payload.get("intent") or {}),
+        system_prompt_version=str(payload.get("system_prompt_version", "")),
+        evidence_pack=list(payload.get("evidence_pack") or []),
+        tool_choice=str(payload.get("tool_choice", "")),
+        tool_args=dict(payload.get("tool_args") or {}),
+        tool_result=dict(payload.get("tool_result") or {}),
+        provider=dict(payload.get("provider") or {}),
+        latency_ms=int(payload.get("latency_ms") or 0),
+        token_usage=dict(payload.get("token_usage") or {}),
+        model_output=str(payload.get("model_output", "")),
+        final_action=str(payload.get("final_action", "")),
+        trace_id=str(payload.get("trace_id", "")),
+        created_at=str(payload.get("created_at", "")),
+    )
+
+
+def _redact(value: Any) -> Any:
+    if isinstance(value, dict):
+        redacted: dict[str, Any] = {}
+        for key, item in value.items():
+            lowered = str(key).lower()
+            if _is_sensitive_key(lowered):
+                redacted[key] = "[redacted]"
+            else:
+                redacted[key] = _redact(item)
+        return redacted
+    if isinstance(value, list):
+        return [_redact(item) for item in value]
+    if isinstance(value, str):
+        return _SECRET_TOKEN_RE.sub("[redacted]", _ASSIGNMENT_RE.sub(lambda match: f"{match.group(1)}=[redacted]", value))
+    return value
+
+
+def _is_sensitive_key(key: str) -> bool:
+    return (
+        key in _SENSITIVE_KEY_EXACT
+        or key.endswith("_token")
+        or key.endswith("-token")
+        or key.endswith("_secret")
+        or key.endswith("-secret")
+        or key.endswith("_password")
+        or key.endswith("-password")
+    )
+
+
+__all__ = ["AuditStep", "AuditTrailStore", "ReplayResult"]

proseforge_agent/agent/context_window.py

@@ -0,0 +1,90 @@
+"""Context window token budgeting and compaction."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from ..llm import Message
+
+
+DEFAULT_PROVIDER_LIMITS = {
+    "fake": 4096,
+    "openai": 128000,
+    "anthropic": 200000,
+    "gemini": 1000000,
+}
+
+
+@dataclass(frozen=True)
+class ContextUsageReport:
+    """Token budget report before constructing a provider prompt."""
+
+    provider: str
+    max_context_tokens: int
+    prompt_tokens: int
+    evidence_tokens: int
+    reserve_tokens: int
+    evidence_budget_tokens: int
+    remaining_tokens: int
+    truncated_evidence_ids: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class ContextWindowManager:
+    """Estimate prompt usage, truncate evidence, and summarize old messages."""
+
+    def __init__(self, provider_limits: dict[str, int] | None = None) -> None:
+        self.provider_limits = {**DEFAULT_PROVIDER_LIMITS, **dict(provider_limits or {})}
+
+    def estimate_tokens(self, text: str) -> int:
+        return len(str(text).split())
+
+    def status(
+        self,
+        *,
+        provider: str,
+        messages: list[Message],
+        evidence: list[dict[str, Any]] | None = None,
+        reserve_tokens: int = 256,
+        max_context_tokens: int | None = None,
+    ) -> ContextUsageReport:
+        max_tokens = max_context_tokens or self.provider_limits.get(provider, DEFAULT_PROVIDER_LIMITS["fake"])
+        prompt_tokens = sum(self.estimate_tokens(message.content) for message in messages)
+        evidence_budget = max(0, max_tokens - prompt_tokens - reserve_tokens)
+        included_evidence = 0
+        truncated: list[str] = []
+        for item in evidence or []:
+            item_tokens = self.estimate_tokens(str(item.get("text", "")))
+            if included_evidence + item_tokens > evidence_budget:
+                truncated.append(str(item.get("id") or "evidence"))
+                continue
+            included_evidence += item_tokens
+        remaining = max(0, max_tokens - prompt_tokens - included_evidence - reserve_tokens)
+        return ContextUsageReport(
+            provider=provider,
+            max_context_tokens=max_tokens,
+            prompt_tokens=prompt_tokens,
+            evidence_tokens=included_evidence,
+            reserve_tokens=reserve_tokens,
+            evidence_budget_tokens=evidence_budget,
+            remaining_tokens=remaining,
+            truncated_evidence_ids=truncated,
+        )
+
+    def compact_messages(self, messages: list[Message], *, keep_last: int = 6) -> list[Message]:
+        if keep_last < 0:
+            keep_last = 0
+        if len(messages) <= keep_last:
+            return list(messages)
+        early = messages[: len(messages) - keep_last]
+        tail = messages[-keep_last:] if keep_last else []
+        summary_text = "summary: " + " | ".join(
+            f"{message.role}: {message.content}" for message in early
+        )
+        return [Message(role="system", content=summary_text), *tail]
+
+
+__all__ = ["ContextUsageReport", "ContextWindowManager", "DEFAULT_PROVIDER_LIMITS"]

proseforge_agent/agent/control.py

@@ -0,0 +1,45 @@
+"""Cooperative control signals for long-running agent loops."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ControlSignal:
+    """One cooperative control signal consumed at a safe point."""
+
+    kind: str
+    instruction: str = ""
+    reason: str = ""
+    trace_id: str = ""
+
+
+class ControlToken:
+    """Thread-safe enough single-process token for interrupt and steer requests."""
+
+    def __init__(self) -> None:
+        self._signal: ControlSignal | None = None
+
+    @staticmethod
+    def interrupt_signal(reason: str = "") -> ControlSignal:
+        return ControlSignal(kind="interrupt", reason=reason, trace_id=f"control-{uuid.uuid4().hex[:12]}")
+
+    @staticmethod
+    def steer_signal(instruction: str) -> ControlSignal:
+        return ControlSignal(kind="steer", instruction=instruction, trace_id=f"control-{uuid.uuid4().hex[:12]}")
+
+    def interrupt(self, reason: str = "user requested stop") -> None:
+        self._signal = self.interrupt_signal(reason)
+
+    def steer(self, instruction: str) -> None:
+        self._signal = self.steer_signal(instruction)
+
+    def poll(self) -> ControlSignal | None:
+        signal = self._signal
+        self._signal = None
+        return signal
+
+
+__all__ = ["ControlSignal", "ControlToken"]

proseforge_agent/agent/degradation.py

@@ -0,0 +1,166 @@
+"""Graceful feature degradation and runtime capability reports."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from enum import IntEnum
+from typing import Any
+
+
+class FeatureLevel(IntEnum):
+    """Ordered runtime capability levels."""
+
+    OFFLINE = 0
+    LOCAL_MODEL = 1
+    REMOTE_PROVIDER = 2
+
+    @property
+    def label(self) -> str:
+        return {
+            FeatureLevel.OFFLINE: "offline",
+            FeatureLevel.LOCAL_MODEL: "local_model",
+            FeatureLevel.REMOTE_PROVIDER: "remote_provider",
+        }[self]
+
+
+@dataclass(frozen=True)
+class FeatureDeclaration:
+    """Capability requirement for a feature."""
+
+    id: str
+    required_level: FeatureLevel
+    dependencies: list[str] = field(default_factory=list)
+    guidance: str = ""
+
+
+@dataclass(frozen=True)
+class FeatureCheck:
+    """Decision for one feature under current runtime capabilities."""
+
+    feature_id: str
+    allowed: bool
+    status: str
+    required_level: str
+    available_level: str
+    guidance: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class CapabilityReport:
+    """Runtime capability report for all declared features."""
+
+    available_level: str
+    features: dict[str, dict[str, Any]]
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+DEFAULT_FEATURES = {
+    "export_txt": FeatureDeclaration(
+        id="export_txt",
+        required_level=FeatureLevel.OFFLINE,
+        guidance="TXT/Markdown export can run offline.",
+    ),
+    "manifest_validate": FeatureDeclaration(
+        id="manifest_validate",
+        required_level=FeatureLevel.OFFLINE,
+        guidance="Manifest validation can run offline.",
+    ),
+    "keyword_search": FeatureDeclaration(
+        id="keyword_search",
+        required_level=FeatureLevel.OFFLINE,
+        guidance="Keyword search can run from local text indexes.",
+    ),
+    "stats": FeatureDeclaration(
+        id="stats",
+        required_level=FeatureLevel.OFFLINE,
+        guidance="Writing stats can run from local project files.",
+    ),
+    "backup": FeatureDeclaration(
+        id="backup",
+        required_level=FeatureLevel.OFFLINE,
+        guidance="Backups can run without provider access.",
+    ),
+    "fake_chat": FeatureDeclaration(
+        id="fake_chat",
+        required_level=FeatureLevel.OFFLINE,
+        guidance="Fake provider chat can run offline.",
+    ),
+    "rewrite": FeatureDeclaration(
+        id="rewrite",
+        required_level=FeatureLevel.LOCAL_MODEL,
+        dependencies=["provider"],
+        guidance="Rewrite requires provider capability; use fake chat or export while offline.",
+    ),
+    "cloud_sync": FeatureDeclaration(
+        id="cloud_sync",
+        required_level=FeatureLevel.REMOTE_PROVIDER,
+        dependencies=["network"],
+        guidance="Cloud sync requires network connectivity.",
+    ),
+}
+
+
+class CapabilityRuntime:
+    """Evaluate features against the current runtime capability level."""
+
+    def __init__(
+        self,
+        *,
+        available_level: FeatureLevel = FeatureLevel.OFFLINE,
+        dependencies: dict[str, bool] | None = None,
+        declarations: dict[str, FeatureDeclaration] | None = None,
+    ) -> None:
+        self.available_level = available_level
+        self.dependencies = dependencies or {}
+        self.declarations = declarations or DEFAULT_FEATURES
+
+    def check(self, feature_id: str) -> FeatureCheck:
+        declaration = self.declarations[feature_id]
+        missing = [name for name in declaration.dependencies if not self.dependencies.get(name, False)]
+        if self.available_level < declaration.required_level:
+            return FeatureCheck(
+                feature_id=feature_id,
+                allowed=False,
+                status="degraded",
+                required_level=declaration.required_level.label,
+                available_level=self.available_level.label,
+                guidance=declaration.guidance,
+            )
+        if missing:
+            return FeatureCheck(
+                feature_id=feature_id,
+                allowed=False,
+                status="degraded",
+                required_level=declaration.required_level.label,
+                available_level=self.available_level.label,
+                guidance=f"requires {', '.join(missing)}; {declaration.guidance}",
+            )
+        return FeatureCheck(
+            feature_id=feature_id,
+            allowed=True,
+            status="ok",
+            required_level=declaration.required_level.label,
+            available_level=self.available_level.label,
+            guidance=declaration.guidance,
+        )
+
+    def report(self) -> CapabilityReport:
+        return CapabilityReport(
+            available_level=self.available_level.label,
+            features={feature_id: self.check(feature_id).to_dict() for feature_id in sorted(self.declarations)},
+        )
+
+
+__all__ = [
+    "CapabilityReport",
+    "CapabilityRuntime",
+    "DEFAULT_FEATURES",
+    "FeatureCheck",
+    "FeatureDeclaration",
+    "FeatureLevel",
+]