pop-framework 0.1.0__py3-none-any.whl

pop/__init__.py

@@ -0,0 +1,85 @@
+"""pop -- Fast, lean AI agents. 5 lines to production."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core
+    "Agent",
+    "tool",
+    "Runner",
+    "run",
+    # Multi-agent
+    "handoff",
+    "pipeline",
+    "orchestrate",
+    "debate",
+    "fan_out",
+    # Workflows
+    "chain",
+    "route",
+    "parallel",
+    # Models
+    "chat",
+    "model",
+    "register_provider",
+    # Types
+    "AgentResult",
+    "Step",
+    "TokenUsage",
+    "Message",
+    # Stream events
+    "ThinkEvent",
+    "ToolCallEvent",
+    "ToolResultEvent",
+    "TextDeltaEvent",
+    "DoneEvent",
+]
+
+# Lazy import mapping: attribute name -> (module, name)
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    # Core
+    "Agent": ("pop.agent", "Agent"),
+    "tool": ("pop.tool", "tool"),
+    "Runner": ("pop.runner", "Runner"),
+    "run": ("pop.runner", "run"),
+    # Multi-agent
+    "handoff": ("pop.multi", "handoff"),
+    "pipeline": ("pop.multi", "pipeline"),
+    "orchestrate": ("pop.multi", "orchestrate"),
+    "debate": ("pop.multi", "debate"),
+    "fan_out": ("pop.multi", "fan_out"),
+    # Workflows
+    "chain": ("pop.workflows", "chain"),
+    "route": ("pop.workflows", "route"),
+    "parallel": ("pop.workflows", "parallel"),
+    # Models
+    "chat": ("pop.models", "chat"),
+    "model": ("pop.models", "model"),
+    "register_provider": ("pop.models", "register_provider"),
+    # Types
+    "AgentResult": ("pop.types", "AgentResult"),
+    "Step": ("pop.types", "Step"),
+    "TokenUsage": ("pop.types", "TokenUsage"),
+    "Message": ("pop.types", "Message"),
+    # Stream events
+    "ThinkEvent": ("pop.types", "ThinkEvent"),
+    "ToolCallEvent": ("pop.types", "ToolCallEvent"),
+    "ToolResultEvent": ("pop.types", "ToolResultEvent"),
+    "TextDeltaEvent": ("pop.types", "TextDeltaEvent"),
+    "DoneEvent": ("pop.types", "DoneEvent"),
+}
+
+
+def __getattr__(name: str) -> object:
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        import importlib
+
+        module = importlib.import_module(module_path)
+        value = getattr(module, attr_name)
+        # Cache on the module to avoid repeated lookups
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module 'pop' has no attribute {name!r}")

pop/_sync.py

@@ -0,0 +1,32 @@
+"""Shared sync-over-async helper.
+
+Both Agent.run() and Runner.run() need to call async methods from sync code.
+This module provides a single implementation to avoid duplication.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine
+
+_T = TypeVar("_T")
+
+
+def run_sync(coro: Coroutine[Any, Any, _T]) -> _T:
+    """Run a coroutine synchronously, handling running event loops (e.g. Jupyter)."""
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        loop = None
+
+    if loop and loop.is_running():
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor() as pool:
+            future = pool.submit(asyncio.run, coro)
+            return future.result()
+
+    return asyncio.run(coro)

pop/agent.py

