minima-cli 0.4.9__py3-none-any.whl

minima_harness/agent/loop.py

@@ -0,0 +1,311 @@
+"""The agent loop — a port of PI's ``agentLoop`` async generator.
+
+Runs turn after turn: stream the model -> emit message events -> if it requested tools,
+execute them (parallel via anyio, with before/afterToolCall hooks) -> append tool
+results -> continue. Steering/follow-up queues are drained between turns. Emits the full
+PI event taxonomy so any subscriber can render the run.
+
+Tool-execution events are replayed in completion order (the loop awaits the whole batch,
+then yields the buffered events); final ``toolResult`` messages are appended in assistant
+source order. This is correct and deterministic for the harness's needs.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import AsyncIterator
+from typing import Any
+
+import anyio
+from pydantic import ValidationError
+
+from minima_harness.agent.events import (
+    AgentEndEvent,
+    AgentStartEvent,
+    MessageEndEvent,
+    MessageStartEvent,
+    MessageUpdateEvent,
+    ToolExecutionEndEvent,
+    ToolExecutionStartEvent,
+    ToolExecutionUpdateEvent,
+    TurnEndEvent,
+    TurnStartEvent,
+)
+from minima_harness.agent.state import AgentLoopConfig, AgentState
+from minima_harness.agent.tools import (
+    AfterToolCallContext,
+    BeforeToolCallContext,
+    ToolResult,
+    error_result,
+    find_agent_tool,
+)
+from minima_harness.ai.stream import stream as default_stream
+from minima_harness.ai.types import Context, Message, Tool
+
+_PendingTool = tuple[Any, Any, Any]  # (tool_call, AgentTool, validated_params)
+
+
+async def agent_loop(
+    prompts: list[Message],
+    state: AgentState,
+    config: AgentLoopConfig,
+) -> AsyncIterator[Any]:
+    """Run the agent over ``prompts`` appended to ``state``, yielding AgentEvents."""
+    if state.model is None:
+        raise ValueError("AgentState.model must be set before running the loop")
+
+    yield AgentStartEvent()
+
+    for prompt in prompts:
+        state.messages.append(prompt)
+        yield MessageStartEvent(message=prompt)
+        yield MessageEndEvent(message=prompt)
+
+    stream_fn = config.stream_fn or default_stream
+    turns = 0
+    while turns < config.max_turns:
+        turns += 1
+        yield TurnStartEvent()
+
+        llm_messages = await _prepare_messages(state, config)
+        ctx = Context(
+            system_prompt=state.system_prompt,
+            messages=llm_messages,
+            tools=[
+                Tool(name=t.name, description=t.description, parameters=t.parameters)
+                for t in state.tools
+            ],
+        )
+        options = _stream_options(config)
+        s = stream_fn(state.model, ctx, options=options)
+        yield MessageStartEvent(message=None)
+        async for stream_event in s:
+            yield MessageUpdateEvent(assistant_message_event=stream_event)
+        assistant = await s.result()
+        state.streaming_message = assistant
+        state.messages.append(assistant)
+        yield MessageEndEvent(message=assistant)
+
+        if assistant.stop_reason == "error":
+            state.error_message = assistant.error_message or "provider error"
+            yield TurnEndEvent(message=assistant, tool_results=[])
+            break
+
+        tool_calls = assistant.tool_calls if assistant.stop_reason == "toolUse" else []
+        results: list[tuple[Any, ToolResult, bool]] = []
+        if tool_calls:
+            async for ev in _execute_tool_calls(tool_calls, config, state, results):
+                yield ev
+            for tc, result, is_error in results:
+                tr = Message(
+                    role="toolResult",
+                    tool_call_id=tc.id,
+                    tool_name=tc.name,
+                    content=result.content,
+                    is_error=is_error,
+                )
+                state.messages.append(tr)
+                yield MessageStartEvent(message=tr)
+                yield MessageEndEvent(message=tr)
+
+        yield TurnEndEvent(message=assistant, tool_results=[r for _, r, _ in results])
+
+        if results and all(r.terminate for _, r, _ in results):
+            break
+        if config.should_stop_after_turn is not None and await config.should_stop_after_turn(
+            assistant, [r for _, r, _ in results], state, state.messages
+        ):
+            break
+
+        injected = _pop_queue(state.steering, state.steering_mode)
+        if injected:
+            for m in injected:
+                state.messages.append(m)
+                yield MessageStartEvent(message=m)
+                yield MessageEndEvent(message=m)
+            continue
+
+        if not tool_calls:
+            injected = _pop_queue(state.follow_up, state.follow_up_mode)
+            if injected:
+                for m in injected:
+                    state.messages.append(m)
+                    yield MessageStartEvent(message=m)
+                    yield MessageEndEvent(message=m)
+                continue
+            break
+
+    state.turns_taken = turns
+    state.streaming_message = None
+    yield AgentEndEvent(messages=list(state.messages))
+
+
+async def agent_loop_continue(state: AgentState, config: AgentLoopConfig) -> AsyncIterator[Any]:
+    """Resume from existing context (last message must be user or toolResult)."""
+    if state.messages:
+        last = state.messages[-1]
+        if last.role == "assistant":
+            raise ValueError(
+                "agent_loop_continue requires the last message to be user or toolResult"
+            )
+    # Trick: agent_loop is an async generator; forward its yields.
+    async for ev in agent_loop([], state, config):  # pragma: no cover - delegated
+        yield ev
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _drop_failed_calls(messages: list[Message]) -> list[Message]:
+    """Never send a failed call's assistant to a provider.
+
+    A provider error is swallowed into an assistant with ``stop_reason == "error"`` and
+    (usually) empty content, which the loop appends to history before breaking. Left in the
+    context it makes the *next* request invalid — e.g. Anthropic rejects an empty text block
+    with ``400 "messages: text content blocks must be non-empty"`` — so a single provider
+    hiccup would wedge the whole session. Filtering here protects every consumer of the loop
+    (not just :class:`MinimaAgent`) and resumed sessions alike.
+    """
+    return [m for m in messages if getattr(m, "stop_reason", None) != "error"]
+
+
+async def _prepare_messages(state: AgentState, config: AgentLoopConfig) -> list[Message]:
+    messages = _drop_failed_calls(state.messages)
+    if config.transform_context is not None:
+        messages = await config.transform_context(messages, None)
+    return config.convert_to_llm(messages)
+
+
+def _stream_options(config: AgentLoopConfig) -> dict[str, Any]:
+    opts: dict[str, Any] = dict(config.stream_options or {})
+    opts["thinking"] = config.thinking_level != "off"
+    if config.thinking_level != "off":
+        budget = (config.thinking_budgets or {}).get(config.thinking_level)
+        if budget is not None:
+            opts["thinking_budget"] = budget
+    if config.session_id:
+        opts["session_id"] = config.session_id
+    return opts
+
+
+async def _execute_tool_calls(
+    tool_calls: list[Any],
+    config: AgentLoopConfig,
+    state: AgentState,
+    out_results: list[tuple[Any, ToolResult, bool]],
+) -> AsyncIterator[Any]:
+    """Preflight (yield tool_execution_start) then execute; yield updates + ends.
+
+    Appends results to ``out_results`` in assistant SOURCE order; buffered events are
+    replayed in completion order.
+    """
+    plan: list[_PendingTool] = []
+    for tc in tool_calls:
+        state.pending_tool_calls.add(tc.id)
+        tool = find_agent_tool(state.tools, tc.name)
+        if tool is None:
+            yield ToolExecutionStartEvent(tool_call_id=tc.id, tool_name=tc.name, args=None)
+            res = error_result(f"Unknown tool: {tc.name}")
+            yield ToolExecutionEndEvent(tool_call_id=tc.id, result=res, is_error=True)
+            out_results.append((tc, res, True))
+            state.pending_tool_calls.discard(tc.id)
+            continue
+        try:
+            params = tool.parameters.model_validate(tc.arguments)
+        except ValidationError as exc:
+            yield ToolExecutionStartEvent(tool_call_id=tc.id, tool_name=tc.name, args=None)
+            res = error_result(_format_validation_error(exc))
+            yield ToolExecutionEndEvent(tool_call_id=tc.id, result=res, is_error=True)
+            out_results.append((tc, res, True))
+            state.pending_tool_calls.discard(tc.id)
+            continue
+        yield ToolExecutionStartEvent(tool_call_id=tc.id, tool_name=tc.name, args=params)
+        if config.before_tool_call is not None:
+            decision = await config.before_tool_call(
+                BeforeToolCallContext(tool_call=tc, args=params, context=state)
+            )
+            if decision is not None and decision.block:
+                res = error_result(decision.reason or "blocked by beforeToolCall")
+                yield ToolExecutionEndEvent(tool_call_id=tc.id, result=res, is_error=True)
+                out_results.append((tc, res, True))
+                state.pending_tool_calls.discard(tc.id)
+                continue
+        plan.append((tc, tool, params))
+
+    sequential = config.tool_execution == "sequential" or any(
+        t.execution_mode == "sequential" for _, t, _ in plan
+    )
+    completion: list[tuple[Any, list, ToolResult, bool]] = []
+    if sequential:
+        for tc, tool, params in plan:
+            completion.append(await _run_one(tc, tool, params, config, state))
+    else:
+        async with anyio.create_task_group() as tg:
+
+            async def runner(tc: Any, tool: Any, params: Any) -> None:
+                completion.append(await _run_one(tc, tool, params, config, state))
+
+            for tc, tool, params in plan:
+                tg.start_soon(runner, tc, tool, params)
+
+    by_id: dict[str, tuple[Any, ToolResult, bool]] = {}
+    for tc, updates, result, is_error in completion:
+        for upd in updates:
+            yield upd
+        yield ToolExecutionEndEvent(tool_call_id=tc.id, result=result, is_error=is_error)
+        state.pending_tool_calls.discard(tc.id)
+        by_id[tc.id] = (tc, result, is_error)
+
+    for tc, _, _ in plan:  # source order
+        out_results.append(by_id[tc.id])
+
+
+async def _run_one(
+    tc: Any, tool: Any, params: Any, config: AgentLoopConfig, state: AgentState
+) -> tuple[Any, list, ToolResult, bool]:
+    updates: list[Any] = []
+
+    def on_update(partial: Any) -> None:
+        updates.append(ToolExecutionUpdateEvent(tool_call_id=tc.id, partial=partial))
+
+    try:
+        result = await tool.execute(tc.id, params, None, on_update)
+        is_error = False
+    except Exception as exc:  # noqa: BLE001 - surface as tool error, not a raise
+        result = error_result(str(exc))
+        is_error = True
+
+    if config.after_tool_call is not None:
+        ar = await config.after_tool_call(
+            AfterToolCallContext(tool_call=tc, result=result, is_error=is_error, context=state)
+        )
+        if ar is not None:
+            if ar.terminate:
+                result.terminate = True
+            if ar.details is not None:
+                result.details = {**result.details, **ar.details}
+            if ar.content is not None:
+                result.content = ar.content
+
+    return tc, updates, result, is_error
+
+
+def _format_validation_error(exc: ValidationError) -> str:
+    parts = []
+    for err in exc.errors():
+        loc = ".".join(str(x) for x in err["loc"]) or "<root>"
+        parts.append(f"{loc}: {err['msg']}")
+    return "; ".join(parts)
+
+
+def _pop_queue(queue: deque[Message], mode: str) -> list[Message]:
+    """Pop messages per mode: one for ``one-at-a-time``, all for ``all``."""
+    if not queue:
+        return []
+    if mode == "one-at-a-time":
+        return [queue.popleft()]
+    drained = list(queue)
+    queue.clear()
+    return drained

minima_harness/agent/state.py

@@ -0,0 +1,79 @@
+"""Agent run state and loop config.
+
+``AgentState`` is both the observable state (read via ``agent.state``) and the mutable
+context threaded through :func:`agent_loop` — it carries messages, tools, and the
+steering/follow-up queues the Agent pushes into. Loop config is split out so it can be
+rebuilt per run (the Agent holds the knobs; the loop receives a frozen snapshot).
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from minima_harness.agent.tools import (
+    AfterToolCall,
+    BeforeToolCall,
+    ThinkingLevel,
+    ToolExecutionMode,
+)
+from minima_harness.ai.types import AssistantMessage, Message, Model
+
+
+@dataclass(slots=True)
+class AgentState:
+    """Mutable run state shared between the Agent and the loop."""
+
+    system_prompt: str | None = None
+    model: Model | None = None
+    thinking_level: ThinkingLevel = "off"
+    tools: list = field(default_factory=list)  # list[AgentTool]
+    messages: list[Message] = field(default_factory=list)
+    # Streaming flags (observable).
+    is_streaming: bool = False
+    streaming_message: AssistantMessage | None = None
+    pending_tool_calls: set[str] = field(default_factory=set)
+    error_message: str | None = None
+    # Turns actually run in the last agent_loop (token-yield signal: a cheap model that
+    # takes many turns to resolve can cost more than one frontier turn). Set by the loop.
+    turns_taken: int = 0
+    # Queues the Agent pushes into mid-run; drained between turns by the loop.
+    steering: deque[Message] = field(default_factory=deque)
+    follow_up: deque[Message] = field(default_factory=deque)
+    steering_mode: str = "one-at-a-time"
+    follow_up_mode: str = "one-at-a-time"
+
+
+# (messages) -> messages to send to the LLM (filter custom types, prune, etc.)
+ConvertToLlm = Callable[[list[Message]], list[Message]]
+# (messages, signal) -> messages (optional compaction/injection before convert_to_llm)
+TransformContext = Callable[[list[Message], object | None], Awaitable[list[Message]]]
+# Run after a turn settles; return True to stop gracefully (e.g. before compaction).
+ShouldStopAfterTurn = Callable[[AssistantMessage, list, AgentState, list[Message]], Awaitable[bool]]
+StreamFn = Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class AgentLoopConfig:
+    """Snapshot of loop behaviour handed to :func:`agent_loop`."""
+
+    model: Model
+    convert_to_llm: ConvertToLlm
+    tool_execution: ToolExecutionMode = "parallel"
+    before_tool_call: BeforeToolCall | None = None
+    after_tool_call: AfterToolCall | None = None
+    transform_context: TransformContext | None = None
+    should_stop_after_turn: ShouldStopAfterTurn | None = None
+    thinking_budgets: dict[str, int] | None = None
+    thinking_level: ThinkingLevel = "off"
+    max_turns: int = 50
+    session_id: str | None = None
+    stream_fn: StreamFn | None = None
+    stream_options: dict[str, Any] | None = None
+
+
+def default_convert_to_llm(messages: list[Message]) -> list[Message]:
+    """Drop anything the LLM can't ingest (keeps user/assistant/toolResult)."""
+    return [m for m in messages if m.role in ("user", "assistant", "toolResult")]

