petfishframework 0.1.0__py3-none-any.whl

petfishframework/retrieval/__init__.py

@@ -0,0 +1,12 @@
+"""Retrieval package — base store, CRAG, and Adaptive-RAG strategies."""
+from __future__ import annotations
+
+from .adaptive import AdaptiveRetriever
+from .crag import CRAGRetriever
+from .memory_store import MemoryRetriever
+
+__all__ = [
+    "AdaptiveRetriever",
+    "CRAGRetriever",
+    "MemoryRetriever",
+]

petfishframework/retrieval/adaptive.py

@@ -0,0 +1,137 @@
+"""Adaptive-RAG retriever implementation.
+
+Reference: Jeong et al., "Adaptive-RAG: Learning to Adapt Retrieval-Augmented
+Large Language Models through Question Complexity", arXiv:2403.14403.
+
+The core loop is:
+
+1. Classify query complexity (no-retrieval / single-step / multi-step).
+2. Route to the appropriate retrieval strategy.
+   - no_retrieval -> no context needed; return []
+   - single_step  -> one retrieval pass
+   - multi_step   -> iterative retrieval with sub-queries
+
+This module implements that flow purely through the ``Retriever`` protocol
+so no changes to ``core/`` are required.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Callable
+
+from petfishframework.core.contracts import Retriever
+from petfishframework.core.events import EventEmitter
+from petfishframework.core.types import Snippet
+
+
+def _default_classifier(query: str) -> str:
+    """Heuristic classifier used when no model-based classifier is supplied."""
+    lower = query.lower()
+
+    # Multi-step signals: composition, comparison, or analysis.
+    multi_step_patterns = (
+        r"\bcompare\b",
+        r"\bcontrasting\b",
+        r"\banalyze\b",
+        r"\bexplain\b.*\band\b.*\bhow\b",
+        r"\bbetween\b.*\band\b",
+        r"\bdifference\b.*\band\b",
+        r"\bsummarize\b.*\bthen\b",
+    )
+    for pattern in multi_step_patterns:
+        if re.search(pattern, lower):
+            return "multi_step"
+
+    # Single-step signals: factual lookup.
+    single_step_patterns = (
+        r"^(what|who|when|where|which|how many|how much|define)\b",
+    )
+    for pattern in single_step_patterns:
+        if re.search(pattern, lower):
+            return "single_step"
+
+    return "no_retrieval"
+
+
+@dataclass
+class AdaptiveRetriever(Retriever):
+    """Adaptive RAG retriever.
+
+    Wraps any ``Retriever`` and optionally a complexity classifier.
+    Depending on the classification, it performs no retrieval, a single
+    retrieval, or a simple iterative multi-step retrieval.
+    """
+
+    base_retriever: Retriever
+    classifier: Callable[[str], str] | None = None
+    events: EventEmitter | None = field(default=None, repr=False)
+
+    def retrieve(self, query: str, top_k: int = 5) -> list[Snippet]:
+        """Classify query complexity and route to the matching strategy."""
+        classify_fn = self.classifier or _default_classifier
+        classification = classify_fn(query)
+
+        if self.events is not None:
+            self.events.emit(
+                "adaptive.classify",
+                {"query": query, "classification": classification},
+            )
+
+        strategy: str
+        snippets: list[Snippet]
+
+        if classification == "no_retrieval":
+            strategy = "none"
+            snippets = []
+        elif classification == "multi_step":
+            strategy = "iterative"
+            snippets = self._iterative_retrieval(query, top_k)
+        else:  # single_step (default)
+            strategy = "single"
+            snippets = self.base_retriever.retrieve(query, top_k)
+
+        if self.events is not None:
+            self.events.emit(
+                "adaptive.route",
+                {
+                    "query": query,
+                    "classification": classification,
+                    "strategy": strategy,
+                    "snippet_count": len(snippets),
+                },
+            )
+
+        return snippets
+
+    def _iterative_retrieval(self, query: str, top_k: int) -> list[Snippet]:
+        """Skeleton multi-step retrieval: two rounds with deduplication.
+
+        Round 1 uses the original query. Round 2 uses a refined query built
+        from the top result of round 1. This is intentionally simple to keep
+        the skeleton dependency-free and deterministic.
+        """
+        first_pass = self.base_retriever.retrieve(query, top_k)
+
+        # Build a simple refined query by appending key terms from the
+        # highest-scoring snippet. If there are no first-pass results, stop.
+        if not first_pass:
+            return []
+
+        top_snippet = first_pass[0]
+        top_terms = " ".join(sorted(top_snippet.content.split()[:5]))
+        refined_query = f"{query} {top_terms}".strip()
+
+        second_pass = self.base_retriever.retrieve(refined_query, top_k)
+
+        # Merge and deduplicate by content, preserving score order.
+        seen: set[str] = set()
+        merged: list[Snippet] = []
+        for snippet in first_pass + second_pass:
+            if snippet.content not in seen:
+                seen.add(snippet.content)
+                merged.append(snippet)
+                if len(merged) >= top_k:
+                    break
+
+        return merged

petfishframework/retrieval/crag.py

@@ -0,0 +1,135 @@
+"""CRAG (Corrective RAG) retriever implementation.
+
+Reference: Yan et al., "Corrective Retrieval Augmented Generation",
+arXiv:2401.15884. The core loop is:
+
+1. Retrieve from a base retriever.
+2. Evaluate retrieval quality (relevant / ambiguous / irrelevant).
+3. Route:
+   - relevant   -> return retrieved docs
+   - ambiguous  -> combine retrieved docs with external knowledge
+   - irrelevant -> replace retrieved docs with external knowledge
+
+This module implements that flow purely through the ``Retriever`` protocol
+so no changes to ``core/`` are required.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from petfishframework.core.contracts import Retriever
+from petfishframework.core.events import EventEmitter
+from petfishframework.core.types import Snippet
+
+
+def _default_evaluator(query: str, snippets: list[Snippet]) -> str:
+    """Heuristic evaluator used when no model-based evaluator is supplied.
+
+    Thresholds mirror the CRAG paper's intent but use query-relative keyword
+    coverage rather than the normalized document score. This gives crisper
+    separation between relevant, ambiguous, and irrelevant retrievals.
+    """
+    if not snippets:
+        return "irrelevant"
+
+    from petfishframework.retrieval.memory_store import _tokenize
+
+    query_tokens = _tokenize(query)
+    if not query_tokens:
+        return "irrelevant"
+
+    def _coverage(snippet: Snippet) -> float:
+        snippet_tokens = _tokenize(snippet.content)
+        shared = query_tokens & snippet_tokens
+        return len(shared) / len(query_tokens)
+
+    best_coverage = max(_coverage(snippet) for snippet in snippets)
+    if best_coverage >= 0.5:
+        return "relevant"
+    if best_coverage >= 0.2:
+        return "ambiguous"
+    return "irrelevant"
+
+
+def _default_web_search(query: str) -> list[Snippet]:
+    """Stub web-search fallback.
+
+    Returns an empty list. Production systems can inject a real search tool
+    here without touching CRAG's routing logic.
+    """
+    return []
+
+
+@dataclass
+class CRAGRetriever(Retriever):
+    """Corrective RAG retriever.
+
+    Wraps any ``Retriever`` and optionally an evaluator and web-search
+    fallback. When the evaluator decides the base retrieval is poor, CRAG
+    routes to the external knowledge source rather than passing bad evidence
+    downstream.
+    """
+
+    base_retriever: Retriever
+    evaluator: Callable[[str, list[Snippet]], str] | None = None
+    web_search: Callable[[str], list[Snippet]] | None = None
+    events: EventEmitter | None = field(default=None, repr=False)
+
+    def retrieve(self, query: str, top_k: int = 5) -> list[Snippet]:
+        """Retrieve, evaluate quality, and route to the appropriate source."""
+        base_snippets = self.base_retriever.retrieve(query, top_k)
+
+        evaluate_fn = self.evaluator or _default_evaluator
+        assessment = evaluate_fn(query, base_snippets)
+
+        if self.events is not None:
+            self.events.emit(
+                "crag.evaluate",
+                {"query": query, "assessment": assessment, "snippet_count": len(base_snippets)},
+            )
+
+        web_snippets: list[Snippet] = []
+        final_snippets: list[Snippet]
+        action: str
+
+        if assessment == "relevant":
+            final_snippets = base_snippets
+            action = "use_base"
+        elif assessment == "ambiguous":
+            search_fn = self.web_search or _default_web_search
+            web_snippets = search_fn(query)
+            final_snippets = self._merge(base_snippets, web_snippets, top_k)
+            action = "combine"
+        else:  # irrelevant
+            search_fn = self.web_search or _default_web_search
+            final_snippets = search_fn(query)
+            action = "fallback"
+
+        if self.events is not None:
+            self.events.emit(
+                "crag.route",
+                {
+                    "query": query,
+                    "assessment": assessment,
+                    "action": action,
+                    "base_count": len(base_snippets),
+                    "web_count": len(web_snippets),
+                    "final_count": len(final_snippets),
+                },
+            )
+
+        return final_snippets
+
+    @staticmethod
+    def _merge(base: list[Snippet], web: list[Snippet], top_k: int) -> list[Snippet]:
+        """Merge two snippet lists, deduplicate by content, and truncate."""
+        seen: set[str] = set()
+        merged: list[Snippet] = []
+        for snippet in base + web:
+            if snippet.content not in seen:
+                seen.add(snippet.content)
+                merged.append(snippet)
+                if len(merged) >= top_k:
+                    break
+        return merged

