petfishframework 0.1.0__py3-none-any.whl

petfishframework/models/openai.py

@@ -0,0 +1,178 @@
+"""OpenAI model adapter for the ModelAdapter protocol.
+
+The ``openai`` package is imported lazily inside ``OpenAIModel.__init__`` so the
+framework core remains free of the optional OpenAI dependency at import time.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from petfishframework.core.contracts import ModelAdapter
+from petfishframework.core.types import (
+    Message,
+    ModelRequest,
+    ModelResponse,
+    Role,
+    ToolCall,
+    Usage,
+)
+
+
+class OpenAIModel(ModelAdapter):
+    """Adapter that queries OpenAI-compatible chat completion APIs."""
+
+    def __init__(
+        self,
+        model: str = "gpt-4o",
+        api_key: str | None = None,
+        base_url: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Create an OpenAI adapter with a lazily imported OpenAI client.
+
+        Args:
+            model: The OpenAI model name (e.g. ``gpt-4o``).
+            api_key: OpenAI API key. If not provided, ``OPENAI_API_KEY`` is used.
+            base_url: Optional custom base URL for the OpenAI API.
+            **kwargs: Additional keyword arguments forwarded to ``openai.OpenAI``.
+
+        Raises:
+            ImportError: If the ``openai`` package is not installed.
+            ValueError: If no API key is available.
+        """
+        try:
+            import openai
+            from openai import OpenAI
+        except ImportError as exc:
+            raise ImportError(
+                "The 'openai' package is required to use OpenAIModel. "
+                "Install it with 'pip install petfishframework[openai]'."
+            ) from exc
+
+        resolved_key = api_key if api_key is not None else os.environ.get("OPENAI_API_KEY")
+        if resolved_key is None:
+            raise ValueError(
+                "OpenAIModel requires an api_key or the OPENAI_API_KEY environment variable."
+            )
+
+        resolved_base_url = base_url if base_url is not None else os.environ.get("OPENAI_BASE_URL")
+
+        self.name = model
+        self._model = model
+        self._openai = openai
+        self._client = OpenAI(api_key=resolved_key, base_url=resolved_base_url, **kwargs)
+
+    def query(self, request: ModelRequest) -> ModelResponse:
+        """Send a chat completion request and convert the response."""
+        messages = self._build_messages(request.messages)
+        tools = self._build_tools(request.tools, request.tool_schemas)
+
+        params: dict[str, Any] = {
+            "model": self._model,
+            "messages": messages,
+            "temperature": request.temperature,
+        }
+        if request.max_tokens is not None:
+            params["max_tokens"] = request.max_tokens
+        if tools:
+            params["tools"] = tools
+
+        try:
+            response = self._client.chat.completions.create(**params)
+        except (self._openai.APIError, self._openai.RateLimitError) as exc:
+            raise RuntimeError(f"OpenAI API error: {exc}") from exc
+
+        return self._build_response(response)
+
+    def _build_messages(self, messages: tuple[Message, ...]) -> list[dict[str, Any]]:
+        """Convert framework messages to the OpenAI chat message format."""
+        openai_messages: list[dict[str, Any]] = []
+        for msg in messages:
+            entry: dict[str, Any] = {
+                "role": msg.role.value,
+                "content": msg.content,
+            }
+            if msg.tool_calls and msg.role is Role.ASSISTANT:
+                entry["tool_calls"] = [
+                    {
+                        "id": tool_call.id,
+                        "type": "function",
+                        "function": {
+                            "name": tool_call.name,
+                            "arguments": json.dumps(tool_call.arguments),
+                        },
+                    }
+                    for tool_call in msg.tool_calls
+                ]
+            if msg.role is Role.TOOL and msg.tool_call_id is not None:
+                entry["tool_call_id"] = msg.tool_call_id
+            openai_messages.append(entry)
+        return openai_messages
+
+    def _build_tools(
+        self, tool_names: tuple[str, ...], tool_schemas: tuple[dict, ...] = ()
+    ) -> list[dict[str, Any]] | None:
+        """Convert tool definitions to OpenAI function-calling format.
+
+        Uses full schemas (name + description + parameters) when available.
+        Falls back to name-only if schemas not provided.
+        """
+        if not tool_names and not tool_schemas:
+            return None
+        if tool_schemas:
+            return [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": s.get("name", ""),
+                        "description": s.get("description", ""),
+                        "parameters": s.get("input_schema", {"type": "object", "properties": {}}),
+                    },
+                }
+                for s in tool_schemas
+            ]
+        return [
+            {"type": "function", "function": {"name": name}}
+            for name in tool_names
+        ]
+
+    def _build_response(self, response: Any) -> ModelResponse:
+        """Convert an OpenAI chat completion response to a ModelResponse."""
+        choice = response.choices[0]
+        message = choice.message
+
+        tool_calls: tuple[ToolCall, ...] = ()
+        if message.tool_calls:
+            parsed_calls: list[ToolCall] = []
+            for tool_call in message.tool_calls:
+                raw_args = tool_call.function.arguments
+                try:
+                    args = json.loads(raw_args) if raw_args else {}
+                except (json.JSONDecodeError, TypeError):
+                    # Some providers (e.g. SiliconFlow/Qwen) return non-standard JSON.
+                    # Fall back to wrapping the raw string in a dict.
+                    args = {"_raw": raw_args} if raw_args else {}
+                parsed_calls.append(
+                    ToolCall(
+                        id=tool_call.id,
+                        name=tool_call.function.name,
+                        arguments=args,
+                    )
+                )
+            tool_calls = tuple(parsed_calls)
+
+        usage = Usage(
+            input_tokens=response.usage.prompt_tokens,
+            output_tokens=response.usage.completion_tokens,
+            total_tokens=response.usage.total_tokens,
+        )
+
+        return ModelResponse(
+            content=message.content or "",
+            tool_calls=tool_calls,
+            usage=usage,
+            finish_reason=choice.finish_reason or "stop",
+            raw=response,
+        )