@@ -0,0 +1,328 @@
+"""Agent class — the core ReAct loop with optional Reflexion.
+
+Implements the Reasoning + Acting pattern: the LLM reasons about the task,
+decides on an action (tool call, final answer, or ask human), and the loop
+continues until completion or a budget is exceeded.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+from pop.hooks.base import Hook, HookManager
+from pop.models.router import ModelRouter
+from pop.types import (
+    Action,
+    ActionType,
+    AgentResult,
+    AgentState,
+    Message,
+    ModelResponse,
+    Status,
+    Step,
+    TokenUsage,
+    ToolCall,
+    ToolDefinition,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from pop.memory.base import MemoryBackend
+    from pop.models.base import ModelAdapter
+
+# Rough cost estimation per token (fallback when provider doesn't report cost)
+_DEFAULT_COST_PER_INPUT_TOKEN = 0.000003
+_DEFAULT_COST_PER_OUTPUT_TOKEN = 0.000015
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _estimate_cost(usage: TokenUsage) -> float:
+    return (
+        usage.input_tokens * _DEFAULT_COST_PER_INPUT_TOKEN
+        + usage.output_tokens * _DEFAULT_COST_PER_OUTPUT_TOKEN
+    )
+
+
+class Agent:
+    """The core ReAct loop agent with optional Reflexion."""
+
+    def __init__(
+        self,
+        model: str | list[str] | ModelAdapter,
+        *,
+        name: str = "agent",
+        tools: list[ToolDefinition] | None = None,
+        instructions: str = "",
+        memory: MemoryBackend | None = None,
+        hooks: list[Hook] | None = None,
+        max_steps: int = 10,
+        max_cost: float | None = None,
+        max_retries: int = 3,
+        reflect_on_failure: bool = False,
+        output_guardrails: list[Callable[[str], bool]] | None = None,
+        core_memory: dict[str, str] | None = None,
+    ) -> None:
+        self.name = name
+        self.instructions = instructions
+        self._tools: tuple[ToolDefinition, ...] = tuple(tools) if tools else ()
+        self._tool_map: dict[str, ToolDefinition] = {t.name: t for t in self._tools}
+        self._memory = memory
+        self._hook_manager = HookManager(hooks)
+        self._max_steps = max_steps
+        self._max_cost = max_cost
+        self._max_retries = max_retries
+        self._reflect_on_failure = reflect_on_failure
+        self._output_guardrails: tuple[Callable[[str], bool], ...] = (
+            tuple(output_guardrails) if output_guardrails else ()
+        )
+        self._core_memory: dict[str, str] = dict(core_memory) if core_memory else {}
+
+        # Resolve model adapter — single router instance shared across paths
+        self._router: ModelRouter | None = None
+        if isinstance(model, str):
+            router = ModelRouter()
+            self._adapter: ModelAdapter = router.from_model_string(model)
+            self._fallback_models: list[str] = []
+        elif isinstance(model, list):
+            self._router = ModelRouter()
+            self._adapter = self._router.from_model_string(model[0])
+            self._fallback_models = list(model)
+        else:
+            self._adapter = model
+            self._fallback_models = []
+
+    def run(self, task: str, **kwargs: Any) -> AgentResult:
+        """Synchronous wrapper around arun()."""
+        from pop._sync import run_sync
+
+        return run_sync(self.arun(task, **kwargs))
+
+    async def arun(self, task: str, **kwargs: Any) -> AgentResult:
+        """Async execution of the agent loop."""
+        run_id = kwargs.get("run_id", str(uuid.uuid4()))
+        state = AgentState(status=Status.RUNNING)
+        state = state.with_message(Message.user(task))
+
+        self._hook_manager.fire_run_start(task, run_id)
+
+        result = await self._loop(state, run_id)
+
+        self._hook_manager.fire_run_end(result)
+        return result
+
+    async def _loop(self, state: AgentState, run_id: str) -> AgentResult:
+        """The core ReAct loop."""
+        steps: list[Step] = []
+
+        while state.step_count < self._max_steps:
+            if self._max_cost is not None and state.cost_usd >= self._max_cost:
+                return self._build_partial_result(state, steps, run_id)
+
+            messages = self._build_messages(state)
+            tools_for_model = list(self._tools) if self._tools else None
+
+            if self._fallback_models and self._router is not None:
+                response = await self._router.chat_with_fallback(
+                    model_strings=self._fallback_models,
+                    messages=messages,
+                    tools=tools_for_model,
+                )
+            else:
+                response = await self._adapter.chat(messages, tools_for_model)
+
+            step_cost = _estimate_cost(response.token_usage)
+            state = state.with_step(
+                step_cost=step_cost,
+                step_tokens=response.token_usage,
+            )
+
+            if self._max_cost is not None and state.cost_usd > self._max_cost:
+                step = self._make_step(
+                    index=len(steps),
+                    response=response,
+                    action=Action(type=ActionType.FINAL_ANSWER, answer=response.content),
+                )
+                steps = [*steps, step]
+                self._hook_manager.fire_step(step)
+                return self._build_partial_result(state, steps, run_id)
+
+            # Determine action from response
+            if response.tool_calls:
+                state = state.with_message(
+                    Message.assistant(response.content, tool_calls=response.tool_calls)
+                )
+                for tool_call in response.tool_calls:
+                    step, state = await self._handle_tool_call(
+                        tool_call, response, state, len(steps)
+                    )
+                    steps = [*steps, step]
+                    self._hook_manager.fire_step(step)
+            else:
+                # Final answer candidate
+                action = Action(type=ActionType.FINAL_ANSWER, answer=response.content)
+                step = self._make_step(index=len(steps), response=response, action=action)
+
+                if not self._check_guardrails(response.content):
+                    # Guardrail failed — add feedback and continue
+                    state = state.with_message(Message.assistant(response.content))
+                    state = state.with_message(
+                        Message.user(
+                            "Your previous output was rejected by a guardrail. "
+                            "Please try again with a different response."
+                        )
+                    )
+                    steps = [*steps, step]
+                    self._hook_manager.fire_step(step)
+                    continue
+
+                state = state.with_message(Message.assistant(response.content))
+                state = state.with_status(Status.DONE)
+                steps = [*steps, step]
+                self._hook_manager.fire_step(step)
+
+                return AgentResult(
+                    output=response.content,
+                    steps=tuple(steps),
+                    state=state,
+                    cost=state.cost_usd,
+                    token_usage=state.token_usage,
+                    run_id=run_id,
+                )
+
+        return self._build_partial_result(state, steps, run_id)
+
+    async def _handle_tool_call(
+        self,
+        tool_call: ToolCall,
+        response: ModelResponse,
+        state: AgentState,
+        step_index: int,
+    ) -> tuple[Step, AgentState]:
+        """Execute a tool call and return the step and updated state."""
+        tool_result_str: str | None = None
+        error_str: str | None = None
+
+        try:
+            tool_result_str = await self._execute_tool(tool_call)
+        except Exception as exc:
+            error_str = f"Tool '{tool_call.name}' error: {exc}"
+            tool_result_str = error_str
+
+        call_id = tool_call.call_id or f"call_{step_index}"
+        state = state.with_message(
+            Message.tool_result(
+                content=tool_result_str,
+                tool_call_id=call_id,
+                name=tool_call.name,
+            )
+        )
+
+        if error_str and self._reflect_on_failure:
+            state = state.with_message(
+                Message.user(
+                    "The tool call failed. Please reflect on the error above "
+                    "and decide how to proceed."
+                )
+            )
+
+        action = Action(
+            type=ActionType.TOOL_CALL,
+            tool_call=tool_call,
+        )
+        step = Step(
+            index=step_index,
+            timestamp=_now(),
+            thought=response.content or None,
+            action=action,
+            tool_name=tool_call.name,
+            tool_args=dict(tool_call.args),
+            tool_result=tool_result_str,
+            error=error_str,
+            token_usage=response.token_usage,
+            cost_usd=_estimate_cost(response.token_usage),
+            model_used=response.model,
+        )
+
+        return step, state
+
+    async def _execute_tool(self, tool_call: ToolCall) -> str:
+        """Find tool, execute, and return result as string."""
+        tool_def = self._tool_map.get(tool_call.name)
+        if tool_def is None:
+            raise ValueError(f"Unknown tool: '{tool_call.name}'")
+
+        if tool_def.is_async:
+            result = await tool_def.function(**tool_call.args)
+        else:
+            result = tool_def.function(**tool_call.args)
+
+        return str(result)
+
+    def _build_messages(self, state: AgentState) -> list[Message]:
+        """Assemble the message list for the LLM."""
+        messages: list[Message] = []
+
+        system_parts: list[str] = []
+        if self.instructions:
+            system_parts.append(self.instructions)
+        if self._core_memory:
+            core_lines = [f"- {k}: {v}" for k, v in self._core_memory.items()]
+            system_parts.append("Core memory:\n" + "\n".join(core_lines))
+
+        if system_parts:
+            messages.append(Message.system("\n\n".join(system_parts)))
+
+        messages.extend(state.messages)
+        return messages
+
+    def _check_guardrails(self, output: str) -> bool:
+        """Run all guardrail functions. Returns True if all pass."""
+        return all(guardrail(output) for guardrail in self._output_guardrails)
+
+    def _make_step(
+        self,
+        index: int,
+        response: ModelResponse,
+        action: Action,
+    ) -> Step:
+        """Create a Step record from a model response."""
+        return Step(
+            index=index,
+            timestamp=_now(),
+            thought=response.content or None,
+            action=action,
+            token_usage=response.token_usage,
+            cost_usd=_estimate_cost(response.token_usage),
+            model_used=response.model,
+        )
+
+    def _build_partial_result(
+        self,
+        state: AgentState,
+        steps: list[Step],
+        run_id: str,
+    ) -> AgentResult:
+        """Build a partial result when budget is exceeded."""
+        last_output = ""
+        if steps:
+            last_step = steps[-1]
+            if last_step.action.answer:
+                last_output = last_step.action.answer
+            elif last_step.tool_result:
+                last_output = last_step.tool_result
+
+        return AgentResult(
+            output=last_output,
+            steps=tuple(steps),
+            state=state.with_status(Status.PAUSED),
+            cost=state.cost_usd,
+            token_usage=state.token_usage,
+            partial=True,
+            run_id=run_id,
+        )

pop/hooks/__init__.py

@@ -0,0 +1,31 @@
+"""Hook system for opt-in middleware."""
+
+from __future__ import annotations
+
+from pop.hooks.base import Hook, HookManager
+
+__all__ = [
+    "ConsoleHook",
+    "CostTrackingHook",
+    "FileLogHook",
+    "Hook",
+    "HookManager",
+]
+
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    "ConsoleHook": ("pop.hooks.console", "ConsoleHook"),
+    "CostTrackingHook": ("pop.hooks.cost", "CostTrackingHook"),
+    "FileLogHook": ("pop.hooks.file_log", "FileLogHook"),
+}
+
+
+def __getattr__(name: str) -> object:
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        import importlib
+
+        module = importlib.import_module(module_path)
+        value = getattr(module, attr_name)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module 'pop.hooks' has no attribute {name!r}")

pop/hooks/base.py

@@ -0,0 +1,66 @@
+"""Hook base class and manager for opt-in agent middleware."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pop.types import AgentResult, Step
+
+
+class Hook:
+    """Base class for agent lifecycle hooks.
+
+    Hooks are opt-in: override only the methods you need.
+    Default implementations are no-ops, so subclasses don't need
+    to implement methods they don't care about.
+
+    Previous design used a Protocol with hasattr checks, but since
+    Protocol declares all methods, hasattr was always True for valid
+    implementors — making the checks redundant. A base class with
+    no-op defaults is simpler and actually achieves opt-in behavior.
+    """
+
+    def on_run_start(self, task: str, run_id: str = "") -> None:
+        """Called when an agent run starts."""
+
+    def on_step(self, step: Step) -> None:
+        """Called after each agent step completes."""
+
+    def on_run_end(self, result: AgentResult) -> None:
+        """Called when an agent run finishes."""
+
+
+class HookManager:
+    """Dispatches lifecycle events to registered hooks.
+
+    Zero hooks registered means zero overhead — all fire_* methods
+    short-circuit immediately when the hooks tuple is empty.
+    """
+
+    def __init__(self, hooks: list[Hook] | None = None) -> None:
+        self._hooks: tuple[Hook, ...] = tuple(hooks) if hooks else ()
+
+    def fire_run_start(self, task: str, run_id: str = "") -> None:
+        if not self._hooks:
+            return
+        for hook in self._hooks:
+            method = getattr(hook, "on_run_start", None)
+            if method is not None:
+                method(task, run_id)
+
+    def fire_step(self, step: Step) -> None:
+        if not self._hooks:
+            return
+        for hook in self._hooks:
+            method = getattr(hook, "on_step", None)
+            if method is not None:
+                method(step)
+
+    def fire_run_end(self, result: AgentResult) -> None:
+        if not self._hooks:
+            return
+        for hook in self._hooks:
+            method = getattr(hook, "on_run_end", None)
+            if method is not None:
+                method(result)