minima_harness/agent/tools.py

@@ -0,0 +1,97 @@
+"""Agent tools and execution hooks — port of PI's ``AgentTool`` + before/afterToolCall.
+
+Tools declare parameters as a pydantic model (the TypeBox analogue); ``execute`` is an
+async callable ``(tool_call_id, params, signal, on_update) -> ToolResult``. Validation
+errors and thrown exceptions become tool-error results fed back to the model so it can
+retry (matching PI).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel
+
+from minima_harness.ai.types import ContentBlock, TextContent, ToolCall
+
+if TYPE_CHECKING:
+    from minima_harness.agent.state import AgentState
+
+ToolExecutionMode = Literal["parallel", "sequential"]
+ThinkingLevel = Literal["off", "minimal", "low", "medium", "high", "xhigh"]
+
+# on_update(partial_result) -> None; called mid-execution for streaming progress.
+ToolUpdate = Callable[[Any], None]
+ToolExecute = Callable[[str, BaseModel, object | None, ToolUpdate | None], Awaitable["ToolResult"]]
+
+
+@dataclass(slots=True)
+class ToolResult:
+    """What a tool returns. ``content`` goes to the model; ``details`` are app-facing."""
+
+    content: list[ContentBlock]
+    details: dict[str, Any] = field(default_factory=dict)
+    # Hint to skip the automatic follow-up LLM call. Only honoured when every finalized
+    # tool result in the batch also sets terminate=True.
+    terminate: bool = False
+
+
+@dataclass(slots=True)
+class AgentTool:
+    name: str
+    description: str
+    parameters: type[BaseModel]
+    execute: ToolExecute
+    execution_mode: ToolExecutionMode | None = None
+    label: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Hook types
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class BeforeToolCallContext:
+    tool_call: ToolCall
+    args: BaseModel  # validated params
+    context: AgentState
+
+
+@dataclass(slots=True)
+class BeforeToolCallResult:
+    block: bool = False
+    reason: str = ""
+
+
+@dataclass(slots=True)
+class AfterToolCallContext:
+    tool_call: ToolCall
+    result: ToolResult
+    is_error: bool
+    context: AgentState
+
+
+@dataclass(slots=True)
+class AfterToolCallResult:
+    terminate: bool = False
+    details: dict[str, Any] | None = None
+    content: list[ContentBlock] | None = None
+
+
+BeforeToolCall = Callable[[BeforeToolCallContext], Awaitable[BeforeToolCallResult | None]]
+AfterToolCall = Callable[[AfterToolCallContext], Awaitable[AfterToolCallResult | None]]
+
+
+def find_agent_tool(tools: list[AgentTool], name: str) -> AgentTool | None:
+    for t in tools:
+        if t.name == name:
+            return t
+    return None
+
+
+def error_result(message: str) -> ToolResult:
+    """A standard error tool result (single text block)."""
+    return ToolResult(content=[TextContent(text=message)])

minima_harness/ai/__init__.py

@@ -0,0 +1,66 @@
+"""minima_harness.ai — lean Python port of @earendil-works/pi-ai (unified LLM API)."""
+
+from minima_harness.ai.events import Event
+from minima_harness.ai.registry import (
+    all_models,
+    get_model,
+    get_models,
+    get_providers,
+    register_model,
+    try_get_model,
+)
+from minima_harness.ai.stream import Stream, complete, stream
+from minima_harness.ai.tools import (
+    ToolParamError,
+    UnknownToolError,
+    find_tool,
+    validate_tool_call,
+)
+from minima_harness.ai.types import (
+    AssistantMessage,
+    Context,
+    Cost,
+    ImageContent,
+    Message,
+    Modality,
+    Model,
+    ModelCost,
+    TextContent,
+    ThinkingContent,
+    Tool,
+    ToolCall,
+    Usage,
+)
+from minima_harness.ai.usage import attach_cost, cost_for
+
+__all__ = [
+    "AssistantMessage",
+    "Context",
+    "Cost",
+    "Event",
+    "ImageContent",
+    "Message",
+    "Model",
+    "ModelCost",
+    "Modality",
+    "Stream",
+    "TextContent",
+    "ThinkingContent",
+    "Tool",
+    "ToolCall",
+    "ToolParamError",
+    "UnknownToolError",
+    "Usage",
+    "all_models",
+    "attach_cost",
+    "complete",
+    "cost_for",
+    "find_tool",
+    "get_model",
+    "get_models",
+    "get_providers",
+    "register_model",
+    "stream",
+    "try_get_model",
+    "validate_tool_call",
+]

minima_harness/ai/compat.py

@@ -0,0 +1,71 @@
+"""Cross-provider message compatibility.
+
+Assistant messages produced by one provider (e.g. Anthropic thinking blocks) cannot
+always be replayed verbatim into another provider's request. The transform here mirrors
+PI's rule: thinking blocks become ``<thinking>...</thinking>`` tagged text when the
+target api differs from the source; text, tool calls and tool results pass through.
+
+Each provider still owns its *to-wire* mapping (anthropic ``tool_use`` blocks vs google
+``function_call`` parts vs openai ``tool_calls``). This module only normalizes the
+provider-agnostic :class:`~minima_harness.ai.types.Message` list beforehand.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from minima_harness.ai.types import Message, TextContent
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from minima_harness.ai.types import AssistantMessage
+
+_THINK_OPEN = "<thinking>"
+_THINK_CLOSE = "</thinking>"
+
+
+def thinking_to_text(message: AssistantMessage) -> AssistantMessage:
+    """Return a copy with every ThinkingContent block folded into tagged text.
+
+    Thinking blocks are replaced in place by a TextContent wrapping the thinking in
+    ``<thinking>`` tags; adjacent ordering is preserved so the conversation still reads
+    naturally to a foreign model.
+    """
+    new_content: list = []
+    if isinstance(message.content, str):  # pragma: no cover - coerced upstream
+        return message
+    for block in message.content:
+        if hasattr(block, "thinking"):
+            new_content.append(TextContent(text=f"{_THINK_OPEN}{block.thinking}{_THINK_CLOSE}"))
+        else:
+            new_content.append(block)
+    new = message.model_copy(update={"content": new_content})
+    return new
+
+
+def source_api_of(message: AssistantMessage) -> str | None:
+    """Infer the api that produced ``message`` from its ``model`` id (registry lookup)."""
+    if not message.model:
+        return None
+    from minima_harness.ai.registry import find_model_by_id
+
+    model = find_model_by_id(message.model)
+    return model.api if model is not None else None
+
+
+def normalize_for_target(messages: Iterable[Message], target_api: str) -> list[Message]:
+    """Cross-provider normalize a message list before to-wire mapping for ``target_api``.
+
+    Assistant messages whose source api differs from ``target_api`` have their thinking
+    blocks converted to tagged text; everything else is returned unchanged.
+    """
+    out: list[Message] = []
+    for m in messages:
+        if m.role == "assistant":
+            asst = cast("AssistantMessage", m)
+            source = source_api_of(asst)
+            if source is not None and source != target_api:
+                m = thinking_to_text(asst)
+        out.append(m)
+    return out