petfishframework 0.1.0__py3-none-any.whl

petfishframework/core/contracts.py

@@ -0,0 +1,190 @@
+"""Core contracts — protocols that define the framework's seams.
+
+Every concrete implementation (reasoning strategies, model adapters,
+tools, MCP bridges) depends on these protocols, never the reverse.
+This is the Ports & Adapters boundary (decision 5).
+
+Dependencies: core/types.py only. No concrete imports.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Protocol, runtime_checkable
+
+from .types import (
+    Budget,
+    Message,
+    ModelRequest,
+    ModelResponse,
+    Result,
+    Snippet,
+    Task,
+    ToolRef,
+    ToolResult,
+)
+
+# ---------------------------------------------------------------------------
+# Shared enums (used by Tool definitions and permission decisions)
+# ---------------------------------------------------------------------------
+
+class RiskLevel(Enum):
+    """Risk classification for tools and actions (from agentShield-dev)."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class Clearance(Enum):
+    """Data classification levels (from agentShield-dev SARC model)."""
+
+    PUBLIC = "public"
+    INTERNAL = "internal"
+    CONFIDENTIAL = "confidential"
+    SECRET = "secret"
+
+
+# ---------------------------------------------------------------------------
+# Tool contract (decision 2 — MCP-shaped, single tool interface)
+# ---------------------------------------------------------------------------
+
+@runtime_checkable
+class Tool(Protocol):
+    """The single tool contract. MCP-shaped (decision 2).
+
+    Native Python tools are wrapped to satisfy this; external MCP servers
+    are consumed natively. No 'native vs MCP' duality.
+    """
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    risk_level: RiskLevel
+    capabilities: tuple[str, ...]  # e.g. ("network", "fs:write", "mcp:sampling")
+
+    def execute(self, args: dict[str, Any]) -> ToolResult:
+        """Execute the tool with validated arguments. Returns result or error."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Model adapter contract
+# ---------------------------------------------------------------------------
+
+@runtime_checkable
+class ModelAdapter(Protocol):
+    """Abstracts LLM providers. Implementations live in models/."""
+
+    name: str
+
+    def query(self, request: ModelRequest) -> ModelResponse:
+        """Send a request to the model, get a response."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Retriever contract (decision 3 — Environment primitive, NOT an MCP tool)
+# ---------------------------------------------------------------------------
+
+@runtime_checkable
+class Retriever(Protocol):
+    """Knowledge retrieval. Produces EvidenceBundle content (decision 3, Q1 resolved).
+
+    This is an Environment primitive, not a tool — confirmed by open question 1.
+    """
+
+    def retrieve(self, query: str, top_k: int = 5) -> list[Snippet]:
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Memory contract (decision 3 — Environment primitive, three tiers)
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class MemoryView:
+    """Read-only view into memory tiers.
+
+    Working memory: per-step (strategy-managed).
+    Episodic memory: per-task (Session-persisted, Reflexion uses this).
+    Long-term memory: cross-session (retriever-like capability).
+
+    Skeleton: empty stub. Concrete memory backends implement this later.
+    """
+
+    working: dict[str, Any] = field(default_factory=dict)
+    episodic: tuple[dict[str, Any], ...] = ()
+
+
+# ---------------------------------------------------------------------------
+# Environment contract — THE chokepoint (decision 3)
+# ---------------------------------------------------------------------------
+
+@runtime_checkable
+class Environment(Protocol):
+    """The single capability surface strategies may access (decision 3).
+
+    All tool calls, retrieval, and model queries MUST flow through here.
+    This is where permissions (decision 4, two-gate model), cost accounting
+    (decision 4, CostAccountant), and audit (decision 4, EventEmitter) enforce.
+    No strategy may bypass this chokepoint.
+    """
+
+    def tools(self) -> list[Tool]:
+        """Return visible tools (after visibility gate — CapabilityProjection)."""
+        ...
+
+    def call(self, ref: ToolRef, args: dict[str, Any]) -> ToolResult:
+        """Invoke a tool. Passes through invocation gate (authorize→execute→sanitize)."""
+        ...
+
+    def retrieve(self, query: str, top_k: int = 5) -> list[Snippet]:
+        """Retrieve knowledge snippets (produces EvidenceBundle content)."""
+        ...
+
+    def query_model(self, request: ModelRequest) -> ModelResponse:
+        """Query the LLM. Used by strategies for reasoning, value functions, evaluators."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Reasoning strategy contract (decision 3 — pluggable, single interface)
+# ---------------------------------------------------------------------------
+
+@runtime_checkable
+class ReasoningStrategy(Protocol):
+    """Pluggable reasoning. Standardized I/O, not standardized algorithm.
+
+    Strategies differ in HOW they search (react loop / tree search / MCTS /
+    symbolic planning) but share the same consumption surface (Environment).
+    """
+
+    name: str
+
+    def run(self, ctx: "RunContext") -> Result:
+        """Execute the reasoning strategy within the given context."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# RunContext — what a strategy receives
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class RunContext:
+    """Everything a ReasoningStrategy needs to execute.
+
+    Built by Session before calling strategy.run(). The Environment is the
+    ONLY way to access capabilities (chokepoint). Budget is enforced inside
+    Environment, not by the strategy.
+    """
+
+    task: Task
+    env: Environment
+    budget: Budget
+    memory: MemoryView
+    events: Any  # EventEmitter (typed in events.py; Any here to avoid cycle)
+    compiled: Any = None  # CompiledContext (v0.2 contract compilation layer)
+    conversation_history: tuple[Message, ...] = ()  # cross-session memory

