remembr-proof 0.3.0__py3-none-any.whl

remembr_proof/__init__.py

@@ -0,0 +1,116 @@
+"""REMEMBR Proof Seal — Python SDK
+
+Verify AI reasoning chains with a single function call.
+
+Usage:
+    from remembr_proof import ProofSeal
+
+    seal = ProofSeal(api_key="rp_live_...")
+    cert = seal.verify(
+        output="AI's final answer",
+        reasoning_steps=[
+            {"role": "assistant", "content": "Step 1...", "confidence": 0.9},
+            {"role": "assistant", "content": "Step 2...", "confidence": 0.85},
+        ]
+    )
+
+    print(cert.verdict)       # "verified" | "contradictions_found" | ...
+    print(cert.confidence)    # 0.0 - 1.0
+    print(cert.contradictions)  # list of contradiction reports
+"""
+
+from .client import (
+    ProofSeal,
+    ProofCertificate,
+    Contradiction,
+    InsufficientEvidenceReason,
+    INSUFFICIENT_EVIDENCE_REASONS,
+    PolicyRejectionReason,
+    POLICY_REJECTION_REASONS,
+    ReasoningIntegrity,
+    ShadowReasoningIntegrity,
+    ShadowStats,
+    ShadowUnsupportedClaim,
+    ShadowContradiction,
+    ShadowLineage,
+    ShadowLineageTraceNode,
+    UnsupportedClaim,
+    ContradictionPair,
+    VerificationError,
+    is_insufficient_evidence_reason,
+    is_policy_rejection_reason,
+)
+from .middleware import VerifiedResponse, with_proof_seal
+from .logging import configure as configure_logging, get_logger
+from .agents import VerifiedAgent, VerifiedAgentResult
+from .orchestrator import Orchestrator, OrchestratorResult, StageResult
+from .selfdialogue import SelfDialogue, SelfDialogueResult, RoundResult
+from .automation import BatchVerifier, BatchResult, RetryVerifier, ScheduledVerifier
+from .watchdog import Watchdog, WatchdogStatus
+from .remembr import Remembr, MemoryEntry
+from .perplexity import PerplexityClient, VerifiedSearch, SearchResult, VerifiedSearchResult, Citation
+from .computer import CodeRunner, VerifiedCodeRunner, ExecutionOutput, VerifiedExecutionResult
+from .onyx import OnyxClient, VerifiedSpeaker, SpeechResult, VerifiedSpeechResult, SpeechRejectedError
+from .upgrade import UpgradeInfo, check_for_upgrade
+from .synthesis import AdversarialSynthesis, SynthesisResult
+
+__version__ = "0.3.0"
+__all__ = [
+    "ProofSeal",
+    "ProofCertificate",
+    "Contradiction",
+    "InsufficientEvidenceReason",
+    "INSUFFICIENT_EVIDENCE_REASONS",
+    "PolicyRejectionReason",
+    "POLICY_REJECTION_REASONS",
+    "ReasoningIntegrity",
+    "ShadowReasoningIntegrity",
+    "ShadowStats",
+    "ShadowUnsupportedClaim",
+    "ShadowContradiction",
+    "ShadowLineage",
+    "ShadowLineageTraceNode",
+    "UnsupportedClaim",
+    "ContradictionPair",
+    "VerificationError",
+    "is_insufficient_evidence_reason",
+    "is_policy_rejection_reason",
+    "VerifiedResponse",
+    "with_proof_seal",
+    "configure_logging",
+    "get_logger",
+    "VerifiedAgent",
+    "VerifiedAgentResult",
+    "Orchestrator",
+    "OrchestratorResult",
+    "StageResult",
+    "SelfDialogue",
+    "SelfDialogueResult",
+    "RoundResult",
+    "BatchVerifier",
+    "BatchResult",
+    "RetryVerifier",
+    "ScheduledVerifier",
+    "Watchdog",
+    "WatchdogStatus",
+    "Remembr",
+    "MemoryEntry",
+    "PerplexityClient",
+    "VerifiedSearch",
+    "SearchResult",
+    "VerifiedSearchResult",
+    "Citation",
+    "CodeRunner",
+    "VerifiedCodeRunner",
+    "ExecutionOutput",
+    "VerifiedExecutionResult",
+    "OnyxClient",
+    "VerifiedSpeaker",
+    "SpeechResult",
+    "VerifiedSpeechResult",
+    "SpeechRejectedError",
+    "UpgradeInfo",
+    "check_for_upgrade",
+    "AdversarialSynthesis",
+    "SynthesisResult",
+]

