maque-core 1.3.6__py3-none-any.whl

maque_core/__init__.py

@@ -0,0 +1,28 @@
+"""maque_core — a lightweight, extensible Agent framework."""
+
+from .contracts.llm import LLMProvider
+from .contracts.messages import LLMResponse, Message, Role, ToolCall
+from .contracts.tool import ToolSpec
+from .factory import create_agent
+from .kernel import Agent, AgentRunError
+from .llm import MockLLM, OpenAICompatibleProvider
+from .tools import ToolRegistry, tool
+
+__version__ = "1.3.4"
+
+__all__ = [
+    "create_agent",
+    "Agent",
+    "AgentRunError",
+    "tool",
+    "LLMProvider",
+    "Message",
+    "Role",
+    "ToolCall",
+    "LLMResponse",
+    "ToolSpec",
+    "ToolRegistry",
+    "OpenAICompatibleProvider",
+    "MockLLM",
+    "__version__",
+]

maque_core/config.py

@@ -0,0 +1,80 @@
+"""Configuration for the agent framework.
+
+All settings can be overridden via environment variables with the
+``MAQUE_`` prefix, e.g. ``MAQUE_LLM_MODEL=qwen3-turbo``.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class LLMConfig:
+    """LLM backend configuration."""
+
+    model: str = "qwen-turbo"
+    base_url: str = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+    api_key: str = ""
+    temperature: float = 0.7
+    timeout: int = 60
+    max_tokens: int = 2048
+
+    @classmethod
+    def from_env(cls) -> "LLMConfig":
+        return cls(
+            model=os.environ.get("MAQUE_LLM_MODEL", cls.model),
+            base_url=os.environ.get("MAQUE_LLM_BASE_URL", cls.base_url),
+            api_key=os.environ.get("MAQUE_LLM_API_KEY", cls.api_key),
+            temperature=float(os.environ.get("MAQUE_LLM_TEMPERATURE", cls.temperature)),
+            timeout=int(os.environ.get("MAQUE_LLM_TIMEOUT", cls.timeout)),
+            max_tokens=int(os.environ.get("MAQUE_LLM_MAX_TOKENS", cls.max_tokens)),
+        )
+
+
+@dataclass
+class AgentConfig:
+    """Agent runtime configuration."""
+
+    system_prompt: str = "You are a helpful assistant with access to tools. Use tools when needed to answer questions accurately."
+    max_iterations: int = 10
+    max_tool_calls: Optional[int] = None
+    verbose: bool = False
+    max_history_turns: int = 20
+    include_reasoning_in_history: bool = True
+
+    @classmethod
+    def from_env(cls) -> "AgentConfig":
+        max_tool_calls_str = os.environ.get("MAQUE_MAX_TOOL_CALLS", "")
+        max_tool_calls = int(max_tool_calls_str) if max_tool_calls_str else None
+        max_history_str = os.environ.get("MAQUE_MAX_HISTORY_TURNS", "")
+        max_history_turns = int(max_history_str) if max_history_str else cls.max_history_turns
+        return cls(
+            system_prompt=os.environ.get("MAQUE_SYSTEM_PROMPT", cls.system_prompt),
+            max_iterations=int(os.environ.get("MAQUE_MAX_ITERATIONS", cls.max_iterations)),
+            max_tool_calls=max_tool_calls,
+            verbose=os.environ.get("MAQUE_VERBOSE", "").lower() in ("1", "true", "yes"),
+            max_history_turns=max_history_turns,
+            include_reasoning_in_history=os.environ.get(
+                "MAQUE_INCLUDE_REASONING_IN_HISTORY", "true"
+            ).lower() in ("1", "true", "yes"),
+        )
+
+
+@dataclass
+class AppConfig:
+    """Top-level application configuration."""
+
+    llm: LLMConfig = field(default_factory=LLMConfig)
+    agent: AgentConfig = field(default_factory=AgentConfig)
+    tools_package: str = "maque_core.tools.impl"
+
+    @classmethod
+    def from_env(cls) -> "AppConfig":
+        return cls(
+            llm=LLMConfig.from_env(),
+            agent=AgentConfig.from_env(),
+            tools_package=os.environ.get("MAQUE_TOOLS_PACKAGE", cls.tools_package),
+        )

maque_core/contracts/__init__.py

@@ -0,0 +1,17 @@
+"""Core contracts (interfaces and data structures) for the agent framework."""
+
+from .messages import Role, ToolCall, Message, LLMResponse, Observation
+from .llm import LLMProvider
+from .tool import ToolSpec, ToolRegistry, CallBudget
+
+__all__ = [
+    "Role",
+    "ToolCall",
+    "Message",
+    "LLMResponse",
+    "Observation",
+    "LLMProvider",
+    "ToolSpec",
+    "ToolRegistry",
+    "CallBudget",
+]

maque_core/contracts/llm.py

@@ -0,0 +1,47 @@
+"""LLM provider protocol — the interface every LLM backend must implement.
+
+Using a Protocol (structural subtyping) means providers don't need to
+inherit from a base class — they just need the right method signature.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, List, Optional, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .messages import LLMResponse, Message, ToolSpec
+
+
+@runtime_checkable
+class LLMProvider(Protocol):
+    """Protocol for LLM backends.
+
+    Any class with a compatible ``chat`` method is automatically an
+    LLMProvider — no explicit inheritance required.
+    """
+
+    def chat(
+        self,
+        messages: List["Message"],
+        tools: Optional[List["ToolSpec"]] = None,
+        max_tokens: Optional[int] = None,
+        raise_on_error: bool = False,
+        **kwargs: Any,
+    ) -> "LLMResponse":
+        """Send a chat completion request and return the response.
+
+        Args:
+            messages: The conversation history.
+            tools: Optional list of tool specs the model may call.
+            max_tokens: Maximum number of tokens to generate. ``None``
+                means "use the provider's configured default".
+            raise_on_error: When ``False`` (default), API failures are
+                returned as an :class:`LLMResponse` with ``error`` set.
+                When ``True``, they are raised as an
+                :class:`~maque_core.llm.errors.LLMError` subclass instead.
+            **kwargs: Backend-specific parameters (temperature, model, etc.).
+
+        Returns:
+            An LLMResponse with content and/or tool_calls.
+        """
+        ...