petfishframework/observability/__init__.py

@@ -0,0 +1,10 @@
+"""Observability sinks consume the shared event stream.
+
+Skeleton scope: ListSink for tests/audit and ConsoleSink for debugging.
+OTel/LangSmith exporters are TODO.
+"""
+from __future__ import annotations
+
+from .sinks import ConsoleSink, ListSink
+
+__all__ = ["ConsoleSink", "ListSink"]

petfishframework/observability/sinks.py

@@ -0,0 +1,23 @@
+"""Basic EventEmitter sinks."""
+from __future__ import annotations
+
+import sys
+
+from petfishframework.core.events import Event
+
+
+class ListSink:
+    """Collects emitted events into a list for testing and audit."""
+
+    def __init__(self) -> None:
+        self.events: list[Event] = []
+
+    def __call__(self, event: Event) -> None:
+        self.events.append(event)
+
+
+class ConsoleSink:
+    """Prints emitted events to stderr for debugging."""
+
+    def __call__(self, event: Event) -> None:
+        print(event, file=sys.stderr)

petfishframework/permissions/__init__.py

@@ -0,0 +1,32 @@
+"""Permissions package — SARC access control model (v0.2 — absorbed from agentShield-dev).
+
+Do not constrain model thoughts. Constrain model behavior.
+
+The skeleton ships DecisionEffect(6) + SARC types + a DefaultAllow policy.
+The two-gate model (CapabilityProjection visibility + ToolCallMonitor invocation)
+is structurally present but defaults to allow. Concrete enforcement, CapabilityGrant,
+and CredentialBroker are TODO (see skeleton-completeness-checklist.md).
+"""
+from __future__ import annotations
+
+from .model import (
+    AccessContext,
+    Action,
+    Decision,
+    DecisionEffect,
+    DefaultAllowPolicy,
+    PermissionPolicy,
+    Resource,
+    Subject,
+)
+
+__all__ = [
+    "AccessContext",
+    "Action",
+    "Decision",
+    "DecisionEffect",
+    "DefaultAllowPolicy",
+    "PermissionPolicy",
+    "Resource",
+    "Subject",
+]