petfishframework/core/conversation.py

@@ -0,0 +1,51 @@
+"""Conversation memory store.
+
+Provides a protocol for loading/saving chat history by conversation_id and a
+reference in-memory implementation. Conversation history is stored as full
+Message objects so downstream strategies can reconstruct the exact model input.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from .types import Message
+
+
+class ConversationStore(Protocol):
+    """Persistent storage for cross-session conversation history.
+
+    Implementations are expected to be stateful but need not survive process
+    restart (file-based / database backends implement that later).
+    """
+
+    def load(self, conversation_id: str) -> list[Message]:
+        """Return the conversation messages for *conversation_id* or an empty list."""
+        ...
+
+    def save(self, conversation_id: str, messages: list[Message]) -> None:
+        """Replace the stored conversation messages for *conversation_id*."""
+        ...
+
+
+@dataclass
+class InMemoryConversationStore:
+    """Volatile in-memory conversation store for testing and single-process use."""
+
+    _conversations: dict[str, list[Message]] = field(default_factory=dict)
+
+    def load(self, conversation_id: str) -> list[Message]:
+        """Return a shallow copy of the stored messages so callers can mutate safely."""
+        return list(self._conversations.get(conversation_id, []))
+
+    def save(self, conversation_id: str, messages: list[Message]) -> None:
+        """Replace the conversation entirely."""
+        self._conversations[conversation_id] = list(messages)
+
+    def clear(self, conversation_id: str) -> None:
+        """Delete a single conversation if it exists."""
+        self._conversations.pop(conversation_id, None)
+
+    def clear_all(self) -> None:
+        """Delete every stored conversation."""
+        self._conversations.clear()

petfishframework/core/environment.py

@@ -0,0 +1,260 @@
+"""RuntimeEnvironment — the single capability chokepoint (decision 3).
+
+All tool calls, model queries, and retrieval pass through here. It hosts the
+permission gate (SARC), cost accounting (Budget), and audit events.
+"""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any
+
+from petfishframework.permissions.model import (
+    AccessContext,
+    Action,
+    DecisionEffect,
+    PermissionPolicy,
+    Resource,
+    Subject,
+)
+from petfishframework.reliability.cost import CostAccountant
+
+from .contracts import Environment, ModelAdapter, Retriever, Tool
+from .events import EventEmitter
+from .types import (
+    Budget,
+    ModelRequest,
+    ModelResponse,
+    Snippet,
+    ToolRef,
+    ToolResult,
+    Usage,
+)
+
+
+@dataclass
+class RuntimeEnvironment(Environment):
+    """Concrete Environment enforcing permissions, budget, and audit."""
+
+    model: ModelAdapter
+    _tools: tuple[Tool, ...]
+    retriever: Retriever | None
+    budget: Budget
+    events: EventEmitter
+    policy: PermissionPolicy
+    session_id: str = ""
+    _accountant: CostAccountant | None = None
+
+    def __post_init__(self) -> None:
+        if self._accountant is None:
+            self._accountant = CostAccountant()
+
+    @property
+    def _costs(self) -> CostAccountant:
+        """Return the cost accountant, initializing if needed."""
+        if self._accountant is None:
+            self._accountant = CostAccountant()
+        return self._accountant
+
+    def tools(self) -> list[Tool]:
+        """Return visible tools (skeleton: all tools; visibility gate TODO)."""
+        return list(self._tools)
+
+    def call(self, ref: ToolRef, args: dict) -> ToolResult:
+        """Invoke a tool through the permission + budget + audit gate."""
+        tool, decision = self._prepare_tool_call(ref, args)
+
+        if tool is None:
+            return self._deny_tool(
+                ref, args, "unknown tool", DecisionEffect.DENY.value, error_code="unknown_tool"
+            )
+
+        if decision.effect == DecisionEffect.DENY:
+            reason = decision.reason or "policy denied"
+            return self._deny_tool(ref, args, reason, decision.effect.value)
+
+        result = tool.execute(args)
+        return self._finalize_tool_call(ref, args, tool, decision, result)
+
+    async def call_async(self, ref: ToolRef, args: dict) -> ToolResult:
+        """Async version of call; awaits async tool.execute when detected."""
+        tool, decision = self._prepare_tool_call(ref, args)
+
+        if tool is None:
+            return self._deny_tool(
+                ref, args, "unknown tool", DecisionEffect.DENY.value, error_code="unknown_tool"
+            )
+
+        if decision.effect == DecisionEffect.DENY:
+            reason = decision.reason or "policy denied"
+            return self._deny_tool(ref, args, reason, decision.effect.value)
+
+        if asyncio.iscoroutinefunction(tool.execute):
+            result = await tool.execute(args)
+        else:
+            result = tool.execute(args)
+        return self._finalize_tool_call(ref, args, tool, decision, result)
+
+    def retrieve(self, query: str, top_k: int = 5) -> list[Snippet]:
+        """Retrieve knowledge snippets (skeleton: empty if no retriever)."""
+        snippets = self._fetch_snippets(query, top_k)
+        return self._finalize_retrieval(query, top_k, snippets)
+
+    async def retrieve_async(self, query: str, top_k: int = 5) -> list[Snippet]:
+        """Async version of retrieve; awaits async retriever.retrieve when detected."""
+        snippets = await self._fetch_snippets_async(query, top_k)
+        return self._finalize_retrieval(query, top_k, snippets)
+
+    def query_model(self, request: ModelRequest) -> ModelResponse:
+        """Query the model, accumulate usage, and enforce budget."""
+        response = self.model.query(request)
+        return self._finalize_query_model(request, response)
+
+    async def query_model_async(self, request: ModelRequest) -> ModelResponse:
+        """Async version of query_model; awaits async model.query/query_async."""
+        query_async = getattr(self.model, "query_async", None)
+        if query_async is not None and asyncio.iscoroutinefunction(query_async):
+            response = await query_async(request)
+        elif asyncio.iscoroutinefunction(self.model.query):
+            response = await self.model.query(request)
+        else:
+            response = self.model.query(request)
+        return self._finalize_query_model(request, response)
+
+    def usage(self) -> Usage:
+        """Return accumulated usage from the cost accountant."""
+        return self._costs.total()
+
+    def _find_tool(self, name: str) -> Tool | None:
+        for t in self._tools:
+            if t.name == name:
+                return t
+        return None
+
+    def _prepare_tool_call(self, ref: ToolRef, args: dict) -> tuple[Tool | None, Any]:
+        """Permission gate for tool calls; shared by sync and async paths."""
+        tool = self._find_tool(ref.name)
+
+        subject = Subject()
+        action = Action(type="call", tool_name=ref.name, args=args)
+        resource = Resource(type="tool", classification="public")
+        context = AccessContext(session_id=self.session_id, step=0)
+        decision = self.policy.evaluate(subject, action, resource, context)
+
+        return tool, decision
+
+    def _deny_tool(
+        self,
+        ref: ToolRef,
+        args: dict,
+        reason: str,
+        effect_value: str,
+        error_code: str | None = None,
+    ) -> ToolResult:
+        """Emit tool.denied and return an error ToolResult."""
+        self.events.emit(
+            "tool.denied",
+            {
+                "tool_name": ref.name,
+                "args": args,
+                "effect": effect_value,
+                "reason": reason,
+            },
+        )
+        return ToolResult(error=error_code if error_code is not None else f"denied: {reason}")
+
+    def _finalize_tool_call(
+        self,
+        ref: ToolRef,
+        args: dict,
+        tool: Tool,
+        decision: Any,
+        result: ToolResult,
+    ) -> ToolResult:
+        """Post-execution audit, masking, and budget enforcement."""
+        if decision.effect == DecisionEffect.MASK:
+            masked = ToolResult(value="[MASKED]", masked=True)
+            self.events.emit(
+                "tool.masked",
+                {
+                    "tool_name": ref.name,
+                    "args": args,
+                    "effect": DecisionEffect.MASK.value,
+                },
+            )
+            return masked
+
+        # Skeleton: treat other non-allow effects as deny for safety.
+        if decision.effect != DecisionEffect.ALLOW:
+            reason = decision.reason or f"effect {decision.effect.value} not supported"
+            return self._deny_tool(ref, args, reason, decision.effect.value)
+
+        self.events.emit(
+            "tool.called",
+            {
+                "tool_name": ref.name,
+                "args": args,
+                "result_value": result.value if not result.is_error else None,
+                "result_error": result.error if result.is_error else None,
+            },
+        )
+
+        self._costs.record_tool_call()
+        self._costs.check_budget(self.budget)
+        return result
+
+    def _fetch_snippets(self, query: str, top_k: int) -> list[Snippet]:
+        """Sync snippet fetch, including event injection for retrievers."""
+        if self.retriever is None:
+            return []
+
+        # Inject EventEmitter for event-aware retrievers (CRAG, Adaptive-RAG)
+        if hasattr(self.retriever, "events"):
+            object.__setattr__(self.retriever, "events", self.events)
+
+        return self.retriever.retrieve(query, top_k)
+
+    async def _fetch_snippets_async(self, query: str, top_k: int) -> list[Snippet]:
+        """Async snippet fetch; awaits async retriever.retrieve when detected."""
+        if self.retriever is None:
+            return []
+
+        # Inject EventEmitter for event-aware retrievers (CRAG, Adaptive-RAG)
+        if hasattr(self.retriever, "events"):
+            object.__setattr__(self.retriever, "events", self.events)
+
+        if asyncio.iscoroutinefunction(self.retriever.retrieve):
+            return await self.retriever.retrieve(query, top_k)
+        return self.retriever.retrieve(query, top_k)
+
+    def _finalize_retrieval(self, query: str, top_k: int, snippets: list[Snippet]) -> list[Snippet]:
+        """Emit retrieval event; shared by sync and async paths."""
+        self.events.emit(
+            "retrieval",
+            {
+                "query": query,
+                "top_k": top_k,
+                "snippet_count": len(snippets),
+            },
+        )
+        return snippets
+
+    def _finalize_query_model(self, request: ModelRequest, response: ModelResponse) -> ModelResponse:
+        """Emit model.called, accumulate usage, and enforce budget."""
+        self.events.emit(
+            "model.called",
+            {
+                "model": self.model.name,
+                "usage": {
+                    "input_tokens": response.usage.input_tokens,
+                    "output_tokens": response.usage.output_tokens,
+                    "total_tokens": response.usage.total_tokens,
+                    "cost_usd": response.usage.cost_usd,
+                    "elapsed_s": response.usage.elapsed_s,
+                },
+            },
+        )
+
+        self._costs.record(response.usage)
+        self._costs.check_budget(self.budget)
+        return response

petfishframework/core/events.py

@@ -0,0 +1,79 @@
+"""Event system — the structural reliability mechanism (decision 4).
+
+One append-only event stream serves four purposes simultaneously:
+  1. Audit log (every model/tool/retrieval/permission decision recorded)
+  2. Checkpoint source (snapshot = materialized state at a point)
+  3. Cost ledger (usage events accumulate)
+  4. Replay source (re-inject recorded outputs for deterministic replay)
+
+This is the 'one stream, many consumers' trick that makes reliability
+structural rather than bolted-on.
+"""
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass(frozen=True)
+class Event:
+    """A single recorded event in a session's lifecycle."""
+
+    type: str
+    timestamp: float
+    data: dict[str, Any]
+    event_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+
+    # Determinism class for replay (open question 3 — ReplayMode)
+    # DETERMINISTIC: re-execute (calculator, pure functions)
+    # RECORDED: re-inject recorded value (LLM calls, web search)
+    # NONDETERMINISTIC: re-call but expect different (time-dependent APIs)
+    determinism: str = "RECORDED"
+
+
+class EventEmitter:
+    """Append-only event log with multi-consumer sink support.
+
+    Events are immutable once emitted. Sinks (observability/, audit, metrics)
+    subscribe and receive every event without affecting the log.
+    """
+
+    def __init__(self) -> None:
+        self._events: list[Event] = []
+        self._sinks: list[Callable[[Event], None]] = []
+
+    def emit(self, type: str, data: dict[str, Any] | None = None, determinism: str = "RECORDED") -> Event:
+        """Record an event and notify all sinks."""
+        event = Event(
+            type=type,
+            timestamp=time.time(),
+            data=data or {},
+            determinism=determinism,
+        )
+        self._events.append(event)
+        for sink in self._sinks:
+            try:
+                sink(event)
+            except Exception:
+                # Sink failures must NOT break the event log (agentShield P0-9 principle)
+                pass
+        return event
+
+    def subscribe(self, sink: Callable[[Event], None]) -> None:
+        """Register a sink that receives every emitted event."""
+        self._sinks.append(sink)
+
+    @property
+    def events(self) -> tuple[Event, ...]:
+        """Immutable snapshot of all recorded events."""
+        return tuple(self._events)
+
+    def events_of(self, type: str) -> tuple[Event, ...]:
+        """Filter events by type."""
+        return tuple(e for e in self._events if e.type == type)
+
+    def clear(self) -> None:
+        """Reset the log. Used for testing only."""
+        self._events.clear()