petfishframework 0.1.0__py3-none-any.whl

petfishframework/__init__.py

@@ -0,0 +1,33 @@
+"""petfishFramework — a general AI Agent framework.
+
+Model-agnostic agent framework with pluggable reasoning strategies,
+MCP-first tool contracts, and structural reliability.
+"""
+from __future__ import annotations
+
+from .config import FrameworkConfig
+from .core.agent import Agent
+from .core.contracts import Tool
+from .core.types import Budget, BudgetExceeded, Result, Task
+from .permissions.model import DecisionEffect
+from .reasoning import LATS, LLMPlusP, ReAct
+from .reliability.replay import ReplayMode
+from .tools.base import BaseTool
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Agent",
+    "BaseTool",
+    "Budget",
+    "BudgetExceeded",
+    "DecisionEffect",
+    "FrameworkConfig",
+    "LATS",
+    "LLMPlusP",
+    "ReAct",
+    "ReplayMode",
+    "Result",
+    "Task",
+    "Tool",
+]

petfishframework/config.py

@@ -0,0 +1,142 @@
+"""Framework-wide configuration (M2 gap).
+
+Provides a typed, environment-aware config object with safe defaults and
+factories for env-var / dict (YAML/JSON) loading.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+from petfishframework.core.types import Budget
+from petfishframework.reliability.retry import RetryPolicy
+
+
+def _env_str(key: str, default: str) -> str:
+    return os.environ.get(key, default)
+
+
+def _env_float(key: str, default: float) -> float:
+    value = os.environ.get(key)
+    if value is None:
+        return default
+    return float(value)
+
+
+def _env_float_or_none(key: str) -> float | None:
+    value = os.environ.get(key)
+    if value is None:
+        return None
+    return float(value)
+
+
+def _env_int_or_none(key: str) -> int | None:
+    value = os.environ.get(key)
+    if value is None:
+        return None
+    return int(value)
+
+
+def _env_bool(key: str, default: bool) -> bool:
+    value = os.environ.get(key)
+    if value is None:
+        return default
+    return value.lower() not in {"0", "false", "no", "off", ""}
+
+
+@dataclass(frozen=True)
+class FrameworkConfig:
+    """Top-level configuration for petfishFramework.
+
+    Defaults are deliberately conservative: deterministic agents via
+    temperature=0.0, no token cap, no budget limits, and a 30s global
+    operation timeout.
+    """
+
+    default_model: str = "gpt-4o"
+    default_temperature: float = 0.0
+    default_max_tokens: int | None = None
+    default_budget: Budget = field(default_factory=Budget)
+    openai_api_key: str | None = None
+    anthropic_api_key: str | None = None
+    retry_policy: RetryPolicy | None = None
+    timeout_s: float = 30.0
+
+    @classmethod
+    def from_env(cls) -> FrameworkConfig:
+        """Build a config from environment variables.
+
+        Supported variables:
+          - PETFISH_DEFAULT_MODEL
+          - PETFISH_DEFAULT_TEMPERATURE
+          - PETFISH_DEFAULT_MAX_TOKENS
+          - PETFISH_MAX_TOKENS / PETFISH_MAX_COST_USD / PETFISH_MAX_STEPS /
+            PETFISH_MAX_TOOL_CALLS (populate default_budget)
+          - OPENAI_API_KEY / ANTHROPIC_API_KEY
+          - PETFISH_TIMEOUT_S
+          - PETFISH_RETRY_* (max_retries, initial_delay, backoff_factor,
+            max_delay, jitter) populate retry_policy when any is present.
+        """
+        default_budget = Budget(
+            max_tokens=_env_int_or_none("PETFISH_MAX_TOKENS"),
+            max_cost_usd=_env_float_or_none("PETFISH_MAX_COST_USD"),
+            max_steps=_env_int_or_none("PETFISH_MAX_STEPS"),
+            max_tool_calls=_env_int_or_none("PETFISH_MAX_TOOL_CALLS"),
+        )
+
+        retry_policy = None
+        if any(
+            os.environ.get(f"PETFISH_RETRY_{name}") is not None
+            for name in (
+                "MAX_RETRIES",
+                "INITIAL_DELAY",
+                "BACKOFF_FACTOR",
+                "MAX_DELAY",
+                "JITTER",
+            )
+        ):
+            retry_policy = RetryPolicy(
+                max_retries=_env_int_or_none("PETFISH_RETRY_MAX_RETRIES") or 3,
+                initial_delay=_env_float("PETFISH_RETRY_INITIAL_DELAY", 1.0),
+                backoff_factor=_env_float("PETFISH_RETRY_BACKOFF_FACTOR", 2.0),
+                max_delay=_env_float("PETFISH_RETRY_MAX_DELAY", 60.0),
+                jitter=_env_bool("PETFISH_RETRY_JITTER", True),
+            )
+
+        return cls(
+            default_model=_env_str("PETFISH_DEFAULT_MODEL", "gpt-4o"),
+            default_temperature=_env_float("PETFISH_DEFAULT_TEMPERATURE", 0.0),
+            default_max_tokens=_env_int_or_none("PETFISH_DEFAULT_MAX_TOKENS"),
+            default_budget=default_budget,
+            openai_api_key=os.environ.get("OPENAI_API_KEY"),
+            anthropic_api_key=os.environ.get("ANTHROPIC_API_KEY"),
+            retry_policy=retry_policy,
+            timeout_s=_env_float("PETFISH_TIMEOUT_S", 30.0),
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> FrameworkConfig:
+        """Build a config from a plain dict, e.g. loaded from YAML or JSON."""
+        budget_data = data.get("default_budget")
+        if isinstance(budget_data, dict):
+            default_budget = Budget(**budget_data)
+        else:
+            default_budget = Budget()
+
+        retry_data = data.get("retry_policy")
+        if isinstance(retry_data, dict):
+            retry_policy = RetryPolicy(**retry_data)
+        else:
+            retry_policy = None
+
+        return cls(
+            default_model=data.get("default_model", "gpt-4o"),
+            default_temperature=data.get("default_temperature", 0.0),
+            default_max_tokens=data.get("default_max_tokens", None),
+            default_budget=default_budget,
+            openai_api_key=data.get("openai_api_key"),
+            anthropic_api_key=data.get("anthropic_api_key"),
+            retry_policy=retry_policy,
+            timeout_s=data.get("timeout_s", 30.0),
+        )

petfishframework/core/__init__.py

@@ -0,0 +1,91 @@
+"""Core package — thin contracts + driving loop + event stream (decision 5).
+
+Everything here depends only on stdlib + core/types. No concrete
+strategy/adapter/tool implementations. Users can vendor core/ + one
+model adapter + ReAct + one tool and get a working agent.
+"""
+from __future__ import annotations
+
+from .compiled import (
+    CompiledContext,
+    EvidenceBundle,
+    MemorySlice,
+    OutputContract,
+    TaskSpec,
+)
+from .contracts import (
+    Clearance,
+    Environment,
+    MemoryView,
+    ModelAdapter,
+    ReasoningStrategy,
+    Retriever,
+    RiskLevel,
+    RunContext,
+    Tool,
+)
+from .conversation import ConversationStore, InMemoryConversationStore
+from .events import Event, EventEmitter
+from .structured import StructuredResult, parse_json, parse_structured
+from .types import (
+    Budget,
+    BudgetExceeded,
+    Message,
+    ModelRequest,
+    ModelResponse,
+    Result,
+    Role,
+    Snippet,
+    Step,
+    Task,
+    ToolCall,
+    ToolRef,
+    ToolResult,
+    Trajectory,
+    Usage,
+)
+
+__all__ = [
+    # types
+    "Budget",
+    "BudgetExceeded",
+    "Message",
+    "ModelRequest",
+    "ModelResponse",
+    "Result",
+    "Role",
+    "Step",
+    "Snippet",
+    "Task",
+    "ToolCall",
+    "ToolRef",
+    "ToolResult",
+    "Trajectory",
+    "Usage",
+    # contracts
+    "Clearance",
+    "Environment",
+    "MemoryView",
+    "ModelAdapter",
+    "ReasoningStrategy",
+    "Retriever",
+    "RiskLevel",
+    "RunContext",
+    "Tool",
+    # conversation
+    "ConversationStore",
+    "InMemoryConversationStore",
+    # events
+    "Event",
+    "EventEmitter",
+    # structured
+    "StructuredResult",
+    "parse_json",
+    "parse_structured",
+    # compiled
+    "CompiledContext",
+    "EvidenceBundle",
+    "MemorySlice",
+    "OutputContract",
+    "TaskSpec",
+]

petfishframework/core/agent.py

@@ -0,0 +1,207 @@
+"""Agent — an immutable recipe for creating event-sourced Sessions."""
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, field, fields
+from typing import Any, TypeVar
+
+from petfishframework.core.contracts import ModelAdapter, ReasoningStrategy, Retriever, Tool
+from petfishframework.core.conversation import ConversationStore
+from petfishframework.core.events import EventEmitter
+from petfishframework.core.structured import DataclassInstance, StructuredResult, parse_structured
+from petfishframework.core.types import Budget, Message, ModelRequest, Result, Role, Task
+from petfishframework.permissions.model import DefaultAllowPolicy, PermissionPolicy
+
+from .session import Session
+
+T = TypeVar("T", bound=DataclassInstance)
+
+
+@dataclass(frozen=True)
+class Agent:
+    """Declarative agent configuration.
+
+    Agent is the recipe; Session is the execution. Users can call `run()` for
+    the simple path, or call `session()` to obtain a replayable/auditable
+    process (decision 1).
+    """
+
+    model: ModelAdapter
+    reasoning: ReasoningStrategy = field(default_factory=lambda: _default_reasoning())
+    tools: tuple[Tool, ...] = ()
+    retriever: Retriever | None = None
+    permission_policy: PermissionPolicy = field(
+        default_factory=lambda: _default_policy()
+    )
+    tool_registry: Any = None  # ToolRegistry | None — lazy typed to avoid import cycle
+
+    def run(
+        self,
+        task: str | Task,
+        budget: Budget | None = None,
+        conversation_id: str | None = None,
+        conversation_store: ConversationStore | None = None,
+    ) -> Result:
+        """Create a Session and run it, returning the Result."""
+        session = self.session(
+            task,
+            budget=budget,
+            conversation_id=conversation_id,
+            conversation_store=conversation_store,
+        )
+        return session.run()
+
+    async def run_async(
+        self,
+        task: str | Task,
+        budget: Budget | None = None,
+        conversation_id: str | None = None,
+        conversation_store: ConversationStore | None = None,
+    ) -> Result:
+        """Create an async Session and run it, returning the Result."""
+        session = await self.session_async(
+            task,
+            budget=budget,
+            conversation_id=conversation_id,
+            conversation_store=conversation_store,
+        )
+        return await session.run_async()
+
+    def run_structured(
+        self,
+        task: str | Task,
+        output_type: type[T],
+        budget: Budget | None = None,
+    ) -> StructuredResult[T]:
+        """Run the agent and parse the output as structured data (dataclass).
+
+        The task prompt is augmented with instructions to return JSON matching
+        the output_type's fields.
+        """
+        if not isinstance(output_type, type) or not hasattr(output_type, "__dataclass_fields__"):
+            raise ValueError(f"output_type must be a dataclass, got {output_type!r}")
+
+        task_obj = task if isinstance(task, Task) else Task(prompt=task)
+        field_names = [f.name for f in fields(output_type)]
+        augmented_prompt = (
+            f"{task_obj.prompt}\n\nReturn your answer as JSON with these fields: {field_names}"
+        )
+        augmented_task = Task(prompt=augmented_prompt, metadata=task_obj.metadata)
+
+        result = self.run(augmented_task, budget=budget)
+
+        try:
+            parsed = parse_structured(result.answer, output_type)
+            return StructuredResult(
+                answer=result.answer,
+                data=parsed,
+                parse_error=None,
+                session_id=result.session_id,
+            )
+        except ValueError as exc:
+            return StructuredResult(
+                answer=result.answer,
+                data=None,
+                parse_error=str(exc),
+                session_id=result.session_id,
+            )
+
+    def run_stream(
+        self,
+        task: str | Task,
+        budget: Budget | None = None,
+    ) -> Iterator[str]:
+        """Stream the agent's response as text chunks.
+
+        Yields text chunks as they arrive from the model. The final chunk
+        completes the response. Falls back to single-chunk if model doesn't support streaming.
+        """
+        task_obj = task if isinstance(task, Task) else Task(prompt=task)
+
+        if hasattr(self.model, "query_stream"):
+            request = ModelRequest(
+                messages=(Message(role=Role.USER, content=task_obj.prompt),),
+                max_tokens=budget.max_tokens if budget is not None else None,
+            )
+            # Avoid direct attribute access on the typed ModelAdapter interface.
+            stream_attr = "query_stream"
+            stream_method: Callable[[ModelRequest], Iterator[str]] = getattr(
+                self.model, stream_attr
+            )
+            yield from stream_method(request)
+        else:
+            result = self.run(task_obj, budget=budget)
+            yield result.answer
+
+    def session(
+        self,
+        task: str | Task,
+        budget: Budget | None = None,
+        conversation_id: str | None = None,
+        conversation_store: ConversationStore | None = None,
+    ) -> Session:
+        """Create a new Session from this agent's configuration.
+
+        If tool_registry is set, IntentRouter auto-selects tools based on
+        task intent (Council #1: automatic tool selection). Explicit tools
+        are always included; auto-selected tools supplement them.
+        """
+        if isinstance(task, str):
+            task = Task(prompt=task)
+
+        # Resolve tools: explicit + auto-selected from registry
+        resolved_tools = self.tools
+        if self.tool_registry is not None:
+            from petfishframework.tools.registry import IntentRouter
+
+            router = IntentRouter()
+            auto_tools = router.route(task, self.tool_registry)
+            # Merge: explicit tools + auto-selected (deduplicate by name)
+            explicit_names = {t.name for t in resolved_tools}
+            for t in auto_tools:
+                if t.name not in explicit_names:
+                    resolved_tools = resolved_tools + (t,)
+
+        events = EventEmitter()
+        return Session(
+            model=self.model,
+            reasoning=self.reasoning,
+            tools=resolved_tools,
+            retriever=self.retriever,
+            policy=self.permission_policy,
+            task=task,
+            budget=budget,
+            events=events,
+            conversation_id=conversation_id,
+            conversation_store=conversation_store,
+        )
+
+    async def session_async(
+        self,
+        task: str | Task,
+        budget: Budget | None = None,
+        conversation_id: str | None = None,
+        conversation_store: ConversationStore | None = None,
+    ) -> Session:
+        """Create a new Session flagged for async execution.
+
+        The returned Session is identical to the sync session(); the async flag
+        is implicit in calling run_async() on it.
+        """
+        return self.session(
+            task,
+            budget=budget,
+            conversation_id=conversation_id,
+            conversation_store=conversation_store,
+        )
+
+
+def _default_reasoning() -> ReasoningStrategy:
+    # Import lazily to avoid reasoning -> core cycle at import time.
+    from petfishframework.reasoning.react import ReAct
+
+    return ReAct()
+
+
+def _default_policy() -> PermissionPolicy:
+    return DefaultAllowPolicy()

petfishframework/core/compiled.py

@@ -0,0 +1,89 @@
+"""Contract compilation types (v0.2 — absorbed from contract-driven-harness-study).
+
+The Environment compiles these BEFORE the model runs. The model operates
+within these bounds — it is a component inside a contract system, not the
+sole source of control. This externalizes reliability obligations into
+explicit, inspectable contracts.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class TaskSpec:
+    """Compiled task specification.
+
+    Boundaries, success/failure conditions, and forbidden actions.
+    Produced by the Environment's intent-routing + compilation step.
+    """
+
+    task_type: str = "generic"
+    success_criteria: str = ""
+    forbidden_actions: tuple[str, ...] = ()
+    requires_sources: bool = False
+    max_autonomy: str = "full"  # full | bounded | supervised
+
+
+@dataclass(frozen=True)
+class MemorySlice:
+    """Bounded memory slice delivered to the strategy.
+
+    Topic-filtered + TTL-applied + conflict-resolved. This is what the
+    strategy sees, not the raw memory store.
+    """
+
+    entries: tuple[dict[str, Any], ...] = ()
+    topic: str = ""
+    ttl_s: float | None = None
+
+
+@dataclass(frozen=True)
+class SourceRef:
+    """A reference to an evidence source."""
+
+    source_id: str
+    source_type: str = ""  # doc, url, tool_output, etc.
+    trust_tier: str = "unverified"
+
+
+@dataclass(frozen=True)
+class EvidenceBundle:
+    """Evidence with source provenance and trust tiers.
+
+    Produced by the Retriever (Environment.retrieve). The strategy receives
+    this compiled bundle, not raw retrieval access.
+    """
+
+    snippets: tuple[Any, ...] = ()  # Snippet objects from retrieval
+    sources: tuple[SourceRef, ...] = ()
+    requires_citation: bool = False
+
+
+@dataclass(frozen=True)
+class OutputContract:
+    """Output requirements the result must satisfy.
+
+    Required sections, format, and validation rules. The ValidatorGate
+    (reliability/) checks results against this contract.
+    """
+
+    required_sections: tuple[str, ...] = ()
+    format: str = "text"  # text | json | markdown
+    max_length: int | None = None
+    validation_rules: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class CompiledContext:
+    """All four contract objects, compiled before strategy.run().
+
+    This is the v0.2 contract compilation layer (decision 3 enrichment).
+    Passed to RunContext.compiled so strategies can inspect their bounds.
+    """
+
+    task_spec: TaskSpec = field(default_factory=TaskSpec)
+    memory_slice: MemorySlice = field(default_factory=MemorySlice)
+    evidence_bundle: EvidenceBundle = field(default_factory=EvidenceBundle)
+    output_contract: OutputContract = field(default_factory=OutputContract)