maque-core 1.3.4__py3-none-any.whl

maque_core/kernel/agent.py

@@ -0,0 +1,228 @@
+"""Agent — high-level interface to the agent framework.
+
+Wraps the ReAct loop, LLM provider, and tool registry into a single
+convenient class.
+
+Multi-turn conversation support:
+- The agent maintains a persistent ``messages`` list across calls.
+- Each ``ask()`` appends the user message and lets the loop append
+  assistant/tool messages in-place.
+- History is trimmed automatically when it exceeds ``max_history_turns``
+  to prevent context overflow.
+- Use ``reset()`` to start a fresh conversation.
+
+Error propagation:
+- ``ask()`` raises :class:`AgentRunError` on LLM failure by default
+  (``raise_on_error=True``). This is the facade layer — callers get a
+  clean exception instead of having to inspect the response.
+- On failure, all messages appended during the failed call are rolled
+  back so the conversation history stays clean (no orphan user message,
+  no partial assistant/tool messages).
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from ..contracts.llm import LLMProvider
+from ..contracts.messages import Message, Role
+from ..contracts.tool import ToolRegistry
+from .budget import RunBudget
+from .errors import AgentRunError
+from .loop import react_loop
+
+
+class Agent:
+    """High-level agent interface with multi-turn conversation memory.
+
+    Usage::
+
+        agent = Agent(llm=my_llm, registry=my_registry)
+        answer = agent.ask("What is 2 + 2?")
+        print(agent.latest_reasoning)  # the most recent reasoning
+
+        # Multi-turn — history is preserved automatically
+        answer2 = agent.ask("And what about 3 + 3?")
+
+        # Start fresh
+        agent.reset()
+
+    Attributes:
+        latest_reasoning: The reasoning content from the most recent
+            LLM call. None if the last call produced no reasoning.
+            Only the latest reasoning is kept — it is overwritten on
+            each LLM call, not accumulated.
+        messages: The full conversation history (list of Message).
+            Includes system prompt, user messages, assistant responses,
+            and tool results. Modified in-place by ``ask()``.
+    """
+
+    def __init__(
+        self,
+        llm: LLMProvider,
+        registry: ToolRegistry,
+        system_prompt: str = "You are a helpful assistant.",
+        max_iterations: int = 10,
+        max_tool_calls: Optional[int] = None,
+        verbose: bool = False,
+        max_history_turns: int = 20,
+        include_reasoning_in_history: bool = True,
+    ):
+        self.llm = llm
+        self.registry = registry
+        self.system_prompt = system_prompt
+        self.max_iterations = max_iterations
+        self.max_tool_calls = max_tool_calls
+        self.verbose = verbose
+        self.max_history_turns = max_history_turns
+        self.include_reasoning_in_history = include_reasoning_in_history
+        self.latest_reasoning: Optional[str] = None
+
+        # Conversation history — persists across ask() calls for multi-turn.
+        # Starts with just the system prompt.
+        self.messages: List[Message] = [Message.system(system_prompt)]
+
+    def ask(
+        self,
+        question: str,
+        verbose: Optional[bool] = None,
+        raise_on_error: bool = True,
+    ) -> str:
+        """Ask the agent a question and get an answer.
+
+        The question is appended to the conversation history, and the
+        agent's response (including any tool calls and results) is
+        also appended. This means subsequent ``ask()`` calls carry
+        the full conversation context.
+
+        History is trimmed at the start of each call if it exceeds
+        ``max_history_turns``. The system prompt is always preserved.
+
+        After this call, ``self.latest_reasoning`` contains the
+        reasoning from the most recent LLM call (overwritten each time,
+        not accumulated across calls).
+
+        Error handling:
+            By default (``raise_on_error=True``), LLM failures raise
+            :class:`AgentRunError`. When an error occurs, **all messages
+            added during this call are rolled back** so the conversation
+            history stays clean — no orphan user message, no partial
+            assistant or tool messages.
+
+            Pass ``raise_on_error=False`` to get the old behaviour where
+            the error text is returned as the answer string.
+
+        Args:
+            question: The user's question.
+            verbose: Override the agent's verbose setting for this call.
+            raise_on_error: When ``True`` (default), raise
+                :class:`AgentRunError` on LLM failure and roll back
+                the history. When ``False``, return the error text as
+                the answer (legacy behaviour).
+
+        Returns:
+            The agent's answer string.
+
+        Raises:
+            AgentRunError: When the LLM call fails and ``raise_on_error``
+                is True. The conversation history is rolled back to
+                its pre-call state before the exception is raised.
+        """
+        v = verbose if verbose is not None else self.verbose
+
+        # Trim history before adding the new message
+        self._trim_history()
+
+        # Snapshot the current length so we can roll back on failure.
+        # This fixes the P2 "history pollution" bug where a failed call
+        # would leave an orphan user message in the history.
+        snapshot = len(self.messages)
+
+        # Append user message to the persistent history
+        self.messages.append(Message.user(question))
+
+        budget = RunBudget(
+            max_iterations=self.max_iterations,
+            max_tool_calls=self.max_tool_calls,
+        )
+
+        try:
+            answer, reasoning = react_loop(
+                llm=self.llm,
+                registry=self.registry,
+                messages=self.messages,
+                budget=budget,
+                verbose=v,
+                include_reasoning_in_history=self.include_reasoning_in_history,
+                raise_on_error=raise_on_error,
+            )
+        except Exception:
+            # Roll back all messages added during this call
+            # (user message + any assistant/tool messages from the loop).
+            del self.messages[snapshot:]
+            raise
+
+        self.latest_reasoning = reasoning
+        return answer
+
+    def reset(self) -> None:
+        """Reset the conversation history.
+
+        Clears all messages and re-initializes with just the system
+        prompt. Use this to start a fresh conversation without
+        creating a new Agent instance.
+        """
+        self.messages = [Message.system(self.system_prompt)]
+        self.latest_reasoning = None
+
+    def _trim_history(self) -> None:
+        """Trim conversation history to stay within max_history_turns.
+
+        Strategy:
+        - Always keep the system prompt (index 0).
+        - Count complete "turns" in the remaining messages. A turn is
+          a user message plus everything until the next user message
+          (assistant response + any tool calls + tool results).
+        - We reserve room for the upcoming new turn, so we trim to
+          ``max_history_turns - 1`` completed turns. After the new
+          user message is added and the loop runs, the total will be
+          at most ``max_history_turns``.
+        - If the number of completed turns exceeds the target, remove
+          the oldest complete turns from the middle (between system
+          prompt and the most recent turns).
+
+        This is called automatically at the start of each ``ask()``.
+        """
+        if self.max_history_turns <= 0:
+            return
+
+        # Target: keep at most (max - 1) completed turns before adding the new one
+        target_turns = self.max_history_turns - 1
+        if target_turns <= 0:
+            target_turns = 1  # always keep at least 1 turn of context if possible
+
+        # Find all user message indices (these mark turn boundaries)
+        # Skip index 0 which is the system prompt
+        user_indices = [
+            i for i, msg in enumerate(self.messages)
+            if i > 0 and msg.role == Role.USER
+        ]
+
+        current_turns = len(user_indices)
+        if current_turns <= target_turns:
+            return
+
+        # How many turns to remove from the oldest end
+        turns_to_remove = current_turns - target_turns
+
+        # The cut point is the start of the (turns_to_remove)-th user
+        # message from the beginning. We keep everything from that
+        # user message onward (plus the system prompt at index 0).
+        if turns_to_remove < len(user_indices):
+            cut_index = user_indices[turns_to_remove]
+            # Keep system prompt + messages from cut_index onward
+            self.messages = [self.messages[0]] + self.messages[cut_index:]
+
+    def list_tools(self) -> List[str]:
+        """Return the names of all available tools."""
+        return self.registry.tool_names

maque_core/kernel/budget.py

@@ -0,0 +1,69 @@
+"""Run budget — dual protection for agent runs.
+
+Combines two limits:
+1. max_iterations — maximum number of LLM calls (reasoning + acting cycles)
+2. max_tool_calls — maximum number of tool invocations
+
+Either limit being exhausted triggers a forced final answer.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class RunBudget:
+    """Budget for a single agent run.
+
+    Attributes:
+        max_iterations: Maximum LLM calls. None = unlimited.
+        max_tool_calls: Maximum tool calls. None = unlimited.
+        iterations_used: Number of iterations consumed so far.
+        tool_calls_used: Number of tool calls consumed so far.
+    """
+
+    max_iterations: Optional[int] = 10
+    max_tool_calls: Optional[int] = None
+    iterations_used: int = 0
+    tool_calls_used: int = 0
+
+    def consume_iteration(self) -> bool:
+        """Consume one iteration. Returns True if within budget, False if exhausted."""
+        self.iterations_used += 1
+        if self.max_iterations is None:
+            return True
+        return self.iterations_used <= self.max_iterations
+
+    def consume_tool_call(self, count: int = 1) -> bool:
+        """Consume ``count`` tool calls. Returns True if within budget."""
+        self.tool_calls_used += count
+        if self.max_tool_calls is None:
+            return True
+        return self.tool_calls_used <= self.max_tool_calls
+
+    @property
+    def iterations_exhausted(self) -> bool:
+        """Whether the iteration limit has been reached."""
+        if self.max_iterations is None:
+            return False
+        return self.iterations_used >= self.max_iterations
+
+    @property
+    def tool_calls_exhausted(self) -> bool:
+        """Whether the tool call limit has been reached."""
+        if self.max_tool_calls is None:
+            return False
+        return self.tool_calls_used >= self.max_tool_calls
+
+    @property
+    def any_exhausted(self) -> bool:
+        """Whether any budget limit has been reached."""
+        return self.iterations_exhausted or self.tool_calls_exhausted
+
+    def __repr__(self) -> str:
+        return (
+            f"RunBudget(iterations={self.iterations_used}/{self.max_iterations}, "
+            f"tool_calls={self.tool_calls_used}/{self.max_tool_calls})"
+        )

