power-loop 0.2.0__py3-none-any.whl

power_loop/tools/registry.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from power_loop.contracts.errors import ToolNotFound, ToolValidationError
+from power_loop.contracts.tools import ToolDefinition, validate_tool_args
+
+ToolCallable = Callable[..., Any] | Callable[..., Awaitable[Any]]
+
+
+class AsyncToolInSyncContext(TypeError):
+    """Raised when ``ToolRegistry.invoke`` (sync) is called for a handler
+    that is a coroutine function. The caller should use ``invoke_async``
+    instead — silently returning the unawaited coroutine corrupts loop
+    state and is the single most common cause of "tool seemed to succeed
+    but did nothing" bugs.
+    """
+
+
+@dataclass(frozen=True)
+class RegisteredTool:
+    definition: ToolDefinition
+    handler: ToolCallable
+    is_async: bool = False
+
+
+class ToolRegistry:
+    """Open tool registry for dynamic bind/add/remove operations.
+
+    Design goals:
+    - Runtime dynamic registration for library users
+    - Tool schema and handler decoupled but bound by the same name
+    - One execution entry (`invoke`/`invoke_async`) with built-in required-param validation
+    """
+
+    def __init__(self) -> None:
+        self._tools: dict[str, RegisteredTool] = {}
+
+    def register(self, definition: ToolDefinition, handler: ToolCallable, *, overwrite: bool = False) -> None:
+        if not overwrite and definition.name in self._tools:
+            raise ValueError(f"Tool already registered: {definition.name}")
+        # Detect async at register time so ``invoke()`` can raise a clear
+        # error without doing the call first. ``iscoroutinefunction``
+        # covers ``async def``; for callable objects whose ``__call__`` is
+        # async we additionally check that. Plain sync callables that
+        # *happen* to return awaitables are still handled at call time by
+        # ``invoke_async``.
+        is_async = inspect.iscoroutinefunction(handler)
+        if not is_async and not inspect.isfunction(handler) and callable(handler):
+            # Callable object whose ``__call__`` is async (e.g. dataclass
+            # with ``async def __call__``). Check that explicitly.
+            is_async = inspect.iscoroutinefunction(handler.__call__)
+        self._tools[definition.name] = RegisteredTool(
+            definition=definition, handler=handler, is_async=is_async,
+        )
+
+    def unregister(self, name: str) -> None:
+        self._tools.pop(name, None)
+
+    def has(self, name: str) -> bool:
+        return name in self._tools
+
+    def get(self, name: str) -> RegisteredTool | None:
+        return self._tools.get(name)
+
+    def definitions(self) -> list[ToolDefinition]:
+        return [item.definition for item in self._tools.values()]
+
+    def to_openai_tools(self) -> list[dict[str, Any]]:
+        return [d.to_openai_tool() for d in self.definitions()]
+
+    def validate(self, name: str, args: Mapping[str, Any]) -> str | None:
+        """Validate tool name and arguments. Returns an error string or ``None``.
+
+        This is a **legacy internal** method kept for the pipeline's
+        ``execute_tool``; new code should call ``_raise_if_invalid`` or
+        invoke directly and catch ``ToolNotFound`` / ``ToolValidationError``.
+        """
+        tool = self._tools.get(name)
+        if tool is None:
+            return f"Unknown tool: {name}"
+
+        err = validate_tool_args(name, args)
+        if err:
+            return err
+
+        missing = [p for p in tool.definition.required_params if p not in args]
+        if missing:
+            return f"Error: missing required parameter(s): {', '.join(missing)}"
+        return None
+
+    def _raise_if_invalid(self, name: str, args: Mapping[str, Any]) -> None:
+        """Raise :class:`ToolNotFound` / :class:`ToolValidationError` if the
+        tool or its args are invalid."""
+        tool = self._tools.get(name)
+        if tool is None:
+            raise ToolNotFound(name)
+
+        err = validate_tool_args(name, args)
+        if err:
+            raise ToolValidationError(name, err)
+
+        missing = [p for p in tool.definition.required_params if p not in args]
+        if missing:
+            raise ToolValidationError(
+                name, f"missing required parameter(s): {', '.join(missing)}",
+            )
+
+    def invoke(self, name: str, args: Mapping[str, Any]) -> Any:
+        """Sync invocation. Raises :class:`ToolNotFound` if the tool is
+        not registered, :class:`ToolValidationError` if args fail validation,
+        and :class:`AsyncToolInSyncContext` if the handler is ``async def``.
+        """
+        tool = self._tools.get(name)
+        if tool is None:
+            raise ToolNotFound(name)
+
+        if tool.is_async:
+            raise AsyncToolInSyncContext(
+                f"Tool {name!r} has an async handler; call invoke_async() instead."
+            )
+
+        self._raise_if_invalid(name, args)
+
+        try:
+            return tool.handler(**dict(args))
+        except TypeError:
+            return tool.handler(dict(args))
+
+    async def invoke_async(self, name: str, args: Mapping[str, Any]) -> Any:
+        """Universal invocation entry. Raises :class:`ToolNotFound` if the
+        tool is not registered, :class:`ToolValidationError` if args fail
+        validation."""
+        tool = self._tools.get(name)
+        if tool is None:
+            raise ToolNotFound(name)
+
+        self._raise_if_invalid(name, args)
+
+        if tool.is_async:
+            return await tool.handler(**dict(args))
+
+        try:
+            result = tool.handler(**dict(args))
+        except TypeError:
+            result = tool.handler(dict(args))
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+
+def build_registry(definitions: list[ToolDefinition], handlers: Mapping[str, ToolCallable]) -> ToolRegistry:
+    registry = ToolRegistry()
+    for definition in definitions:
+        handler = handlers.get(definition.name)
+        if handler is None:
+            raise ValueError(f"Missing handler for tool definition: {definition.name}")
+        registry.register(definition, handler)
+    return registry