pop/hooks/console.py

@@ -0,0 +1,50 @@
+"""ConsoleHook — pretty-prints agent activity to stderr."""
+
+from __future__ import annotations
+
+import sys
+
+from pop.types import ActionType, AgentResult, Step
+
+
+class ConsoleHook:
+    """Prints human-readable agent activity to stderr.
+
+    Uses stderr so agent stdout output remains clean for piping.
+    """
+
+    def on_run_start(self, task: str, run_id: str = "") -> None:
+        print(f"Starting agent run: {task}", file=sys.stderr)
+
+    def on_step(self, step: Step) -> None:
+        if step.error:
+            print(
+                f"Step {step.index}: ERROR — {step.error}",
+                file=sys.stderr,
+            )
+            return
+
+        if step.action.type == ActionType.TOOL_CALL and step.tool_name:
+            args_str = str(step.tool_args or {})
+            print(
+                f"Step {step.index}: calling {step.tool_name}({args_str})",
+                file=sys.stderr,
+            )
+            if step.tool_result is not None:
+                truncated = step.tool_result[:100]
+                print(f"  → {truncated}", file=sys.stderr)
+            return
+
+        if step.action.type == ActionType.FINAL_ANSWER:
+            print(f"Step {step.index}: final answer", file=sys.stderr)
+            return
+
+        print(f"Step {step.index}: {step.action.type.value}", file=sys.stderr)
+
+    def on_run_end(self, result: AgentResult) -> None:
+        step_count = len(result.steps)
+        total_tokens = result.token_usage.total
+        print(
+            f"Done! {step_count} steps, ${result.cost:.4f}, {total_tokens} tokens",
+            file=sys.stderr,
+        )