maque_core/kernel/errors.py

@@ -0,0 +1,46 @@
+"""Kernel-level error types.
+
+AgentRunError is the exception raised by the kernel loop when an LLM
+call fails and ``raise_on_error`` is enabled. It carries both the
+human-readable message and the raw :class:`LLMResponse` so upper
+layers can inspect provider-level detail (model, usage, etc.) without
+having to parse the error text.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from ..contracts.messages import LLMResponse
+
+
+class AgentRunError(Exception):
+    """Raised when the ReAct loop encounters an unrecoverable LLM error.
+
+    This is the kernel-layer error channel — it replaces the old pattern
+    where errors were stuffed into ``LLMResponse.content`` and callers
+    had to check ``response.is_error`` after every call.
+
+    Attributes:
+        message: Human-readable error description.
+        response: The raw :class:`LLMResponse` that carried the error.
+            ``None`` when the failure happened before a response was
+            obtained (e.g. the loop itself detected a structural problem).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        response: Optional["LLMResponse"] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.response = response
+
+    def __str__(self) -> str:
+        return self.message
+
+
+__all__ = ["AgentRunError"]

maque_core/kernel/loop.py

@@ -0,0 +1,320 @@
+"""ReAct loop — the core Reasoning + Acting cycle.
+
+The loop:
+1. Send messages + tool schemas to LLM
+2. If LLM returns text → that's the answer (done)
+3. If LLM returns tool_calls → execute them, add results to messages, go to 1
+4. If budget exhausted → force final answer from the LLM
+
+Multi-turn support:
+- The loop can accept an existing messages list and append to it in-place,
+  so conversation history persists across multiple ``ask()`` calls.
+- Reasoning from each LLM call can be stored on the assistant message
+  (controlled by ``include_reasoning_in_history``), giving the model
+  visibility into its own prior reasoning in subsequent turns.
+- finish_reason='length' triggers one retry with a "please continue"
+  system message, so truncated outputs get completed.
+
+Error propagation:
+- By default (``raise_on_error=False``), LLM errors are returned inside
+  ``LLMResponse`` with ``error`` set — the legacy behaviour.
+- When ``raise_on_error=True``, any LLM failure raises :class:`AgentRunError`
+  instead, so the error travels through the exception channel and the
+  caller doesn't have to inspect every response.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from ..contracts.llm import LLMProvider
+from ..contracts.messages import LLMResponse, Message, Observation, Role
+from ..contracts.tool import ToolRegistry
+from .budget import RunBudget
+from .errors import AgentRunError
+
+
+def react_loop(
+    llm: LLMProvider,
+    registry: ToolRegistry,
+    messages: List[Message],
+    budget: Optional[RunBudget] = None,
+    verbose: bool = False,
+    include_reasoning_in_history: bool = True,
+    raise_on_error: bool = False,
+) -> tuple:
+    """Run the ReAct (Reasoning + Acting) loop.
+
+    Args:
+        llm: The LLM provider to use.
+        registry: The tool registry to use for tool calls.
+        messages: Conversation history list. The loop appends new
+            messages to this list **in-place**, so callers can keep
+            using the same list across multiple turns for multi-turn
+            conversations. Must already contain system prompt and
+            user message(s).
+        budget: Optional run budget (iterations + tool calls).
+        verbose: If True, print each step to stdout.
+        include_reasoning_in_history: If True, store reasoning content
+            on each assistant message so it's visible in future turns.
+            If False, reasoning is only kept as ``latest_reasoning``
+            and not persisted in history (saves tokens).
+        raise_on_error: When ``False`` (default, backward-compatible),
+            LLM failures are returned as an :class:`LLMResponse` with
+            ``error`` set. When ``True``, they raise :class:`AgentRunError`
+            instead, propagating through the exception channel.
+
+    Returns:
+        A tuple of (final_answer: str, latest_reasoning: str | None).
+        latest_reasoning contains only the most recent LLM call's
+        reasoning content (overwritten each iteration, not accumulated).
+    """
+    if budget is None:
+        budget = RunBudget(max_iterations=10)
+
+    tool_budget_exhausted = False
+    latest_reasoning: Optional[str] = None
+
+    while True:
+        # Check iteration budget
+        if not budget.consume_iteration():
+            if verbose:
+                print(f"[budget] max iterations reached ({budget.max_iterations}), forcing final answer")
+            answer, reasoning = _force_final_answer(
+                llm, messages, reason="max_iterations_reached",
+                raise_on_error=raise_on_error,
+            )
+            if reasoning is not None:
+                latest_reasoning = reasoning
+                if include_reasoning_in_history and messages:
+                    # Attach reasoning to the last assistant message
+                    for msg in reversed(messages):
+                        if msg.role == Role.ASSISTANT:
+                            msg.reasoning = reasoning
+                            break
+            return answer, latest_reasoning
+
+        # Get tool schemas
+        tool_schemas = None
+        if len(registry) > 0 and not tool_budget_exhausted:
+            from ..contracts.tool import ToolSpec
+            # Build ToolSpec list from registry
+            tool_specs = []
+            for name in registry.tool_names:
+                spec = registry.get_spec(name)
+                if spec:
+                    tool_specs.append(spec)
+            tool_schemas = tool_specs
+
+        # Call LLM (with finish_reason length retry)
+        response = _chat_with_length_retry(
+            llm, messages, tool_schemas, budget, verbose,
+            raise_on_error=raise_on_error,
+        )
+
+        # Update latest reasoning (overwrite — only keep the most recent)
+        if response.reasoning is not None:
+            latest_reasoning = response.reasoning
+
+        if verbose:
+            print(f"[llm] content={response.content!r} tool_calls={len(response.tool_calls)}")
+            if response.reasoning:
+                print(f"[llm] reasoning={response.reasoning[:80]}...")
+
+        # Add assistant message to history
+        # When include_reasoning_in_history is True, reasoning is stored
+        # on the message so future turns can see the model's prior thinking.
+        assistant_msg = Message.assistant(
+            content=response.content,
+            tool_calls=response.tool_calls,
+        )
+        if include_reasoning_in_history and response.reasoning is not None:
+            assistant_msg.reasoning = response.reasoning
+        messages.append(assistant_msg)
+
+        # If no tool calls, we're done — return the content
+        if not response.tool_calls:
+            return response.content, latest_reasoning
+
+        # If tool budget is already exhausted but model still called tools → force final answer
+        if tool_budget_exhausted:
+            if verbose:
+                print("[budget] tool budget exhausted but model called tools, forcing final answer")
+            answer, reasoning = _force_final_answer(
+                llm, messages, reason="tool_budget_exhausted",
+                raise_on_error=raise_on_error,
+            )
+            if reasoning is not None:
+                latest_reasoning = reasoning
+                if include_reasoning_in_history and messages:
+                    for msg in reversed(messages):
+                        if msg.role == Role.ASSISTANT:
+                            msg.reasoning = reasoning
+                            break
+            return answer, latest_reasoning
+
+        # Execute all tool calls
+        for tool_call in response.tool_calls:
+            # Check tool budget before executing
+            if budget.max_tool_calls is not None and budget.tool_calls_used >= budget.max_tool_calls:
+                tool_budget_exhausted = True
+                # Add a tool message for the truncated call (Kernel layer fix:
+                # budget truncation补tool消息 — ensures the model sees a
+                # consistent tool_call → tool_result pair, otherwise the
+                # message history has unmatched tool_calls which breaks
+                # some model APIs).
+                messages.append(
+                    Message.tool_result(
+                        tool_call_id=tool_call.id,
+                        tool_name=tool_call.name,
+                        content=(
+                            f"Tool call budget exhausted (max={budget.max_tool_calls}). "
+                            "This call was not executed. Please provide your final answer "
+                            "based on the information you already have."
+                        ),
+                    )
+                )
+                # Also add a system message explaining the budget situation
+                messages.append(
+                    Message.system(
+                        f"Tool call budget exhausted (max={budget.max_tool_calls}). "
+                        "Please provide your final answer based on the information you already have."
+                    )
+                )
+                if verbose:
+                    print(f"[budget] tool call budget exhausted at {budget.max_tool_calls}")
+                break  # stop executing more tool calls this round
+
+            observation = registry.execute(
+                tool_name=tool_call.name,
+                arguments=tool_call.arguments,
+                tool_call_id=tool_call.id,
+            )
+            budget.consume_tool_call()
+
+            if verbose:
+                status = "ERROR" if observation.is_error else "OK"
+                print(f"[tool] {tool_call.name}({tool_call.arguments}) → {status}: {observation.content[:80]}")
+
+            messages.append(observation.to_message())
+
+        # Continue the loop — the next iteration will give the model
+        # the tool results and let it decide what to do next
+
+
+def _chat_with_length_retry(
+    llm: LLMProvider,
+    messages: List[Message],
+    tool_schemas: Optional[list],
+    budget: RunBudget,
+    verbose: bool,
+    raise_on_error: bool = False,
+) -> LLMResponse:
+    """Call the LLM once, with one retry if finish_reason is 'length'.
+
+    When the model hits the token limit (finish_reason='length') and
+    we still have iteration budget, append a system message asking the
+    model to continue, then call again. This gives truncated outputs
+    a chance to complete.
+
+    Max 1 retry to prevent infinite loops.
+
+    Error handling:
+    - When ``raise_on_error`` is True and the LLM returns an error
+      response (or the retry produces one), raise :class:`AgentRunError`
+      instead of returning the response.
+    """
+    response = llm.chat(messages, tools=tool_schemas)
+
+    # Error check — raise if enabled
+    if response.error is not None and raise_on_error:
+        raise AgentRunError(response.error, response=response)
+
+    # Only retry on length truncation, and only if we have budget left
+    if (
+        response.finish_reason == "length"
+        and budget.iterations_used < budget.max_iterations - 1
+    ):
+        if verbose:
+            print("[llm] output truncated (finish_reason=length), retrying with continue prompt")
+
+        # Append the truncated assistant message with a continue system prompt
+        # We need to temporarily add the truncated response + continue hint
+        truncated_msg = Message.assistant(
+            content=response.content,
+            tool_calls=response.tool_calls,
+        )
+        messages.append(truncated_msg)
+        messages.append(
+            Message.system("输出被截断，请继续生成你的回答。")
+        )
+
+        # Consume an iteration for the retry
+        budget.consume_iteration()
+
+        # Retry — this time without tools (we just want the continuation text)
+        # try/finally: the temporary messages must be popped even when
+        # llm.chat raises, otherwise the truncated message + continue
+        # prompt leak into the caller's history.
+        try:
+            retry_response = llm.chat(messages, tools=None)
+        finally:
+            # Remove the temporary messages we added — the caller will add
+            # the final assistant message itself. We combine the truncated
+            # content with the continuation.
+            messages.pop()  # remove system continue message
+            messages.pop()  # remove truncated assistant message
+
+        # Combine content from both calls
+        combined_content = response.content + retry_response.content
+
+        # Build combined response
+        combined = LLMResponse(
+            content=combined_content,
+            reasoning=retry_response.reasoning or response.reasoning,
+            tool_calls=retry_response.tool_calls or response.tool_calls,
+            model=retry_response.model or response.model,
+            usage=retry_response.usage,
+            finish_reason=retry_response.finish_reason,
+            error=retry_response.error,
+        )
+
+        # Error check on combined result — raise if enabled
+        if combined.error is not None and raise_on_error:
+            raise AgentRunError(combined.error, response=combined)
+
+        return combined
+
+    return response
+
+
+def _force_final_answer(
+    llm: LLMProvider,
+    messages: List[Message],
+    reason: str,
+    raise_on_error: bool = False,
+) -> tuple:
+    """Force the model to produce a final text answer without tools.
+
+    Called when budget is exhausted or we need to wrap up.
+
+    Error handling:
+    - When ``raise_on_error`` is True and the LLM returns an error
+      response, raise :class:`AgentRunError` instead of returning.
+
+    Returns:
+        A tuple of (answer: str, reasoning: str | None).
+    """
+    messages.append(
+        Message.system(
+            f"Reached limit ({reason}). Please provide a concise final answer "
+            "based on the conversation so far, without calling any more tools."
+        )
+    )
+    response = llm.chat(messages, tools=None)
+
+    # Error check — raise if enabled
+    if response.error is not None and raise_on_error:
+        raise AgentRunError(response.error, response=response)
+
+    return response.content or "(no final answer generated)", response.reasoning