power_loop/tools/spawn_agent.py

@@ -0,0 +1,173 @@
+"""spawn_agent + run_agent — meta-tools the LLM uses to delegate work.
+
+Two flavours of subagent invocation sit on the same plumbing
+(:func:`power_loop.runtime.spec.run_agent_spec`):
+
+* ``spawn_agent(task, preset=…)`` — *imperative*. Simple kwargs, the library
+  builds an :class:`AgentSpec` with sensible defaults for ``system_prompt`` and
+  the default tool preset. Designed for the common "go do this" case.
+* ``run_agent(spec_json, input)`` — *declarative*. The LLM provides a full
+  :class:`AgentSpec` JSON (custom system prompt, explicit tool whitelist,
+  max_rounds, etc). Designed for dynamic-workflow patterns where the parent
+  agent reasons about what a child should look like.
+
+Both tools require an active :class:`StatefulAgentLoop` context (set by
+:meth:`StatefulAgentLoop._run_loop`). Calling them outside one returns a
+clear error string.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from power_loop.contracts.tools import ToolDefinition
+from power_loop.core.agent_context import get_current_loop
+from power_loop.runtime.spec import AgentSpec, AgentSpecError, run_agent_spec
+
+DEFAULT_MAX_ROUNDS = 20
+
+SPAWN_AGENT_DEFINITION = ToolDefinition(
+    name="spawn_agent",
+    description=(
+        "Spawn a sub-agent to handle a delegated task in an isolated session. "
+        "The sub-agent inherits the parent's tool registry (filterable via "
+        "the 'tools' arg). Returns the sub-agent's final text."
+    ),
+    input_schema={
+        "type": "object",
+        "properties": {
+            "task": {
+                "type": "string",
+                "description": "The task description / instructions for the sub-agent.",
+            },
+            "system_prompt": {
+                "type": "string",
+                "description": (
+                    "Optional system prompt override. Defaults to a generic "
+                    "task-completion prompt."
+                ),
+            },
+            "tools": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": (
+                    "Optional whitelist of tool names from the parent registry. "
+                    "Omit to grant the sub-agent the full parent toolset."
+                ),
+            },
+            "max_rounds": {
+                "type": "integer",
+                "description": f"Maximum rounds (default {DEFAULT_MAX_ROUNDS}, clamp 1-50).",
+            },
+        },
+        "required": ["task"],
+    },
+    required_params=("task",),
+)
+
+RUN_AGENT_DEFINITION = ToolDefinition(
+    name="run_agent",
+    description=(
+        "Materialize a full AgentSpec JSON as a one-shot sub-agent. Use when "
+        "you want explicit control over name / system_prompt / tools / "
+        "max_rounds / max_tokens / temperature / lifecycle. Strict schema: "
+        "unknown fields are rejected."
+    ),
+    input_schema={
+        "type": "object",
+        "properties": {
+            "spec": {
+                "type": "object",
+                "description": "AgentSpec object (or JSON string).",
+            },
+            "input": {
+                "type": "string",
+                "description": "The initial user message sent to the sub-agent.",
+            },
+        },
+        "required": ["spec", "input"],
+    },
+    required_params=("spec", "input"),
+)
+
+
+# ── handlers ──────────────────────────────────────────────────────────────
+
+
+_DEFAULT_SUB_SYSTEM_PROMPT = (
+    "You are a delegated sub-agent. Complete the task the parent gave you, "
+    "be concise, and return your final answer in the last assistant message."
+)
+
+
+async def _handle_spawn_agent(**kwargs: Any) -> str:
+    loop = get_current_loop()
+    if loop is None:
+        return (
+            "Error: spawn_agent must be invoked from inside an active "
+            "StatefulAgentLoop run."
+        )
+    task = str(kwargs.get("task") or "").strip()
+    if not task:
+        return "Error: spawn_agent requires 'task'."
+
+    spec = AgentSpec(
+        name=str(kwargs.get("name") or "delegate"),
+        system_prompt=str(kwargs.get("system_prompt") or _DEFAULT_SUB_SYSTEM_PROMPT),
+        tools=kwargs.get("tools"),
+        max_rounds=int(kwargs.get("max_rounds") or DEFAULT_MAX_ROUNDS),
+    )
+    result = await run_agent_spec(spec, task, parent_loop=loop)
+    return _format_subagent_result(result)
+
+
+async def _handle_run_agent(**kwargs: Any) -> str:
+    loop = get_current_loop()
+    if loop is None:
+        return (
+            "Error: run_agent must be invoked from inside an active "
+            "StatefulAgentLoop run."
+        )
+    spec_payload = kwargs.get("spec")
+    user_input = str(kwargs.get("input") or "")
+    if not user_input:
+        return "Error: run_agent requires 'input'."
+    try:
+        spec = AgentSpec.from_json(spec_payload) if not isinstance(spec_payload, AgentSpec) else spec_payload
+    except AgentSpecError as exc:
+        return f"Error: invalid AgentSpec — {exc}"
+
+    result = await run_agent_spec(spec, user_input, parent_loop=loop)
+    return _format_subagent_result(result)
+
+
+def _format_subagent_result(result: dict[str, Any]) -> str:
+    text = result.get("final_text") or "(no output)"
+    status = result.get("status")
+    if status and status != "completed":
+        return f"[sub-agent status={status}]\n{text}"
+    return text
+
+
+# ── registration helpers ──────────────────────────────────────────────────
+
+
+def register_spawn_agent(registry, *, include_run_agent: bool = True, overwrite: bool = False) -> None:
+    """Register the spawn_agent (and optionally run_agent) tools on ``registry``.
+
+    Usage::
+
+        from power_loop import create_default_tool_registry, register_spawn_agent
+        registry = create_default_tool_registry()
+        register_spawn_agent(registry)
+    """
+    registry.register(SPAWN_AGENT_DEFINITION, _handle_spawn_agent, overwrite=overwrite)
+    if include_run_agent:
+        registry.register(RUN_AGENT_DEFINITION, _handle_run_agent, overwrite=overwrite)
+
+
+__all__ = [
+    "SPAWN_AGENT_DEFINITION",
+    "RUN_AGENT_DEFINITION",
+    "register_spawn_agent",
+]