coreouto 0.1.0__py3-none-any.whl

coreouto/__init__.py

@@ -0,0 +1,95 @@
+"""coreouto — a minimal, extensible Python agent library.
+
+See README.md and docs/ for usage. The public API is re-exported here.
+"""
+
+from coreouto._types import (
+    AgentConfig,
+    LLMResponse,
+    Message,
+    Response,
+    ToolCall,
+    ToolResult,
+    Usage,
+)
+from coreouto._version import __version__
+from coreouto.agent import Agent, MaxIterationsError
+from coreouto.hooks import (
+    AFTER_LLM_CALL,
+    AFTER_TOOL_CALL,
+    BEFORE_LLM_CALL,
+    BEFORE_TOOL_CALL,
+    ON_FINISH,
+    ON_ITERATION,
+    ON_USER_INJECTION,
+    clear_hooks,
+    get_hooks,
+    register_hook,
+)
+from coreouto.multi_agent import agent_as_tool, make_delegate_tool
+from coreouto.presets import (
+    AgentPreset,
+    clear_agent_presets,
+    get_agent_preset,
+    list_agent_presets,
+    register_agent_preset,
+)
+from coreouto.providers import (
+    available_providers,
+    clear_providers,
+    get_provider,
+    register_provider,
+)
+from coreouto.settings import CANONICAL_SETTINGS, normalize_provider_config
+from coreouto.sync import call_sync
+from coreouto.tools import (
+    Tool,
+    clear_tools,
+    get_tool,
+    list_tools,
+    register_tool,
+    register_tool_class,
+)
+
+__all__ = [
+    "AFTER_LLM_CALL",
+    "AFTER_TOOL_CALL",
+    "BEFORE_LLM_CALL",
+    "BEFORE_TOOL_CALL",
+    "CANONICAL_SETTINGS",
+    "ON_FINISH",
+    "ON_ITERATION",
+    "ON_USER_INJECTION",
+    "Agent",
+    "AgentConfig",
+    "AgentPreset",
+    "LLMResponse",
+    "MaxIterationsError",
+    "Message",
+    "Response",
+    "Tool",
+    "ToolCall",
+    "ToolResult",
+    "Usage",
+    "__version__",
+    "agent_as_tool",
+    "available_providers",
+    "call_sync",
+    "clear_agent_presets",
+    "clear_hooks",
+    "clear_providers",
+    "clear_tools",
+    "get_agent_preset",
+    "get_hooks",
+    "get_provider",
+    "get_tool",
+    "list_agent_presets",
+    "list_tools",
+    "make_delegate_tool",
+    "normalize_provider_config",
+    "register_agent_preset",
+    "register_hook",
+    "register_provider",
+    "register_tool",
+    "register_tool_class",
+]

