petfishframework 0.1.0__py3-none-any.whl

petfishframework/core/session.py

@@ -0,0 +1,182 @@
+"""Session — event-sourced run loop (decision 1 + decision 4)."""
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+
+from petfishframework.permissions.model import PermissionPolicy
+
+from .compiled import CompiledContext, EvidenceBundle, MemorySlice, OutputContract, TaskSpec
+from .contracts import (
+    MemoryView,
+    ModelAdapter,
+    ReasoningStrategy,
+    Retriever,
+    RunContext,
+    Tool,
+)
+from .conversation import ConversationStore
+from .environment import RuntimeEnvironment
+from .events import EventEmitter
+from .types import Budget, Message, Result, Role, Task, Usage
+
+
+@dataclass
+class Session:
+    """A single execution of an Agent.
+
+    Session owns the RuntimeEnvironment, RunContext, and EventEmitter. It is
+    the Process abstraction in the Agent:Session :: program:process analogy.
+    """
+
+    model: ModelAdapter
+    reasoning: ReasoningStrategy
+    tools: tuple[Tool, ...]
+    retriever: Retriever | None
+    policy: PermissionPolicy
+    task: Task
+    budget: Budget | None
+    events: EventEmitter
+    session_id: str = field(default_factory=lambda: uuid.uuid4().hex[:16])
+    _env: RuntimeEnvironment | None = field(default=None, repr=False)
+    conversation_id: str | None = None
+    conversation_store: ConversationStore | None = None
+
+    def run(self) -> Result:
+        """Execute the session and return a Result."""
+        ctx = self._prepare_run()
+        result = self.reasoning.run(ctx)
+        return self._finalize_run(result)
+
+    async def run_async(self) -> Result:
+        """Execute the session asynchronously and return a Result."""
+        ctx = self._prepare_run()
+        run_async = getattr(self.reasoning, "run_async", None)
+        if run_async is None:
+            raise RuntimeError(
+                f"Strategy {self.reasoning.name} does not support async. "
+                "Implement run_async()."
+            )
+        result = await run_async(ctx)
+        return self._finalize_run(result)
+
+    def _prepare_run(self) -> RunContext:
+        """Build the RuntimeEnvironment and RunContext; shared by sync/async paths."""
+        compiled = CompiledContext(
+            task_spec=TaskSpec(task_type="generic"),
+            memory_slice=MemorySlice(),
+            evidence_bundle=EvidenceBundle(),
+            output_contract=OutputContract(),
+        )
+
+        budget = self.budget if self.budget is not None else Budget()
+        self._env = RuntimeEnvironment(
+            model=self.model,
+            _tools=self.tools,
+            retriever=self.retriever,
+            budget=budget,
+            events=self.events,
+            policy=self.policy,
+            session_id=self.session_id,
+        )
+
+        conversation_history = self._load_conversation_history()
+        ctx = RunContext(
+            task=self.task,
+            env=self._env,
+            budget=budget,
+            memory=MemoryView(),
+            events=self.events,
+            compiled=compiled,
+            conversation_history=conversation_history,
+        )
+
+        self.events.emit(
+            "session.start",
+            {
+                "session_id": self.session_id,
+                "task": self.task.prompt,
+                "reasoning": self.reasoning.name,
+            },
+        )
+        return ctx
+
+    def _load_conversation_history(self) -> tuple[Message, ...]:
+        """Load persisted conversation history when a store and id are configured."""
+        if self.conversation_store is None or self.conversation_id is None:
+            return ()
+
+        history = tuple(self.conversation_store.load(self.conversation_id))
+        self.events.emit(
+            "conversation.load",
+            {
+                "conversation_id": self.conversation_id,
+                "message_count": len(history),
+            },
+        )
+        return history
+
+    def _finalize_run(self, result: Result) -> Result:
+        """Attach usage, persist conversation, and emit session.end."""
+        usage = self._env.usage() if self._env is not None else Usage()
+        result = Result(
+            answer=result.answer,
+            trajectory=result.trajectory,
+            usage=usage,
+            session_id=self.session_id,
+        )
+
+        self._save_conversation_history(result)
+
+        self.events.emit(
+            "session.end",
+            {
+                "session_id": self.session_id,
+                "answer": result.answer,
+                "usage": {
+                    "input_tokens": usage.input_tokens,
+                    "output_tokens": usage.output_tokens,
+                    "total_tokens": usage.total_tokens,
+                    "cost_usd": usage.cost_usd,
+                    "elapsed_s": usage.elapsed_s,
+                },
+            },
+        )
+        return result
+
+    def _save_conversation_history(self, result: Result) -> None:
+        """Persist previous history plus the current user/assistant turn."""
+        if self.conversation_store is None or self.conversation_id is None:
+            return
+
+        previous = list(self.conversation_store.load(self.conversation_id))
+        current_turn = [
+            Message(role=Role.USER, content=self.task.prompt),
+            Message(role=Role.ASSISTANT, content=result.answer),
+        ]
+        new_messages = previous + current_turn
+        self.conversation_store.save(self.conversation_id, new_messages)
+        self.events.emit(
+            "conversation.save",
+            {
+                "conversation_id": self.conversation_id,
+                "message_count": len(new_messages),
+            },
+        )
+
+    def replay(self) -> tuple:
+        """Return the recorded event log (AUDIT replay mode).
+
+        RESUME and RERUN replay modes are TODO (open question 3).
+        """
+        return self.events.events
+
+    def checkpoint(self) -> None:
+        """Emit a checkpoint event capturing current state."""
+        self.events.emit(
+            "checkpoint",
+            {
+                "session_id": self.session_id,
+                "step_count": len(self.events.events),
+            },
+        )