pop/hooks/cost.py

@@ -0,0 +1,53 @@
+"""CostTrackingHook — accumulates cost and warns on budget."""
+
+from __future__ import annotations
+
+import sys
+
+from pop.types import AgentResult, Step, TokenUsage
+
+
+class CostTrackingHook:
+    """Tracks cumulative cost and token usage across an agent run.
+
+    Optionally warns when spending exceeds 80% of a given budget.
+    """
+
+    def __init__(self, budget: float | None = None) -> None:
+        self._budget = budget
+        self._total_cost: float = 0.0
+        self._total_tokens: TokenUsage = TokenUsage()
+        self._step_count: int = 0
+
+    @property
+    def total_cost(self) -> float:
+        return self._total_cost
+
+    @property
+    def total_tokens(self) -> int:
+        return self._total_tokens.total
+
+    @property
+    def step_count(self) -> int:
+        return self._step_count
+
+    def on_step(self, step: Step) -> None:
+        self._total_cost = self._total_cost + step.cost_usd
+        self._total_tokens = self._total_tokens + step.token_usage
+        self._step_count = self._step_count + 1
+
+        if self._budget is not None and self._total_cost >= self._budget * 0.8:
+            print(
+                f"Warning: cost ${self._total_cost:.4f} has reached "
+                f"{self._total_cost / self._budget * 100:.0f}% of "
+                f"${self._budget:.4f} budget",
+                file=sys.stderr,
+            )
+
+    def on_run_end(self, result: AgentResult) -> None:
+        print(
+            f"Cost summary: ${self._total_cost:.4f}, "
+            f"{self._total_tokens.total} tokens, "
+            f"{self._step_count} steps",
+            file=sys.stderr,
+        )

pop/hooks/file_log.py

@@ -0,0 +1,46 @@
+"""FileLogHook — writes JSON Lines to a file."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pop.types import AgentResult, Step
+
+
+class FileLogHook:
+    """Appends JSON Lines to a file for structured logging.
+
+    Creates the file (and parent directories) if they don't exist.
+    """
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path)
+
+    def on_step(self, step: Step) -> None:
+        record = {
+            "event": "step",
+            "index": step.index,
+            "tool_name": step.tool_name,
+            "latency_ms": step.latency_ms,
+            "cost_usd": step.cost_usd,
+            "error": step.error,
+        }
+        self._append(record)
+
+    def on_run_end(self, result: AgentResult) -> None:
+        record = {
+            "event": "run_end",
+            "output": result.output,
+            "cost_usd": result.cost,
+            "total_tokens": result.token_usage.total,
+            "step_count": len(result.steps),
+        }
+        self._append(record)
+
+    def _append(self, record: dict[str, object]) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        with open(self._path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record) + "\n")