petfishframework/retrieval/memory_store.py

@@ -0,0 +1,72 @@
+"""Simple in-memory retriever used as a base for CRAG and Adaptive-RAG.
+
+No external vector DB required: scoring uses keyword overlap normalized by
+document length. This keeps the skeleton lightweight while still providing a
+plausible Retriever protocol implementation.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from petfishframework.core.contracts import Retriever
+from petfishframework.core.types import Snippet
+
+
+def _tokenize(text: str) -> set[str]:
+    """Lower-case, alphanumeric tokens of at least two characters."""
+    return {token for token in re.findall(r"[a-zA-Z0-9]+", text.lower()) if len(token) >= 2}
+
+
+@dataclass
+class MemoryRetriever(Retriever):
+    """In-memory retriever with keyword-overlap scoring.
+
+    Implements the ``Retriever`` protocol so it can be wrapped by CRAG and
+    Adaptive-RAG strategies without any changes to ``core/``.
+    """
+
+    _documents: list[dict[str, Any]] = field(default_factory=list, repr=False)
+
+    def add(self, content: str, metadata: dict[str, Any] | None = None) -> None:
+        """Add a document to the in-memory store."""
+        self._documents.append(
+            {
+                "content": content,
+                "metadata": metadata or {},
+            },
+        )
+
+    def retrieve(self, query: str, top_k: int = 5) -> list[Snippet]:
+        """Return the top_k documents by keyword overlap score.
+
+        Score = (count of shared query tokens in doc) / (doc token count).
+        """
+        query_tokens = _tokenize(query)
+        if not query_tokens or not self._documents:
+            return []
+
+        scored: list[tuple[float, Snippet]] = []
+        for doc in self._documents:
+            content = doc["content"]
+            doc_tokens = _tokenize(content)
+            if not doc_tokens:
+                continue
+
+            shared = len(query_tokens & doc_tokens)
+            score = shared / len(doc_tokens)
+            scored.append(
+                (
+                    score,
+                    Snippet(
+                        content=content,
+                        source=doc["metadata"].get("source", ""),
+                        score=score,
+                        metadata=doc["metadata"],
+                    ),
+                ),
+            )
+
+        scored.sort(key=lambda item: item[0], reverse=True)
+        return [snippet for _, snippet in scored[:top_k]]

petfishframework/tools/__init__.py

@@ -0,0 +1,12 @@
+"""Tools — native Python wrappers matching the MCP-shaped Tool contract.
+
+Skeleton scope: BaseTool wrapper + calculator demonstration.
+"""
+from __future__ import annotations
+
+from .agent_tool import AgentAsTool
+from .base import BaseTool, tool
+from .calculator import Calculator
+from .word_sorter import WordSorter
+
+__all__ = ["AgentAsTool", "BaseTool", "Calculator", "WordSorter", "tool"]

petfishframework/tools/agent_tool.py

@@ -0,0 +1,47 @@
+"""Agent-as-Tool wrapper enabling multi-agent delegation.
+
+A supervisor agent can delegate work to a sub-agent by treating the sub-agent
+as just another tool. The sub-agent runs through the full framework
+(Session, Environment, events, budget) with its own budget, while the
+supervisor sees only the returned answer as a tool result.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from petfishframework.core.agent import Agent
+from petfishframework.core.contracts import RiskLevel
+from petfishframework.core.types import ToolResult
+
+
+class AgentAsTool:
+    """Wrap an Agent so it can be invoked as a Tool by another agent."""
+
+    def __init__(
+        self,
+        agent: Agent,
+        name: str = "sub_agent",
+        description: str = "Delegate a task to a sub-agent",
+        risk_level: RiskLevel = RiskLevel.MEDIUM,
+        capabilities: tuple[str, ...] = (),
+    ) -> None:
+        self._agent = agent
+        self.name = name
+        self.description = description
+        self.input_schema = {
+            "task": {
+                "type": "string",
+                "description": "The task to delegate to the sub-agent",
+            }
+        }
+        self.risk_level = risk_level
+        self.capabilities = capabilities
+
+    def execute(self, args: dict[str, Any]) -> ToolResult:
+        """Run the wrapped agent with the supplied task and return its answer."""
+        task = args.get("task", "")
+        try:
+            result = self._agent.run(task)
+            return ToolResult(value=result.answer)
+        except Exception as exc:  # noqa: BLE001
+            return ToolResult(error=str(exc))