petfishframework/core/structured.py

@@ -0,0 +1,202 @@
+"""Structured output parsing — stdlib-only (json + dataclasses).
+
+Thin-core extension that turns a model's JSON response into a typed dataclass
+without pulling in Pydantic or any external dependency.
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, fields
+from typing import Any, ClassVar, Generic, Protocol, TypeVar, get_type_hints
+
+
+class DataclassInstance(Protocol):
+    """Protocol matching dataclass instances recognized by stdlib fields()."""
+
+    __dataclass_fields__: ClassVar[dict[str, Any]]
+
+
+T = TypeVar("T", bound=DataclassInstance)
+
+# Match a fenced JSON code block: ```json ... ``` or ``` ... ```
+_CODE_BLOCK_RE = re.compile(
+    r"```(?:json)?\s*(.*?)\s*```",
+    re.DOTALL | re.IGNORECASE,
+)
+
+# Match the first JSON object ({...}) or array ([...]) in free text.
+_JSON_OBJECT_RE = re.compile(r"\{[\s\S]*?\}")
+_JSON_ARRAY_RE = re.compile(r"\[[\s\S]*?\]")
+
+
+@dataclass(frozen=True)
+class StructuredResult(Generic[T]):
+    """The outcome of a structured agent run.
+
+    Always carries the raw answer, the parsed object (when possible), an
+    optional parse error message, and the originating session id.
+    """
+
+    answer: str
+    data: T | None
+    parse_error: str | None
+    session_id: str
+
+
+def extract_json_from_content(content: str) -> str | None:
+    """Extract a JSON string from direct JSON, fenced code blocks, or embedded text.
+
+    Returns the first plausible JSON object or array found, or None if none
+    is detected.
+    """
+    if not content or not content.strip():
+        return None
+
+    text = content.strip()
+
+    # 1. Direct JSON.
+    try:
+        json.loads(text)
+        return text
+    except json.JSONDecodeError:
+        pass
+
+    # 2. Fenced markdown code block.
+    code_match = _CODE_BLOCK_RE.search(text)
+    if code_match:
+        candidate = code_match.group(1).strip()
+        try:
+            json.loads(candidate)
+            return candidate
+        except json.JSONDecodeError:
+            pass
+
+    # 3. Embedded object or array.
+    object_match = _JSON_OBJECT_RE.search(text)
+    if object_match:
+        candidate = object_match.group(0)
+        try:
+            json.loads(candidate)
+            return candidate
+        except json.JSONDecodeError:
+            pass
+
+    array_match = _JSON_ARRAY_RE.search(text)
+    if array_match:
+        candidate = array_match.group(0)
+        try:
+            json.loads(candidate)
+            return candidate
+        except json.JSONDecodeError:
+            pass
+
+    return None
+
+
+def parse_json(content: str) -> Any:
+    """Parse JSON from model response content.
+
+    Handles direct JSON, fenced code blocks, and JSON embedded in prose.
+    Returns the parsed value (dict, list, or primitive). Raises ValueError
+    when no valid JSON can be extracted.
+    """
+    candidate = extract_json_from_content(content)
+    if candidate is None:
+        raise ValueError("No valid JSON found in content.")
+    try:
+        return json.loads(candidate)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON: {exc}") from exc
+
+
+def _is_dataclass_type(output_type: type) -> bool:
+    """True if output_type looks like a dataclass class."""
+    return isinstance(output_type, type) and hasattr(output_type, "__dataclass_fields__")
+
+
+def parse_structured(content: str, output_type: type[T]) -> T:
+    """Parse JSON from content and instantiate output_type.
+
+    output_type must be a dataclass. Unknown fields in the JSON payload are
+    ignored. Raises ValueError if the JSON is invalid or instantiation fails.
+    """
+    if not _is_dataclass_type(output_type):
+        raise ValueError(f"output_type must be a dataclass, got {output_type!r}")
+
+    try:
+        parsed = parse_json(content)
+    except ValueError as exc:
+        raise ValueError(f"Could not parse structured output: {exc}") from exc
+
+    if not isinstance(parsed, dict):
+        raise ValueError(f"Expected a JSON object for dataclass {output_type.__name__}, got {type(parsed).__name__}")
+
+    dataclass_fields = {f.name for f in fields(output_type)}
+    filtered = {k: v for k, v in parsed.items() if k in dataclass_fields}
+
+    # Coerce simple JSON types toward the declared field type when safe.
+    type_hints = get_type_hints(output_type)
+    coerced: dict[str, Any] = {}
+    for key, value in filtered.items():
+        field_type = type_hints.get(key)
+        try:
+            coerced[key] = _coerce_value(value, field_type)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"Field '{key}' could not be coerced to {field_type}: {exc}") from exc
+
+    try:
+        return output_type(**coerced)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"Could not instantiate {output_type.__name__}: {exc}") from exc
+
+
+def _coerce_value(value: Any, field_type: Any) -> Any:
+    """Best-effort stdlib coercion for JSON primitives to common dataclass field types."""
+    if field_type is None:
+        return value
+
+    # Strip None from Optional[X] to inspect the inner type.
+    origin = getattr(field_type, "__origin__", None)
+    args = getattr(field_type, "__args__", ())
+
+    # Optional[X] == Union[X, None]
+    if origin is type | None or origin is None.__class__:
+        # typing.Optional[X]
+        non_none_args = [a for a in args if a is not type(None)]
+        if len(non_none_args) == 1:
+            field_type = non_none_args[0]
+            origin = getattr(field_type, "__origin__", None)
+            args = getattr(field_type, "__args__", ())
+
+    # Direct identity matches.
+    if field_type is Any:
+        return value
+
+    if isinstance(value, field_type):
+        return value
+
+    # Union types (other than Optional handled above) — try each arg.
+    if origin is type | None:
+        for candidate in args:
+            if candidate is type(None) and value is None:
+                return None
+            try:
+                return _coerce_value(value, candidate)
+            except (TypeError, ValueError):
+                continue
+        raise TypeError(f"Value {value!r} does not match union {field_type}")
+
+    # Common JSON-friendly scalar coercions.
+    if field_type is int:
+        return int(value)
+    if field_type is float:
+        return float(value)
+    if field_type is str:
+        return str(value)
+    if field_type is bool:
+        return bool(value)
+
+    # Generic containers — keep as parsed lists/dicts; dataclass construction
+    # will validate element types via runtime checks on its own.
+    return value

petfishframework/core/types.py

@@ -0,0 +1,192 @@
+"""Core types — value objects shared across the framework.
+
+This module has ZERO dependencies on concrete implementations.
+Everything here is pure data (dataclasses / enums) that other modules
+build upon. Keeping it dependency-free is what makes the thin-core
+principle (decision 5) hold.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Task & Result
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class Task:
+    """The user's request to the agent."""
+
+    prompt: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Step:
+    """One step in a reasoning trajectory."""
+
+    thought: str | None = None
+    tool_name: str | None = None
+    tool_args: dict[str, Any] | None = None
+    observation: str | None = None
+
+
+@dataclass(frozen=True)
+class Trajectory:
+    """The full sequence of steps an agent took."""
+
+    steps: tuple[Step, ...] = ()
+
+    def append(self, step: Step) -> "Trajectory":
+        return Trajectory(steps=self.steps + (step,))
+
+
+@dataclass(frozen=True)
+class Result:
+    """The final output of an agent run."""
+
+    answer: str
+    trajectory: Trajectory = field(default_factory=Trajectory)
+    usage: "Usage" = field(default_factory=lambda: Usage())
+    session_id: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Budget & Usage (reliability/cost — decision 4)
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class Usage:
+    """Accumulated resource consumption."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+    cost_usd: float = 0.0
+    elapsed_s: float = 0.0
+
+    def add(self, other: "Usage") -> "Usage":
+        return Usage(
+            input_tokens=self.input_tokens + other.input_tokens,
+            output_tokens=self.output_tokens + other.output_tokens,
+            total_tokens=self.total_tokens + other.total_tokens,
+            cost_usd=self.cost_usd + other.cost_usd,
+            elapsed_s=self.elapsed_s + other.elapsed_s,
+        )
+
+
+@dataclass(frozen=True)
+class Budget:
+    """Hard limits for a single session run.
+
+    Exceeding any limit raises BudgetExceeded (hard enforcement — decision 4).
+    A None field means unlimited for that dimension.
+    """
+
+    max_tokens: int | None = None
+    max_cost_usd: float | None = None
+    max_steps: int | None = None
+    max_tool_calls: int | None = None
+
+
+class BudgetExceeded(Exception):
+    """Raised when a session exceeds its budget (hard enforcement)."""
+
+    def __init__(self, dimension: str, limit: Any, actual: Any):
+        self.dimension = dimension
+        self.limit = limit
+        self.actual = actual
+        super().__init__(f"Budget exceeded: {dimension} limit={limit} actual={actual}")
+
+
+# ---------------------------------------------------------------------------
+# Messaging (model interaction)
+# ---------------------------------------------------------------------------
+
+class Role(Enum):
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+
+@dataclass(frozen=True)
+class Message:
+    """A single chat message."""
+
+    role: Role
+    content: str = ""
+    tool_calls: tuple["ToolCall", ...] = ()
+    tool_call_id: str | None = None  # for role=TOOL responses
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    """A tool invocation requested by the model."""
+
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class ModelRequest:
+    """A request to a language model."""
+
+    messages: tuple[Message, ...]
+    tools: tuple[str, ...] = ()  # tool names available (for function-calling)
+    tool_schemas: tuple[dict[str, Any], ...] = ()  # full tool definitions: {name, description, input_schema}
+    temperature: float = 0.0
+    max_tokens: int | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ModelResponse:
+    """A response from a language model."""
+
+    content: str = ""
+    tool_calls: tuple[ToolCall, ...] = ()
+    usage: Usage = field(default_factory=Usage)
+    finish_reason: str = "stop"
+    raw: Any = None  # provider-specific raw response
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class ToolRef:
+    """A reference to a tool by name."""
+
+    name: str
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    """The outcome of a tool invocation."""
+
+    value: Any = None
+    error: str | None = None
+    masked: bool = False  # if MASK decision effect applied
+
+    @property
+    def is_error(self) -> bool:
+        return self.error is not None
+
+
+# ---------------------------------------------------------------------------
+# Retrieval
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class Snippet:
+    """A single retrieval result."""
+
+    content: str
+    source: str = ""
+    score: float = 0.0
+    metadata: dict[str, Any] = field(default_factory=dict)

petfishframework/mcp/__init__.py

@@ -0,0 +1,19 @@
+"""MCP integration module — the only module that knows the MCP wire protocol.
+
+This package adapts MCP-shaped tools into the framework's canonical Tool
+contract (decision 2). Core and strategies see only `Tool`; all MCP-specific
+concepts live here.
+"""
+from __future__ import annotations
+
+from .client import MCPClient, MCPToolSpec, connect_stdio
+from .server import serve_as_mcp
+from .wrapper import MCPToolWrapper
+
+__all__ = [
+    "MCPClient",
+    "MCPToolSpec",
+    "MCPToolWrapper",
+    "connect_stdio",
+    "serve_as_mcp",
+]

petfishframework/mcp/client.py

@@ -0,0 +1,96 @@
+"""MCP client — tool discovery and invocation.
+
+The in-process client is constructed from ``MCPToolSpec`` dictionaries. The
+``connect_stdio`` function builds a client from a real MCP server subprocess
+speaking JSON-RPC over stdio.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .wrapper import MCPToolWrapper
+
+
+@dataclass(frozen=True)
+class MCPToolSpec:
+    """Static description of an MCP tool callable from Python code.
+
+    This is the in-process equivalent of an MCP ``tools/list`` entry plus its
+    invocation handler. It is used to bootstrap ``MCPClient`` in tests and in
+    environments where the server is co-located.
+    """
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    call_fn: Callable[[dict[str, Any]], Any]
+
+
+class MCPClient:
+    """Client for MCP tool discovery and invocation.
+
+    Constructed from a dictionary of tool specs. Clients created by
+    ``connect_stdio`` additionally hold a reference to the live stdio transport
+    so the subprocess stays alive as long as the client is in use.
+    """
+
+    def __init__(self, tools: dict[str, MCPToolSpec]) -> None:
+        self._tools: dict[str, MCPToolSpec] = dict(tools)
+
+    def discover_tools(self) -> list[MCPToolWrapper]:
+        """Return each registered MCP tool wrapped as a framework ``Tool``."""
+        return [
+            MCPToolWrapper(
+                name=spec.name,
+                description=spec.description,
+                input_schema=spec.input_schema,
+                call_fn=spec.call_fn,
+            )
+            for spec in self._tools.values()
+        ]
+
+    def call_tool(self, name: str, args: dict[str, Any]) -> Any:
+        """Invoke a registered tool by name and return its raw value."""
+        spec = self._tools[name]
+        return spec.call_fn(args)
+
+
+def connect_stdio(
+    command: str,
+    args: list[str],
+    env: dict[str, str] | None = None,
+) -> MCPClient:
+    """Connect to an MCP server via stdio and discover its tools.
+
+    This function spawns ``command`` with ``args`` as a subprocess, performs
+    the MCP initialization handshake, lists the available tools, and returns an
+    ``MCPClient`` populated with ``MCPToolSpec`` instances that forward calls to
+    the subprocess via JSON-RPC.
+
+    The underlying ``StdioMCPClient`` is attached to the returned
+    ``MCPClient`` as ``_transport`` so it stays alive for the lifetime of the
+    client. Callers may use the returned client as a context manager to ensure
+    the subprocess is terminated on exit.
+    """
+    from .stdio_transport import StdioMCPClient
+
+    transport = StdioMCPClient(command, args, env=env)
+    transport.initialize()
+
+    tool_defs = transport.list_tools()
+    tools: dict[str, MCPToolSpec] = {}
+    for tool_def in tool_defs:
+        name = tool_def["name"]
+        tools[name] = MCPToolSpec(
+            name=name,
+            description=tool_def.get("description", ""),
+            input_schema=tool_def.get("inputSchema", {}),
+            call_fn=lambda arguments, tool_name=name: transport.call_tool(
+                tool_name, arguments
+            ),
+        )
+
+    client = MCPClient(tools=tools)
+    object.__setattr__(client, "_transport", transport)
+    return client

petfishframework/mcp/server.py

@@ -0,0 +1,14 @@
+"""MCP server helper — expose framework tools as an MCP server (Phase 4)."""
+from __future__ import annotations
+
+from petfishframework.core.contracts import Tool
+
+
+def serve_as_mcp(tools: list[Tool]) -> None:  # noqa: ARG001
+    """Expose framework tools as an MCP server.
+
+    STUB — Phase 4 work. This function documents the symmetrical direction:
+    just as ``mcp/`` consumes external tools into the framework's ``Tool``
+    contract, the framework can also export its own tools as an MCP server.
+    """
+    raise NotImplementedError("MCP server mode is Phase 4.")