petfishframework/permissions/model.py

@@ -0,0 +1,110 @@
+"""SARC access control model — Subject/Action/Resource/Context (v0.2).
+
+Absorbed from agentShield-dev's battle-tested runtime access control.
+Six DecisionEffect values replace binary allow/deny, enabling field-level
+masking, partial allows, human-in-the-loop approval, and degradation.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Protocol
+
+
+class DecisionEffect(Enum):
+    """Six effect values (not binary allow/deny). From agentShield-dev.
+
+    ALLOW            — full access
+    DENY             — no access (default for unmatched)
+    MASK             — return masked value [MASKED:classification]
+    PARTIAL_ALLOW    — only some arguments/fields permitted
+    REQUIRE_APPROVAL — needs human approval before proceeding
+    DEGRADE          — downgrade response quality (e.g. high-risk audit fail)
+    """
+
+    ALLOW = "allow"
+    DENY = "deny"
+    MASK = "mask"
+    PARTIAL_ALLOW = "partial_allow"
+    REQUIRE_APPROVAL = "require_approval"
+    DEGRADE = "degrade"
+
+
+# ---------------------------------------------------------------------------
+# SARC model (Subject-Action-Resource-Context)
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class Subject:
+    """Who is requesting (the agent/user identity vector)."""
+
+    user_id: str = "anonymous"
+    roles: tuple[str, ...] = ()
+    clearance: str = "public"  # matches Clearance enum values
+    projects: tuple[str, ...] = ()
+    tenant_id: str = "default"
+
+
+@dataclass(frozen=True)
+class Action:
+    """What operation is being requested."""
+
+    type: str  # read | call | write | execute | retrieve | send
+    tool_name: str | None = None
+    args: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Resource:
+    """What is being acted upon."""
+
+    type: str = "tool"  # tool | data | output | model
+    classification: str = "public"
+    tags: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class AccessContext:
+    """Runtime conditions for the decision."""
+
+    session_id: str = ""
+    prompt_risk: float = 0.0
+    session_risk: float = 0.0
+    step: int = 0
+
+
+@dataclass(frozen=True)
+class Decision:
+    """An authorization decision with effect, reason, and constraints."""
+
+    effect: DecisionEffect
+    reason: str = ""
+    allowed_fields: tuple[str, ...] | None = None  # for PARTIAL_ALLOW
+    masked_fields: tuple[str, ...] | None = None  # for MASK
+    constraints: dict[str, Any] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Permission policy contract
+# ---------------------------------------------------------------------------
+
+class PermissionPolicy(Protocol):
+    """Evaluates authorization decisions. Implementations plug in SARC backends."""
+
+    def evaluate(self, subject: Subject, action: Action, resource: Resource, context: AccessContext) -> Decision:
+        ...
+
+
+@dataclass
+class DefaultAllowPolicy:
+    """Skeleton default: allow everything. Real policies replace this.
+
+    The gate STRUCTURE exists (Environment calls this before every tool
+    invocation) but defaults to ALLOW. This ensures the permission chokepoint
+    is wired from day one — flipping to deny-by-default is a config change,
+    not an architecture change.
+    """
+
+    def evaluate(self, subject: Subject, action: Action, resource: Resource, context: AccessContext) -> Decision:
+        # Skeleton: allow all. TODO: wire SARC policy engine + two-gate model.
+        return Decision(effect=DecisionEffect.ALLOW, reason="default_allow_policy")

petfishframework/reasoning/__init__.py

@@ -0,0 +1,13 @@
+"""Reasoning strategies — pluggable search algorithms over Environment.
+
+V2 adds LATS (Language Agent Tree Search) and LLM+P (LLM + Symbolic Planner)
+next to ReAct, validating that all three fit the same ReasoningStrategy
+interface without modifying core contracts.
+"""
+from __future__ import annotations
+
+from .lats import LATS
+from .llm_plus_p import LLMPlusP
+from .react import ReAct
+
+__all__ = ["LATS", "LLMPlusP", "ReAct"]

petfishframework/reasoning/lats.py

@@ -0,0 +1,222 @@
+"""LATS (Language Agent Tree Search) reasoning strategy — V2 simplified.
+
+This is a deliberately simplified LATS that validates the ReasoningStrategy
+interface fit (decision 3 / open question 2). It generates candidate next
+actions, scores them with the model, selects the best, executes it, and
+repeats. Full MCTS with UCB/rollout/backpropagation is Phase 4.
+
+All capability access flows through ctx.env; the Environment interface is
+completely unchanged.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from petfishframework.core.contracts import ReasoningStrategy
+from petfishframework.core.types import (
+    BudgetExceeded,
+    Message,
+    ModelRequest,
+    Result,
+    Role,
+    Step,
+    ToolCall,
+    ToolRef,
+    Trajectory,
+    Usage,
+)
+
+
+@dataclass
+class LATS(ReasoningStrategy):
+    """Simplified Language Agent Tree Search over the Environment.
+
+    Fields:
+        breadth: Number of candidate next actions generated per expansion.
+        max_depth: Maximum search depth (tool-execution steps).
+        name: Strategy identifier.
+    """
+
+    breadth: int = 3
+    max_depth: int = 5
+    name: str = "lats"
+
+    def run(self, ctx) -> Result:
+        """Run the simplified LATS loop within the provided RunContext."""
+        tools = ctx.env.tools()
+        tool_names = tuple(t.name for t in tools)
+
+        system_prompt = self._system_prompt(tools)
+        messages = [
+            Message(role=Role.SYSTEM, content=system_prompt),
+            Message(role=Role.USER, content=ctx.task.prompt),
+        ]
+
+        steps: list[Step] = []
+        usage = Usage()
+        max_depth = ctx.budget.max_steps if ctx.budget.max_steps is not None else self.max_depth
+
+        try:
+            for depth in range(max_depth):
+                # -----------------------------------------------------------------
+                # 1. Expand: generate candidate next actions.
+                # -----------------------------------------------------------------
+                expand_request = ModelRequest(messages=tuple(messages), tools=tool_names)
+                expand_response = ctx.env.query_model(expand_request)
+                usage = usage.add(expand_response.usage)
+
+                candidates = expand_response.tool_calls
+                ctx.events.emit(
+                    "lats.expand",
+                    {
+                        "depth": depth,
+                        "breadth": self.breadth,
+                        "candidate_count": len(candidates),
+                    },
+                )
+
+                # Termination: model produced a final answer without tool calls.
+                if not candidates:
+                    steps.append(Step(thought=expand_response.content))
+                    return Result(
+                        answer=expand_response.content,
+                        trajectory=Trajectory(steps=tuple(steps)),
+                        usage=usage,
+                    )
+
+                # Limit candidates to configured breadth.
+                candidates = candidates[: self.breadth]
+
+                # -----------------------------------------------------------------
+                # 2. Evaluate: score each candidate.
+                # -----------------------------------------------------------------
+                scored: list[tuple[ToolCall, float]] = []
+                for candidate in candidates:
+                    score, score_usage = self._score_candidate(
+                        ctx,
+                        messages,
+                        candidate,
+                    )
+                    usage = usage.add(score_usage)
+                    scored.append((candidate, score))
+                    ctx.events.emit(
+                        "lats.evaluate",
+                        {
+                            "depth": depth,
+                            "tool_name": candidate.name,
+                            "tool_args": candidate.arguments,
+                            "score": score,
+                        },
+                    )
+
+                # -----------------------------------------------------------------
+                # 3. Select: highest-scoring candidate.
+                # -----------------------------------------------------------------
+                best_candidate, best_score = max(scored, key=lambda item: item[1])
+                ctx.events.emit(
+                    "lats.select",
+                    {
+                        "depth": depth,
+                        "tool_name": best_candidate.name,
+                        "tool_args": best_candidate.arguments,
+                        "score": best_score,
+                    },
+                )
+
+                # -----------------------------------------------------------------
+                # 4. Execute: run the selected action and observe.
+                # -----------------------------------------------------------------
+                tool_result = ctx.env.call(
+                    ToolRef(name=best_candidate.name),
+                    best_candidate.arguments,
+                )
+                observation = (
+                    tool_result.error if tool_result.error is not None else str(tool_result.value)
+                )
+                steps.append(
+                    Step(
+                        thought=f"Depth {depth}: selected {best_candidate.name} "
+                        f"with score {best_score}",
+                        tool_name=best_candidate.name,
+                        tool_args=best_candidate.arguments,
+                        observation=observation,
+                    )
+                )
+
+                # Append selected action + observation to conversation history.
+                messages.append(
+                    Message(
+                        role=Role.ASSISTANT,
+                        content=f"Selected action: {best_candidate.name}({best_candidate.arguments})",
+                        tool_calls=(best_candidate,),
+                    )
+                )
+                messages.append(
+                    Message(
+                        role=Role.TOOL,
+                        content=observation,
+                        tool_call_id=best_candidate.id,
+                    )
+                )
+        except BudgetExceeded:
+            # Hard budget hit: return whatever trajectory we have so far.
+            return Result(
+                answer=messages[-1].content if messages else "",
+                trajectory=Trajectory(steps=tuple(steps)),
+                usage=usage,
+            )
+
+        # Max depth reached without a final answer — return the best observation.
+        final_answer = messages[-1].content if messages else ""
+        return Result(
+            answer=final_answer,
+            trajectory=Trajectory(steps=tuple(steps)),
+            usage=usage,
+        )
+
+    def _score_candidate(
+        self,
+        ctx,
+        messages: list[Message],
+        candidate: ToolCall,
+    ) -> tuple[float, Usage]:
+        """Ask the model to score a candidate action on a 0-10 scale."""
+        scoring_messages = list(messages) + [
+            Message(
+                role=Role.USER,
+                content=(
+                    f"Candidate action: {candidate.name}({candidate.arguments}).\n"
+                    "Rate how useful this action is for completing the task, "
+                    "on a scale from 0 to 10. Respond with just a number."
+                ),
+            )
+        ]
+        request = ModelRequest(messages=tuple(scoring_messages), tools=())
+        response = ctx.env.query_model(request)
+        score = self._parse_score(response.content)
+        return score, response.usage
+
+    @staticmethod
+    def _parse_score(content: str) -> float:
+        """Extract the first numeric value from a scoring response."""
+        match = re.search(r"\d+(?:\.\d+)?", content)
+        if match:
+            return float(match.group())
+        return 0.0
+
+    def _system_prompt(self, tools: list) -> str:
+        """Build a system prompt describing available tools and the LATS protocol."""
+        tool_lines = []
+        for tool in tools:
+            tool_lines.append(f"- {tool.name}: {tool.description}")
+        tool_text = "\n".join(tool_lines) if tool_lines else "(no tools available)"
+
+        return (
+            "You are a helpful assistant that searches for the best next action.\n"
+            "Available tools:\n" + tool_text + "\n"
+            "When asked for candidate actions, respond with up to "
+            f"{self.breadth} tool calls. "
+            "When asked to rate a candidate, respond with a single number 0-10. "
+            "When you have enough information, respond with plain text and no tool calls."
+        )