remembr_proof/agents.py

@@ -0,0 +1,262 @@
+"""OpenAI Agents SDK integration for remembr_proof.
+
+Wraps any OpenAI Agents SDK ``Agent`` with automatic Proof Seal verification.
+The ``openai-agents`` package is a soft dependency — import errors are raised
+only when you actually call ``VerifiedAgent.run*``.
+
+Usage::
+
+    from agents import Agent, function_tool
+    from remembr_proof import ProofSeal
+    from remembr_proof.agents import VerifiedAgent
+
+    @function_tool
+    def lookup(query: str) -> str:
+        \"\"\"Look up information.\"\"\"
+        return "result"
+
+    agent = Agent(name="Researcher", tools=[lookup])
+    seal  = ProofSeal(api_key="rp_live_...")
+    va    = VerifiedAgent(agent, seal)
+
+    result = va.run_sync("What is the capital of France?")
+    print(result.final_output)
+    print(result.certificate.verdict)   # "verified" | ...
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from typing import TYPE_CHECKING, Any, Optional
+
+from .client import ProofCertificate, ProofSeal
+from .logging import get_logger
+
+if TYPE_CHECKING:
+    from agents import Agent, RunResult
+
+log = get_logger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Result container
+# ---------------------------------------------------------------------------
+
+@dataclass
+class VerifiedAgentResult:
+    """Agent run output paired with its Proof Seal certificate."""
+
+    run_result: "RunResult"
+    certificate: ProofCertificate
+
+    @property
+    def final_output(self) -> Any:
+        return self.run_result.final_output
+
+    @property
+    def is_verified(self) -> bool:
+        return self.certificate.is_verified
+
+    @property
+    def last_agent(self) -> "Agent":
+        return self.run_result.last_agent
+
+
+# ---------------------------------------------------------------------------
+# VerifiedAgent wrapper
+# ---------------------------------------------------------------------------
+
+class VerifiedAgent:
+    """Run an OpenAI Agents SDK agent and verify its output with Proof Seal.
+
+    Args:
+        agent: An ``agents.Agent`` instance (from the openai-agents package).
+        proof_seal: An authenticated ``ProofSeal`` client.
+        task_type: Optional workflow category forwarded to the Proof Seal API
+            (e.g. ``"general"``, ``"support_qa"``, ``"finance_ops"``).
+        metadata: Extra key/value pairs merged into the verification request's
+            metadata field alongside ``agent_name``.
+        shadow_extraction: When ``True``, request the shadow extractor report
+            without affecting the primary verdict.
+        policy: Optional verification policy thresholds (see
+            ``ProofSeal.verify`` docs).
+    """
+
+    def __init__(
+        self,
+        agent: "Agent",
+        proof_seal: ProofSeal,
+        *,
+        task_type: Optional[str] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        shadow_extraction: bool = False,
+        policy: Optional[dict[str, Any]] = None,
+    ) -> None:
+        self._agent = agent
+        self._proof_seal = proof_seal
+        self._task_type = task_type
+        self._metadata = metadata or {}
+        self._shadow_extraction = shadow_extraction
+        self._policy = policy
+
+    # -- public API ----------------------------------------------------------
+
+    def run_sync(self, input: str, **runner_kwargs: Any) -> VerifiedAgentResult:
+        """Run the agent synchronously, then verify the output.
+
+        Args:
+            input: The user prompt / task description.
+            **runner_kwargs: Forwarded verbatim to ``Runner.run_sync()``.
+        """
+        Runner = _import_runner()
+        log.debug("running agent", extra={"agent": self._agent.name, "async": False})
+        run_result = Runner.run_sync(self._agent, input, **runner_kwargs)
+        return self._build_result(run_result)
+
+    async def run(self, input: str, **runner_kwargs: Any) -> VerifiedAgentResult:
+        """Run the agent asynchronously, then verify the output.
+
+        Args:
+            input: The user prompt / task description.
+            **runner_kwargs: Forwarded verbatim to ``Runner.run()``.
+        """
+        Runner = _import_runner()
+        log.debug("running agent", extra={"agent": self._agent.name, "async": True})
+        run_result = await Runner.run(self._agent, input, **runner_kwargs)
+        return self._build_result(run_result)
+
+    # -- internals -----------------------------------------------------------
+
+    def _build_result(self, run_result: "RunResult") -> VerifiedAgentResult:
+        final_output = _stringify_output(getattr(run_result, "final_output", ""))
+
+        reasoning_steps, tool_calls = _extract_trace(run_result)
+
+        log.debug(
+            "verifying output",
+            extra={
+                "agent": self._agent.name,
+                "reasoning_steps": len(reasoning_steps),
+                "tool_calls": len(tool_calls),
+            },
+        )
+
+        certificate = self._proof_seal.verify(
+            output=final_output,
+            reasoning_steps=reasoning_steps or None,
+            tool_calls=tool_calls or None,
+            task_type=self._task_type,
+            metadata={"agent_name": self._agent.name, "sdk": "openai-agents", **self._metadata},
+            policy=self._policy,
+            shadow_extraction=self._shadow_extraction,
+        )
+
+        log.info(
+            "verification complete",
+            extra={"verdict": certificate.verdict, "confidence": certificate.confidence},
+        )
+        return VerifiedAgentResult(run_result=run_result, certificate=certificate)
+
+
+# ---------------------------------------------------------------------------
+# Trace extraction
+# ---------------------------------------------------------------------------
+
+def _extract_trace(
+    run_result: "RunResult",
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Map ``RunResult.new_items`` to Proof Seal reasoning_steps and tool_calls."""
+    reasoning_steps: list[dict[str, Any]] = []
+    tool_calls: list[dict[str, Any]] = []
+
+    for item in getattr(run_result, "new_items", []):
+        item_type = type(item).__name__
+
+        if item_type in ("MessageOutputItem", "AgentOutputItem"):
+            text = _item_text(item)
+            if text:
+                reasoning_steps.append({"role": "assistant", "content": text})
+
+        elif item_type == "ToolCallItem":
+            tool_calls.append({
+                "name": _item_name(item),
+                "status": "skipped",
+            })
+
+        elif item_type == "ToolCallOutputItem":
+            output = _item_text(item)
+            target = tool_calls[-1] if tool_calls else None
+            if target is None:
+                target = {"name": _item_name(item), "status": "skipped"}
+                tool_calls.append(target)
+            target["output_summary"] = (output or "")[:500]
+            target["status"] = "success" if output else "skipped"
+
+        elif item_type == "HandoffOutputItem":
+            target = getattr(item, "target_agent", None)
+            label = getattr(target, "name", str(target)) if target else "agent"
+            reasoning_steps.append({
+                "role": "assistant",
+                "content": f"[handoff -> {label}]",
+            })
+
+    return reasoning_steps, tool_calls
+
+
+def _stringify_output(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False, sort_keys=True)
+    return str(value)
+
+
+def _item_name(item: Any) -> str:
+    for attr in ("name", "tool_name"):
+        val = getattr(item, attr, None)
+        if isinstance(val, str) and val:
+            return val
+
+    raw_item = getattr(item, "raw_item", None)
+    for candidate in (raw_item, getattr(raw_item, "function", None)):
+        val = getattr(candidate, "name", None)
+        if isinstance(val, str) and val:
+            return val
+
+    return type(item).__name__
+
+
+def _item_text(item: Any) -> str:
+    """Best-effort text extraction from a RunItem."""
+    for attr in ("text", "output", "content"):
+        val = getattr(item, attr, None)
+        if isinstance(val, str) and val:
+            return val
+        if isinstance(val, dict):
+            text = val.get("text") or val.get("content") or val.get("output")
+            if isinstance(text, str) and text:
+                return text
+            return json.dumps(val, ensure_ascii=False, sort_keys=True)
+        if isinstance(val, list):
+            parts = [
+                p.get("text", p.get("content", "")) if isinstance(p, dict) else str(p)
+                for p in val
+            ]
+            joined = " ".join(p for p in parts if p)
+            if joined:
+                return joined
+    return ""
+
+
+def _import_runner() -> Any:
+    try:
+        from agents import Runner  # type: ignore[import-untyped]
+        return Runner
+    except ImportError as exc:
+        raise ImportError(
+            "openai-agents is required to use VerifiedAgent: "
+            "pip install openai-agents"
+        ) from exc