petfishframework/tools/base.py

@@ -0,0 +1,75 @@
+"""Base tool wrapper that turns a Python callable into the Tool protocol.
+
+Native tools and MCP tools both satisfy the same contract (decision 2):
+name/description/input_schema/risk_level/capabilities + execute(args).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from petfishframework.core.contracts import RiskLevel
+from petfishframework.core.types import ToolResult
+
+
+@dataclass
+class BaseTool:
+    """Concrete wrapper implementing the Tool protocol.
+
+    All fields have defaults so subclasses can override them safely.
+    """
+
+    name: str = "tool"
+    description: str = ""
+    input_schema: dict[str, Any] = field(default_factory=dict)
+    risk_level: RiskLevel = RiskLevel.LOW
+    capabilities: tuple[str, ...] = ()
+    _func: Callable[[dict[str, Any]], ToolResult] = field(
+        default_factory=lambda: _not_implemented,
+        compare=False,
+        repr=False,
+    )
+
+    def execute(self, args: dict[str, Any]) -> ToolResult:
+        """Execute the wrapped function."""
+        return self._func(args)
+
+
+def _not_implemented(_args: dict[str, Any]) -> ToolResult:
+    return ToolResult(error="tool not implemented")
+
+
+def tool(
+    name: str,
+    description: str,
+    input_schema: dict[str, Any] | None = None,
+    risk_level: RiskLevel = RiskLevel.LOW,
+    capabilities: tuple[str, ...] = (),
+) -> Callable[[Callable[..., Any]], BaseTool]:
+    """Decorator that wraps a function as a BaseTool.
+
+    Example:
+        @tool("echo", "Echo the input", {"type": "object", "properties": {"x": {"type": "string"}}})
+        def echo(x: str) -> str:
+            return x
+    """
+    schema = input_schema if input_schema is not None else {"type": "object", "properties": {}}
+
+    def decorator(func: Callable[..., Any]) -> BaseTool:
+        def wrapper(args: dict[str, Any]) -> ToolResult:
+            try:
+                value = func(**args)
+                return ToolResult(value=value)
+            except Exception as exc:  # noqa: BLE001
+                return ToolResult(error=str(exc))
+
+        return BaseTool(
+            name=name,
+            description=description,
+            input_schema=schema,
+            risk_level=risk_level,
+            capabilities=capabilities,
+            _func=wrapper,
+        )
+
+    return decorator

petfishframework/tools/calculator.py

@@ -0,0 +1,84 @@
+"""A safe arithmetic calculator tool."""
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+
+from petfishframework.core.contracts import RiskLevel
+from petfishframework.core.types import ToolResult
+
+from .base import BaseTool
+
+
+def _calc_schema() -> dict:
+    return {
+        "type": "object",
+        "properties": {
+            "expression": {
+                "type": "string",
+                "description": "A simple arithmetic expression, e.g. '2 + 3 * 4'.",
+            }
+        },
+        "required": ["expression"],
+    }
+
+
+@dataclass
+class Calculator(BaseTool):
+    """Safely evaluate a basic arithmetic expression."""
+
+    name: str = "calculator"
+    description: str = "Perform arithmetic"
+    input_schema: dict = field(default_factory=_calc_schema)
+    risk_level: RiskLevel = RiskLevel.LOW
+    capabilities: tuple[str, ...] = ()
+
+    def execute(self, args: dict) -> ToolResult:
+        """Evaluate the expression field safely."""
+        expression = args.get("expression", "")
+        try:
+            result = self._evaluate(expression)
+            # Normalize: return int for whole numbers to avoid 391.0 vs 391 ambiguity
+            if isinstance(result, float) and result.is_integer():
+                result = int(result)
+            return ToolResult(value=result)
+        except Exception as exc:  # noqa: BLE001
+            return ToolResult(error=str(exc))
+
+    def _evaluate(self, expression: str) -> float:
+        """Parse and evaluate a restricted arithmetic expression using ast."""
+        # Convert ^ to ** for power (models/users often use ^ for exponentiation)
+        expression = expression.replace("^", "**")
+        node = ast.parse(expression, mode="eval")
+        return self._eval_node(node.body)
+
+    def _eval_node(self, node: ast.AST) -> float:
+        if isinstance(node, ast.BinOp):
+            left = self._eval_node(node.left)
+            right = self._eval_node(node.right)
+            if isinstance(node.op, ast.Add):
+                return left + right
+            if isinstance(node.op, ast.Sub):
+                return left - right
+            if isinstance(node.op, ast.Mult):
+                return left * right
+            if isinstance(node.op, ast.Div):
+                if right == 0:
+                    raise ZeroDivisionError("division by zero")
+                return left / right
+            if isinstance(node.op, ast.Pow):
+                return left ** right
+            raise ValueError(f"Unsupported operator: {type(node.op).__name__}")
+
+        if isinstance(node, ast.UnaryOp):
+            operand = self._eval_node(node.operand)
+            if isinstance(node.op, ast.UAdd):
+                return +operand
+            if isinstance(node.op, ast.USub):
+                return -operand
+            raise ValueError(f"Unsupported unary operator: {type(node.op).__name__}")
+
+        if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
+            return float(node.value)
+
+        raise ValueError(f"Unsupported expression node: {type(node).__name__}")

petfishframework/tools/path_planner.py

@@ -0,0 +1,90 @@
+"""BFS pathfinder tool for LLM+P's planner-as-tool pattern.
+
+Deterministic symbolic planner: same input always produces the same output.
+This makes it replay-friendly and validates that a planner can be exposed
+as an Environment primitive (audited, budget-metered, permission-gated).
+"""
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Any
+
+from petfishframework.core.contracts import RiskLevel
+from petfishframework.core.types import ToolResult
+
+from .base import BaseTool
+
+
+def _path_planner_schema() -> dict[str, Any]:
+    return {
+        "type": "object",
+        "properties": {
+            "start": {
+                "type": "string",
+                "description": "Starting node identifier.",
+            },
+            "goal": {
+                "type": "string",
+                "description": "Target node identifier.",
+            },
+            "edges": {
+                "type": "array",
+                "description": "Directed edges as [from, to] pairs.",
+                "items": {
+                    "type": "array",
+                    "minItems": 2,
+                    "maxItems": 2,
+                    "items": {"type": "string"},
+                },
+            },
+        },
+        "required": ["start", "goal", "edges"],
+    }
+
+
+@dataclass
+class PathPlanner(BaseTool):
+    """Find the shortest path between two nodes using BFS."""
+
+    name: str = "path_planner"
+    description: str = "Find shortest path between nodes in a graph"
+    input_schema: dict[str, Any] = field(default_factory=_path_planner_schema)
+    risk_level: RiskLevel = RiskLevel.LOW
+    capabilities: tuple[str, ...] = ()
+
+    def execute(self, args: dict[str, Any]) -> ToolResult:
+        """Run BFS and return the shortest path or an error."""
+        start = args.get("start", "")
+        goal = args.get("goal", "")
+        edges = args.get("edges", [])
+
+        if not isinstance(edges, list):
+            return ToolResult(error="edges must be a list of [from, to] pairs")
+
+        adjacency: dict[str, list[str]] = {}
+        for edge in edges:
+            if not isinstance(edge, (list, tuple)) or len(edge) != 2:
+                return ToolResult(error="each edge must be a [from, to] pair")
+            src, dst = edge[0], edge[1]
+            adjacency.setdefault(src, []).append(dst)
+
+        if start == goal:
+            return ToolResult(value={"path": [start], "steps": 0})
+
+        visited = {start}
+        queue: deque[list[str]] = deque([[start]])
+
+        while queue:
+            path = queue.popleft()
+            node = path[-1]
+            for neighbor in adjacency.get(node, []):
+                if neighbor in visited:
+                    continue
+                visited.add(neighbor)
+                new_path = path + [neighbor]
+                if neighbor == goal:
+                    return ToolResult(value={"path": new_path, "steps": len(new_path) - 1})
+                queue.append(new_path)
+
+        return ToolResult(error="no path found")