maque_core/contracts/messages.py

@@ -0,0 +1,264 @@
+"""Core message data structures for agent communication.
+
+Defines the universal message types used across all layers:
+- Role: who sent a message
+- ToolCall: a requested tool invocation
+- Message: a chat message (system / user / assistant / tool)
+- LLMResponse: what the LLM returns
+- Observation: the result of a tool call
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class Role(str, Enum):
+    """Message role — who sent the message."""
+
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass
+class ToolCall:
+    """A single tool invocation requested by the model.
+
+    Attributes:
+        id: Unique identifier for this tool call (used to match results).
+        name: Name of the tool to invoke.
+        arguments: Dict of argument name → value to pass to the tool.
+    """
+
+    id: str
+    name: str
+    arguments: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "arguments": self.arguments,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ToolCall":
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            arguments=data.get("arguments", {}),
+        )
+
+
+@dataclass
+class Message:
+    """A single chat message.
+
+    Use factory methods for readability:
+        Message.system("You are helpful.")
+        Message.user("Hello")
+        Message.assistant("Hi there!", tool_calls=[...])
+        Message.tool_result("call_1", "echo", "output text")
+
+    Attributes:
+        reasoning: Optional reasoning / chain-of-thought content
+            associated with this message. Used for multi-turn
+            conversations so that subsequent rounds can see the
+            model's previous reasoning basis. None when the message
+            has no reasoning (system / user / tool messages, or
+            when ``include_reasoning_in_history`` is False).
+    """
+
+    role: Role
+    content: str = ""
+    tool_calls: List[ToolCall] = field(default_factory=list)
+    tool_call_id: Optional[str] = None
+    tool_name: Optional[str] = None
+    reasoning: Optional[str] = None
+
+    # ---- factory methods ----
+
+    @classmethod
+    def system(cls, content: str) -> "Message":
+        return cls(role=Role.SYSTEM, content=content)
+
+    @classmethod
+    def user(cls, content: str) -> "Message":
+        return cls(role=Role.USER, content=content)
+
+    @classmethod
+    def assistant(
+        cls,
+        content: str = "",
+        tool_calls: Optional[List[ToolCall]] = None,
+    ) -> "Message":
+        return cls(
+            role=Role.ASSISTANT,
+            content=content,
+            tool_calls=tool_calls or [],
+        )
+
+    @classmethod
+    def tool_result(
+        cls,
+        tool_call_id: str,
+        tool_name: str,
+        content: str,
+    ) -> "Message":
+        return cls(
+            role=Role.TOOL,
+            content=content,
+            tool_call_id=tool_call_id,
+            tool_name=tool_name,
+        )
+
+    # ---- serialization ----
+
+    def to_dict(self) -> Dict[str, Any]:
+        data: Dict[str, Any] = {"role": str(self.role), "content": self.content}
+        if self.tool_calls:
+            data["tool_calls"] = [tc.to_dict() for tc in self.tool_calls]
+        if self.tool_call_id is not None:
+            data["tool_call_id"] = self.tool_call_id
+        if self.tool_name is not None:
+            data["name"] = self.tool_name
+        if self.reasoning is not None:
+            data["reasoning"] = self.reasoning
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Message":
+        role = Role(data["role"])
+        tool_calls = [
+            ToolCall.from_dict(tc) for tc in data.get("tool_calls", [])
+        ]
+        return cls(
+            role=role,
+            content=data.get("content", ""),
+            tool_calls=tool_calls,
+            tool_call_id=data.get("tool_call_id"),
+            tool_name=data.get("name"),
+            reasoning=data.get("reasoning"),
+        )
+
+
+@dataclass
+class LLMResponse:
+    """The result of an LLM chat completion call.
+
+    Attributes:
+        content: The text response (may be empty if only tool calls).
+            When the call failed and the adapter returned instead of
+            raising, ``content`` holds the human-readable error text.
+        reasoning: The model's internal reasoning / chain-of-thought.
+            None if the model did not produce reasoning content.
+        tool_calls: Tool invocations requested by the model.
+        model: Name of the model that generated the response.
+        usage: Optional token usage info.
+        finish_reason: Why the model stopped generating. Passed through
+            from the API verbatim (``stop`` / ``length`` / ``tool_calls`` /
+            ``content_filter`` ...). ``"length"`` means the answer was
+            truncated by the token budget — it is NOT a complete answer.
+            None when the provider did not report one (e.g. on failure).
+        error: Error description when the call failed. ``None`` means the
+            response is a genuine model output. When set, ``content`` also
+            carries the message so it can still be displayed, but callers
+            MUST NOT treat it as an answer — check this field, or
+            ``response.is_error``.
+    """
+
+    content: str = ""
+    reasoning: Optional[str] = None
+    tool_calls: List[ToolCall] = field(default_factory=list)
+    model: str = ""
+    usage: Optional[Dict[str, int]] = None
+    finish_reason: Optional[str] = None
+    error: Optional[str] = None
+
+    @property
+    def is_error(self) -> bool:
+        """True when this response represents a failed LLM call."""
+        return self.error is not None
+
+    @property
+    def is_truncated(self) -> bool:
+        """True when the model stopped because it hit the token limit."""
+        return self.finish_reason == "length"
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = {
+            "content": self.content,
+            "reasoning": self.reasoning,
+            "tool_calls": [tc.to_dict() for tc in self.tool_calls],
+            "model": self.model,
+            "usage": self.usage,
+            "finish_reason": self.finish_reason,
+            "error": self.error,
+        }
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "LLMResponse":
+        return cls(
+            content=data.get("content", ""),
+            reasoning=data.get("reasoning"),
+            tool_calls=[ToolCall.from_dict(tc) for tc in data.get("tool_calls", [])],
+            model=data.get("model", ""),
+            usage=data.get("usage"),
+            finish_reason=data.get("finish_reason"),
+            error=data.get("error"),
+        )
+
+
+@dataclass
+class Observation:
+    """The result of executing a tool call.
+
+    Attributes:
+        tool_call_id: Matches the id of the originating ToolCall.
+        tool_name: Name of the tool that was executed.
+        content: String output of the tool.
+        is_error: Whether the tool call resulted in an error.
+        metadata: Extra info like execution duration, etc.
+    """
+
+    tool_call_id: str
+    tool_name: str
+    content: str
+    is_error: bool = False
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "tool_call_id": self.tool_call_id,
+            "tool_name": self.tool_name,
+            "content": self.content,
+            "is_error": self.is_error,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Observation":
+        return cls(
+            tool_call_id=data["tool_call_id"],
+            tool_name=data["tool_name"],
+            content=data["content"],
+            is_error=data.get("is_error", False),
+            metadata=data.get("metadata", {}),
+        )
+
+    def to_message(self) -> Message:
+        """Convert to a tool-role Message for feeding back to the LLM."""
+        return Message.tool_result(
+            tool_call_id=self.tool_call_id,
+            tool_name=self.tool_name,
+            content=self.content,
+        )

maque_core/contracts/tool.py

@@ -0,0 +1,121 @@
+"""Tool-related contracts: ToolSpec, ToolRegistry protocol, and CallBudget.
+
+ToolSpec describes a tool's interface (name, description, parameters).
+ToolRegistry is the protocol for registering and executing tools.
+CallBudget tracks how many tool calls remain in a session.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .messages import Observation
+
+
+@dataclass
+class ToolSpec:
+    """Specification of a tool's interface.
+
+    Attributes:
+        name: Unique tool name.
+        description: Human-readable description for the LLM.
+        parameters: JSON Schema dict describing the tool's arguments.
+        func: The callable that implements the tool.
+    """
+
+    name: str
+    description: str
+    parameters: Dict[str, Any] = field(default_factory=dict)
+    func: Any = None  # callable, stored for execution
+
+    def to_openai_schema(self) -> Dict[str, Any]:
+        """Convert to OpenAI-compatible tool schema format."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+
+@runtime_checkable
+class ToolRegistry(Protocol):
+    """Protocol for tool registries.
+
+    A registry knows about available tools, can return their schemas,
+    and can execute a tool call by name.
+    """
+
+    def register(self, spec: ToolSpec) -> None:
+        """Register a tool spec."""
+        ...
+
+    def get_schemas(self) -> List[Dict[str, Any]]:
+        """Return OpenAI-compatible schemas for all registered tools."""
+        ...
+
+    def execute(
+        self,
+        tool_name: str,
+        arguments: Dict[str, Any],
+        tool_call_id: str = "",
+    ) -> "Observation":
+        """Execute a tool by name with the given arguments.
+
+        Returns:
+            An Observation with the result (or error).
+        """
+        ...
+
+    @property
+    def tool_names(self) -> List[str]:
+        """Return list of registered tool names."""
+        ...
+
+    def __len__(self) -> int:
+        """Number of registered tools."""
+        ...
+
+
+@dataclass
+class CallBudget:
+    """Tracks remaining tool call budget.
+
+    Attributes:
+        max_calls: Maximum number of tool calls allowed. None = unlimited.
+        used: Number of tool calls already consumed.
+    """
+
+    max_calls: Optional[int] = None
+    used: int = 0
+
+    def consume(self, count: int = 1) -> bool:
+        """Consume ``count`` calls. Returns True if within budget, False if exhausted."""
+        if self.max_calls is None:
+            self.used += count
+            return True
+        if self.used + count > self.max_calls:
+            # Still count the attempted calls so ``exhausted`` stays True
+            # but we report that we're over budget
+            self.used += count
+            return False
+        self.used += count
+        return True
+
+    @property
+    def exhausted(self) -> bool:
+        """Whether the budget has been fully consumed."""
+        if self.max_calls is None:
+            return False
+        return self.used >= self.max_calls
+
+    @property
+    def remaining(self) -> Optional[int]:
+        """Number of remaining calls, or None if unlimited."""
+        if self.max_calls is None:
+            return None
+        return max(0, self.max_calls - self.used)

maque_core/factory.py

@@ -0,0 +1,105 @@
+"""Agent factory — convenient entry point for creating agents.
+
+Provides ``create_agent`` which builds an :class:`Agent` from
+explicit parameters, environment variables (via ``AppConfig.from_env``),
+or a pre-built LLM provider.
+"""
+
+from __future__ import annotations
+
+from .config import AppConfig
+from .kernel.agent import Agent
+from .llm.openai_compatible import OpenAICompatibleProvider
+from .tools.discovery import discover_tools
+from .tools.registry import ToolRegistry
+
+
+def create_agent(
+    *,
+    model: str | None = None,
+    base_url: str | None = None,
+    api_key: str | None = None,
+    system_prompt: str | None = None,
+    max_iterations: int | None = None,
+    max_tool_calls: int | None = None,
+    max_history_turns: int | None = None,
+    include_reasoning_in_history: bool | None = None,
+    tools_package: str | list[str] | None = None,
+    llm=None,
+) -> Agent:
+    """Create an Agent from explicit parameters and environment defaults.
+
+    Parameters
+    ----------
+    model:
+        Model name. Overrides the environment default when provided.
+    base_url:
+        Base URL for the OpenAI-compatible endpoint.
+    api_key:
+        API key for the LLM endpoint.
+    system_prompt:
+        System prompt to prepend to the message history.
+    max_iterations:
+        Maximum ReAct iterations per ``ask()`` call.
+    max_tool_calls:
+        Maximum tool calls per ``ask()`` call.
+    max_history_turns:
+        Maximum conversation turns to keep in history.
+    include_reasoning_in_history:
+        Whether to include reasoning content in the message history.
+    tools_package:
+        Package name(s) to scan for ``@tool``-decorated functions.
+        ``None`` means no tools are loaded by default.
+        A string loads one package; a list loads multiple packages
+        into the same registry.
+    llm:
+        Pre-built LLM provider. When provided, ``model``/``base_url``/
+        ``api_key`` are ignored and this provider is used directly.
+
+    Returns
+    -------
+    Agent
+        A configured Agent instance ready to use.
+    """
+    config = AppConfig.from_env()
+
+    # LLM
+    if llm is None:
+        llm = OpenAICompatibleProvider(
+            model=model if model is not None else config.llm.model,
+            base_url=base_url if base_url is not None else config.llm.base_url,
+            api_key=api_key if api_key is not None else config.llm.api_key,
+            temperature=config.llm.temperature,
+            timeout=config.llm.timeout,
+            max_tokens=config.llm.max_tokens,
+        )
+
+    # Tools
+    registry = ToolRegistry()
+    if tools_package is not None:
+        if isinstance(tools_package, str):
+            discover_tools(registry, tools_package)
+        else:
+            for pkg in tools_package:
+                discover_tools(registry, pkg)
+
+    # Config overrides
+    resolved_system_prompt = system_prompt if system_prompt is not None else config.agent.system_prompt
+    resolved_max_iterations = max_iterations if max_iterations is not None else config.agent.max_iterations
+    resolved_max_tool_calls = max_tool_calls if max_tool_calls is not None else config.agent.max_tool_calls
+    resolved_max_history = max_history_turns if max_history_turns is not None else config.agent.max_history_turns
+    resolved_include_reasoning = (
+        include_reasoning_in_history
+        if include_reasoning_in_history is not None
+        else config.agent.include_reasoning_in_history
+    )
+
+    return Agent(
+        llm=llm,
+        registry=registry,
+        system_prompt=resolved_system_prompt,
+        max_iterations=resolved_max_iterations,
+        max_tool_calls=resolved_max_tool_calls,
+        max_history_turns=resolved_max_history,
+        include_reasoning_in_history=resolved_include_reasoning,
+    )

maque_core/kernel/__init__.py

@@ -0,0 +1,8 @@
+"""Kernel layer — the agent's reasoning and acting loop."""
+
+from .agent import Agent
+from .budget import RunBudget
+from .errors import AgentRunError
+from .loop import react_loop
+
+__all__ = ["Agent", "AgentRunError", "RunBudget", "react_loop"]