coreouto/_types.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class ToolCall(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    id: str
+    name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolResult(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    tool_call_id: str
+    content: str
+    is_error: bool = False
+
+
+class Usage(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+
+    @model_validator(mode="after")
+    def _total_matches_sum(self) -> Usage:
+        if self.total_tokens != self.prompt_tokens + self.completion_tokens:
+            raise ValueError(
+                f"total_tokens ({self.total_tokens}) must equal "
+                f"prompt_tokens ({self.prompt_tokens}) + "
+                f"completion_tokens ({self.completion_tokens})"
+            )
+        return self
+
+
+class LLMResponse(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    content: str | None = None
+    tool_calls: list[ToolCall] = Field(default_factory=list)
+    usage: Usage | None = None
+    raw: Any | None = None
+
+
+class Message(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    role: Literal["system", "user", "assistant", "tool"]
+    content: str
+    tool_calls: list[ToolCall] | None = None
+    tool_call_id: str | None = None
+    name: str | None = None
+
+
+class AgentConfig(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    name: str
+    model: str
+    provider: str
+    system_prompt: str | None = None
+    tools: list[str] = Field(default_factory=list)
+    max_iterations: int = 50
+    provider_config: dict[str, Any] = Field(default_factory=dict)
+    provider_passthrough: dict[str, Any] = Field(default_factory=dict)
+
+
+class Response(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    content: str
+    messages: list[Message]
+    iterations: int
+    usage: list[Usage] = Field(default_factory=list)
+    finish_called: bool = True
+    warnings: list[str] = Field(default_factory=list)

coreouto/_version.py

@@ -0,0 +1,3 @@
+"""Version constant for coreouto."""
+
+__version__ = "0.1.0"

coreouto/agent.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import re
+from typing import Any
+
+from coreouto._types import AgentConfig, Message, Response, ToolResult, Usage
+from coreouto.hooks import (
+    AFTER_LLM_CALL,
+    AFTER_TOOL_CALL,
+    BEFORE_LLM_CALL,
+    BEFORE_TOOL_CALL,
+    ON_FINISH,
+    ON_ITERATION,
+    ON_USER_INJECTION,
+    trigger,
+)
+from coreouto.providers import get_provider
+from coreouto.settings import normalize_provider_config
+from coreouto.tools import get_tool
+
+_FINISH_RE = re.compile(r"<finish>(.*?)</finish>", re.DOTALL)
+_FINISH_REMINDER = (
+    "Your previous response did not contain a <finish> tag. "
+    "You MUST wrap your final user-facing answer in <finish>...</finish> tags. "
+    "Anything outside the tags is discarded. "
+    "Example: <finish>Your answer here.</finish>"
+)
+_DEFAULT_SYSTEM_PROMPT = (
+    "You are an agent. Use tools to gather information, then return your final answer to the user.\n\n"
+    "CRITICAL: When you are done, your final user-facing answer MUST be wrapped in <finish>...</finish> tags. "
+    "The text inside the tags is what the user will see.\n\n"
+    "Example:\n"
+    "The capital of France is Paris.\n"
+    "<finish>Paris is the capital of France.</finish>\n\n"
+    "If you respond with text but no <finish> tags, the loop will continue and you'll be asked to retry."
+)
+
+
+class MaxIterationsError(Exception):
+    pass
+
+
+class Agent:
+    def __init__(self, config: AgentConfig) -> None:
+        self.config = config
+        self.provider_name = config.provider
+        self._pending_user_messages: asyncio.Queue[str] = asyncio.Queue()
+
+    def inject_user_message(self, content: str) -> None:
+        """Queue a user message to be inserted on the next loop iteration.
+
+        Thread-safe and async-safe: callable from any thread, from another
+        async task, or from a hook callback. The message is inserted into
+        the conversation at the start of the next iteration and fires the
+        `on_user_injection` hook.
+        """
+        self._pending_user_messages.put_nowait(content)
+
+    def call_sync(
+        self,
+        user_message: str,
+        *,
+        override: AgentConfig | None = None,
+        history: list[Message] | None = None,
+    ) -> Response:
+        from coreouto import sync
+
+        return sync.call_sync(self, user_message, override=override, history=history)
+
+    async def call(
+        self,
+        user_message: str,
+        *,
+        override: AgentConfig | None = None,
+        history: list[Message] | None = None,
+    ) -> Response:
+        cfg = override or self.config
+        provider = get_provider(cfg.provider)
+
+        resolved_tools: list[Any] = []
+        for name in cfg.tools:
+            tool = get_tool(name)
+            if tool is None:
+                raise KeyError(f"tool not registered: {name!r}")
+            resolved_tools.append(tool)
+
+        messages: list[Message] = []
+        if cfg.system_prompt:
+            messages.append(Message(role="system", content=cfg.system_prompt))
+        else:
+            messages.append(Message(role="system", content=_DEFAULT_SYSTEM_PROMPT))
+        if history:
+            messages.extend(history)
+        messages.append(Message(role="user", content=user_message))
+
+        iterations = 0
+        all_usage: list[Usage] = []
+
+        while True:
+            await asyncio.sleep(0)
+            while not self._pending_user_messages.empty():
+                content = self._pending_user_messages.get_nowait()
+                injected = Message(role="user", content=content)
+                messages.append(injected)
+                await trigger(
+                    ON_USER_INJECTION,
+                    message=injected,
+                    messages=messages,
+                )
+
+            iterations += 1
+            if iterations > cfg.max_iterations:
+                raise MaxIterationsError(
+                    f"max_iterations ({cfg.max_iterations}) reached without a <finish> tag"
+                )
+
+            await trigger(
+                BEFORE_LLM_CALL,
+                messages=messages,
+                model=cfg.model,
+                tools=resolved_tools,
+            )
+
+            normalized = normalize_provider_config(cfg.provider, cfg.provider_config)
+            merged = {**normalized, **cfg.provider_passthrough}
+            response = await provider.create(
+                messages=messages,
+                model=cfg.model,
+                tools=resolved_tools,
+                system_prompt=None,
+                **merged,
+            )
+
+            await trigger(AFTER_LLM_CALL, response=response, messages=messages)
+            if response.usage:
+                all_usage.append(response.usage)
+
+            assistant_msg = provider.format_assistant_message(response)
+            messages.append(assistant_msg)
+
+            await trigger(
+                ON_ITERATION,
+                iteration=iterations,
+                messages=messages,
+                response=response,
+            )
+
+            last_assistant_text = response.content or ""
+            match = _FINISH_RE.search(last_assistant_text)
+            if match:
+                final_answer = match.group(1).strip()
+                await trigger(
+                    ON_FINISH,
+                    content=final_answer,
+                    raw_content=last_assistant_text,
+                    messages=messages,
+                    iterations=iterations,
+                )
+                return Response(
+                    content=final_answer,
+                    messages=messages,
+                    iterations=iterations,
+                    usage=all_usage,
+                    finish_called=True,
+                )
+
+            if not response.tool_calls:
+                messages.append(Message(role="user", content=_FINISH_REMINDER))
+                continue
+
+            for tool_call in response.tool_calls:
+                tool = get_tool(tool_call.name)
+
+                await trigger(
+                    BEFORE_TOOL_CALL,
+                    name=tool_call.name,
+                    arguments=tool_call.arguments,
+                )
+
+                if tool is None:
+                    result = ToolResult(
+                        tool_call_id=tool_call.id,
+                        content=f"tool not found: {tool_call.name}",
+                        is_error=True,
+                    )
+                else:
+                    try:
+                        raw_result = tool.handler(**tool_call.arguments)
+                        if inspect.iscoroutine(raw_result):
+                            raw_result = await raw_result
+                        result_content = str(raw_result)
+                        result = ToolResult(
+                            tool_call_id=tool_call.id,
+                            content=result_content,
+                            is_error=False,
+                        )
+                    except Exception as exc:
+                        result = ToolResult(
+                            tool_call_id=tool_call.id,
+                            content=f"{type(exc).__name__}: {exc}",
+                            is_error=True,
+                        )
+
+                await trigger(
+                    AFTER_TOOL_CALL,
+                    name=tool_call.name,
+                    result=result,
+                )
+
+                tool_msg = provider.format_tool_result(tool_call, result)
+                messages.append(tool_msg)

coreouto/contrib/hooks.py

@@ -0,0 +1,97 @@
+"""Opt-in hook recipes for coreouto.
+
+Each factory returns a hook callable ready to be passed to
+``coreouto.hooks.register_hook``. Recipes that need to share state with the
+caller expose that state by returning it alongside the hook as a tuple
+``(hook, state)``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from coreouto._types import LLMResponse, Message, ToolResult, Usage
+
+
+def token_collection_hook(
+    *, sink: list[Usage] | None = None
+) -> tuple[Callable[..., None], list[Usage]]:
+    if sink is None:
+        sink = []
+
+    def hook(response: LLMResponse, **_kwargs: Any) -> None:
+        if response.usage is not None:
+            sink.append(response.usage)
+
+    return hook, sink
+
+
+def auto_summarize_hook(
+    *, threshold: int, summarize_fn: Callable[[list[Message]], list[Message]]
+) -> Callable[..., None]:
+    total: list[int] = [0]
+
+    def hook(
+        *, iteration: int, messages: list[Message], response: LLMResponse, **_kwargs: Any
+    ) -> None:
+        if response.usage is None:
+            return
+        total[0] += response.usage.total_tokens
+        if total[0] >= threshold:
+            summarized = summarize_fn(messages)
+            messages.clear()
+            messages.extend(summarized)
+
+    return hook
+
+
+def token_limit_warning_hook(
+    *, limit: int, callback: Callable[[Usage], Any] | None = None
+) -> Callable[..., None]:
+    if callback is None:
+
+        def callback(usage: Usage) -> None:
+            print(f"WARNING: token limit {limit} exceeded, current {usage.total_tokens}")
+
+    def hook(response: LLMResponse, **_kwargs: Any) -> None:
+        if response.usage is not None and response.usage.total_tokens > limit:
+            callback(response.usage)
+
+    return hook
+
+
+def iteration_notification_hook(
+    *, every: int = 10, callback: Callable[[int], Any] | None = None
+) -> Callable[..., None]:
+    if callback is None:
+
+        def callback(iteration: int) -> None:
+            print(f"INFO: reached iteration {iteration}")
+
+    def hook(*, iteration: int, **_kwargs: Any) -> None:
+        if iteration % every == 0:
+            callback(iteration)
+
+    return hook
+
+
+def tool_usage_collection_hook(
+    *, sink: list[tuple[str, str, bool]] | None = None
+) -> tuple[Callable[..., None], list[tuple[str, str, bool]]]:
+    if sink is None:
+        sink = []
+
+    def hook(*, name: str, result: ToolResult, **_kwargs: Any) -> None:
+        sink.append((name, result.content, result.is_error))
+
+    return hook, sink
+
+
+__all__ = [
+    "auto_summarize_hook",
+    "iteration_notification_hook",
+    "token_collection_hook",
+    "token_limit_warning_hook",
+    "tool_usage_collection_hook",
+]

coreouto/hooks.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+BEFORE_LLM_CALL = "before_llm_call"
+AFTER_LLM_CALL = "after_llm_call"
+BEFORE_TOOL_CALL = "before_tool_call"
+AFTER_TOOL_CALL = "after_tool_call"
+ON_ITERATION = "on_iteration"
+ON_FINISH = "on_finish"
+ON_USER_INJECTION = "on_user_injection"
+
+_HOOKS: dict[str, list[Callable[..., Any]]] = {}
+
+
+def register_hook(event: str, fn: Callable[..., Any]) -> None:
+    if event not in _HOOKS:
+        _HOOKS[event] = []
+    _HOOKS[event].append(fn)
+
+
+def get_hooks(event: str) -> list[Callable[..., Any]]:
+    return list(_HOOKS.get(event, []))
+
+
+def clear_hooks(event: str | None = None) -> None:
+    if event is None:
+        _HOOKS.clear()
+    else:
+        _HOOKS.pop(event, None)
+
+
+async def trigger(event: str, **kwargs: Any) -> None:
+    for fn in _HOOKS.get(event, []):
+        if inspect.iscoroutinefunction(fn):
+            await fn(**kwargs)
+        else:
+            fn(**kwargs)

coreouto/multi_agent.py

@@ -0,0 +1,108 @@
+"""Multi-agent orchestration helpers.
+
+`agent_as_tool` wraps a registered agent preset as a callable `Tool`,
+allowing a parent agent to delegate sub-tasks to specialised child agents.
+The returned tool is **not** auto-registered; the caller is responsible
+for wiring it into a parent's tool list (for example, by passing it
+directly to `AgentConfig(tools=[...])` or by wrapping it with
+`register_tool` if a global name is desired).
+"""
+
+from __future__ import annotations
+
+from coreouto.agent import Agent
+from coreouto.presets import get_agent_preset
+from coreouto.tools import Tool
+
+_DEFAULT_DESCRIPTION_TEMPLATE = (
+    "Delegate a sub-task to the {preset} agent. Input is the task description."
+)
+
+_TASK_PARAMETERS: dict[str, object] = {
+    "type": "object",
+    "properties": {
+        "task": {
+            "type": "string",
+            "description": "The task description to pass to the sub-agent.",
+        }
+    },
+    "required": ["task"],
+}
+
+_DELEGATE_PARAMETERS: dict[str, object] = {
+    "type": "object",
+    "properties": {
+        "agent_name": {
+            "type": "string",
+            "description": "The name of a registered agent preset to call.",
+        },
+        "message": {
+            "type": "string",
+            "description": "The message to pass to the target agent.",
+        },
+    },
+    "required": ["agent_name", "message"],
+}
+
+_DEFAULT_DELEGATE_DESCRIPTION = (
+    "Call a registered agent by name and pass it a message. "
+    "The agent's response is returned as a string."
+)
+
+
+def agent_as_tool(
+    preset_name: str,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> Tool:
+    preset = get_agent_preset(preset_name)
+    config = preset.to_config()
+    agent = Agent(config)
+
+    tool_name = name if name is not None else f"call_{preset_name}"
+    tool_description = (
+        description
+        if description is not None
+        else _DEFAULT_DESCRIPTION_TEMPLATE.format(preset=preset_name)
+    )
+
+    async def handler(task: str) -> str:
+        return (await agent.call(task)).content
+
+    return Tool(
+        name=tool_name,
+        description=tool_description,
+        parameters=_TASK_PARAMETERS,
+        handler=handler,
+    )
+
+
+def make_delegate_tool(
+    *,
+    name: str = "call_agent",
+    description: str | None = None,
+) -> Tool:
+    """Create a tool that dispatches to any registered agent preset by name.
+
+    The returned tool accepts two arguments:
+    - `agent_name: str` — the name of a registered agent preset
+    - `message: str` — the message to pass to that agent
+
+    The handler looks up the preset via `get_agent_preset`, constructs a
+    fresh `Agent` from its config, calls it, and returns the response
+    content. If the preset is not registered, `KeyError` propagates.
+    """
+    tool_description = description if description is not None else _DEFAULT_DELEGATE_DESCRIPTION
+
+    async def delegate(agent_name: str, message: str) -> str:
+        preset = get_agent_preset(agent_name)
+        agent = Agent(preset.to_config())
+        return (await agent.call(message)).content
+
+    return Tool(
+        name=name,
+        description=tool_description,
+        parameters=_DELEGATE_PARAMETERS,
+        handler=delegate,
+    )