quantalogic 0.80__py3-none-any.whl → 0.93__py3-none-any.whl

quantalogic/codeact/examples/README.md

@@ -1,342 +0,0 @@
-# Quantalogic Agent Configuration YAML Format
-
-This document describes the YAML configuration format for the `AgentConfig` class in the Quantalogic framework, used to configure an AI agent’s behavior, tools, and components. The configuration is flexible, supporting both simple setups and advanced customizations, and is fully backward-compatible with earlier versions.
-
-## Overview
-
-The YAML configuration file defines the settings for an `Agent` instance, controlling aspects such as the language model, task-solving parameters, tool usage, and agent personality. You can provide this configuration via a file (passed as a string to `Agent`) or directly as arguments to `AgentConfig`. All fields are optional unless specified, with sensible defaults ensuring compatibility with minimal setups.
-
-### Example Minimal Configuration
-```yaml
-model: "gemini/gemini-2.0-flash"
-max_iterations: 5
-name: "MathBot"
-personality: "witty"
-```
-
-### Example Advanced Configuration
-```yaml
-name: "EquationSolver"
-model: "deepseek/deepseek-chat"
-max_iterations: 5
-max_history_tokens: 2000
-profile: "math_expert"
-customizations:
-  personality:
-    traits:
-      - "witty"
-tools_config:
-  - name: "math_tools"
-    enabled: true
-    config:
-      precision: "high"
-      api_key: "{{ env.MATH_API_KEY }}"
-reasoner:
-  name: "default"
-  config:
-    temperature: 0.7
-executor:
-  name: "default"
-  config:
-    timeout: 300
-sop: |
-  Always provide clear, concise answers.
-  Prioritize mathematical accuracy.
-```
-
-## Configuration Fields
-
-Below is a detailed breakdown of each field in the YAML configuration, including the new `name` field.
-
----
-
-### `name`
-- **Description**: A unique identifier or nickname for the agent, included in the system prompt to personalize its identity.
-- **Type**: String (optional)
-- **Default**: `null`
-- **Example**:
-  ```yaml
-  name: "MathBot"
-  ```
-- **Notes**: If provided, the agent introduces itself with this name in the system prompt (e.g., "I am MathBot, an AI assistant.").
-
----
-
-### `model`
-- **Description**: Specifies the language model used by the agent for reasoning and text generation. Must be compatible with the `litellm` library.
-- **Type**: String
-- **Default**: `"gemini/gemini-2.0-flash"`
-- **Example**:
-  ```yaml
-  model: "deepseek/deepseek-chat"
-  ```
-
----
-
-### `max_iterations`
-- **Description**: Sets the maximum number of reasoning steps the agent will take to solve a task using the ReAct framework.
-- **Type**: Integer
-- **Default**: `5`
-- **Example**:
-  ```yaml
-  max_iterations: 10
-  ```
-
----
-
-### `tools`
-- **Description**: A list of pre-instantiated tools (as Python objects) to include in the agent. Typically used programmatically rather than in YAML.
-- **Type**: List of `Tool` or callable objects (optional)
-- **Default**: `null`
-- **Example** (Programmatic):
-  ```python
-  config = AgentConfig(tools=[my_custom_tool])
-  ```
-
----
-
-### `max_history_tokens`
-- **Description**: Limits the number of tokens stored in the agent’s history, affecting memory usage and context retention.
-- **Type**: Integer
-- **Default**: `8000` (from `MAX_HISTORY_TOKENS`)
-- **Example**:
-  ```yaml
-  max_history_tokens: 4000
-  ```
-
----
-
-### `toolbox_directory`
-- **Description**: Directory where custom toolbox modules are stored (used for local tool development).
-- **Type**: String
-- **Default**: `"toolboxes"`
-- **Example**:
-  ```yaml
-  toolbox_directory: "custom_tools"
-  ```
-
----
-
-### `enabled_toolboxes`
-- **Description**: A list of toolbox names to load from registered entry points (e.g., installed Python packages).
-- **Type**: List of strings (optional)
-- **Default**: `null`
-- **Example**:
-  ```yaml
-  enabled_toolboxes:
-    - "math_tools"
-    - "text_tools"
-  ```
-
----
-
-### `reasoner_name` (Legacy)
-- **Description**: Specifies the name of the reasoner plugin to use (older format, kept for compatibility).
-- **Type**: String
-- **Default**: `"default"`
-- **Example**:
-  ```yaml
-  reasoner_name: "advanced_reasoner"
-  ```
-
----
-
-### `executor_name` (Legacy)
-- **Description**: Specifies the name of the executor plugin to use (older format, kept for compatibility).
-- **Type**: String
-- **Default**: `"default"`
-- **Example**:
-  ```yaml
-  executor_name: "secure_executor"
-  ```
-
----
-
-### `personality`
-- **Description**: Defines the agent’s personality, influencing its system prompt. Can be a simple string (legacy) or a structured dictionary.
-- **Type**: String or Dictionary (optional)
-- **Default**: `null`
-- **Subfields (when dictionary)**:
-  - `traits`: List of personality traits (e.g., "witty", "helpful").
-  - `tone`: Tone of responses (e.g., "formal", "casual").
-  - `humor_level`: Level of humor (e.g., "low", "medium", "high").
-- **Examples**:
-  - Simple:
-    ```yaml
-    personality: "witty"
-    ```
-  - Structured:
-    ```yaml
-    personality:
-      traits:
-        - "witty"
-        - "helpful"
-      tone: "informal"
-      humor_level: "medium"
-    ```
-
----
-
-### `backstory`
-- **Description**: Provides a backstory for the agent, included in the system prompt. Can be a string (legacy) or a dictionary.
-- **Type**: String or Dictionary (optional)
-- **Default**: `null`
-- **Subfields (when dictionary)**:
-  - `origin`: Where the agent was created.
-  - `purpose`: The agent’s intended purpose.
-  - `experience`: Relevant past experience.
-- **Examples**:
-  - Simple:
-    ```yaml
-    backstory: "A seasoned AI assistant."
-    ```
-  - Structured:
-    ```yaml
-    backstory:
-      origin: "Created by Quantalogic."
-      purpose: "Solve complex problems."
-      experience: "Trained on 10,000+ math tasks."
-    ```
-
----
-
-### `sop`
-- **Description**: Standard Operating Procedure (SOP) as a multi-line string, guiding the agent’s behavior.
-- **Type**: String (optional)
-- **Default**: `null`
-- **Example**:
-  ```yaml
-  sop: |
-    Always provide clear, concise answers.
-    Prioritize accuracy over speed.
-  ```
-
----
-
-### `tools_config`
-- **Description**: Configures specific tools or toolboxes, allowing enabling/disabling and setting properties.
-- **Type**: List of dictionaries (optional)
-- **Default**: `null`
-- **Subfields**:
-  - `name`: Name of the tool or toolbox (matches `tool.name` or `tool.toolbox_name`).
-  - `enabled`: Boolean to include/exclude the tool/toolbox (default: `true`).
-  - Additional key-value pairs: Properties to set on the tool (e.g., `config`, `precision`).
-- **Example**:
-  ```yaml
-  tools_config:
-    - name: "math_tools"
-      enabled: true
-      config:
-        precision: "high"
-    - name: "agent_tool"
-      enabled: false
-      model: "custom_model"
-  ```
-
----
-
-### `reasoner`
-- **Description**: Configures the reasoning component, replacing `reasoner_name` with added flexibility.
-- **Type**: Dictionary (optional)
-- **Default**: `{"name": "default"}`
-- **Subfields**:
-  - `name`: Name of the reasoner plugin (e.g., `"default"`).
-  - `config`: Dictionary of reasoner-specific settings (e.g., `temperature`, `max_tokens`).
-- **Example**:
-  ```yaml
-  reasoner:
-    name: "default"
-    config:
-      temperature: 0.7
-      max_tokens: 1500
-  ```
-
----
-
-### `executor`
-- **Description**: Configures the execution component, replacing `executor_name`.
-- **Type**: Dictionary (optional)
-- **Default**: `{"name": "default"}`
-- **Subfields**:
-  - `name`: Name of the executor plugin (e.g., `"default"`).
-  - `config`: Dictionary of executor-specific settings (e.g., `timeout`).
-- **Example**:
-  ```yaml
-  executor:
-    name: "default"
-    config:
-      timeout: 600
-  ```
-
----
-
-### `profile`
-- **Description**: Selects a predefined agent profile, setting defaults for other fields.
-- **Type**: String (optional)
-- **Default**: `null`
-- **Supported Profiles**:
-  - `"math_expert"`: Configures for mathematical tasks.
-  - `"creative_writer"`: Configures for creative tasks.
-- **Example**:
-  ```yaml
-  profile: "math_expert"
-  ```
-
----
-
-### `customizations`
-- **Description**: Overrides or extends profile defaults with custom settings.
-- **Type**: Dictionary (optional)
-- **Default**: `null`
-- **Example**:
-  ```yaml
-  profile: "math_expert"
-  customizations:
-    personality:
-      traits:
-        - "witty"
-    tools_config:
-      - name: "advanced_calculus"
-        enabled: true
-  ```
-
----
-
-## Tool Configuration Details
-(unchanged from previous documentation, included for completeness)
-
----
-
-## Backward Compatibility
-
-The updated configuration format remains fully compatible with older versions:
-- **New Field (`name`)**: Optional, defaults to `null`, so existing configs without `name` work unchanged.
-- **Legacy Fields**: `reasoner_name`, `executor_name`, `personality` (string), and `backstory` (string) are still supported.
-- **Minimal Configs**: A simple config like:
-  ```yaml
-  model: "gemini/gemini-2.0-flash"
-  ```
-  functions as before.
-
----
-
-## Usage
-
-### Example with Name
-```yaml
-name: "MathWizard"
-model: "gemini/gemini-2.0-flash"
-max_iterations: 5
-profile: "math_expert"
-```
-
-The agent will introduce itself as: "I am MathWizard, an AI assistant with the following personality traits: precise, logical."
-
----
-
-## Best Practices
-
-- **Use `name`**: Assign a unique name to distinguish agents in multi-agent setups or logs.
-- **Profiles**: Leverage `profile` for quick setup, refining with `customizations`.
-- **Secrets**: Use `{{ env.VAR_NAME }}` for sensitive data in `tools_config`.
-

quantalogic/codeact/examples/agent_sample.yaml

@@ -1,29 +0,0 @@
-# Model configuration
-model: "deepseek/deepseek-chat"
-# Task-solving parameters
-max_iterations: 5
-max_history_tokens: 2000
-# Toolbox and tool configuration
-toolbox_directory: "toolboxes"
-enabled_toolboxes:
-  - math_tools
-# Component selection
-reasoner:
-  name: "default"
-executor:
-  name: "default"
-# Agent personality and behavior
-profile: "math_expert"
-customizations:
-  personality:
-    traits:
-      - witty
-tools_config:
-  - name: "math_tools"
-    enabled: true
-    config:
-      precision: "high"
-sop: |
-  Always provide clear, concise answers.
-  Prioritize mathematical accuracy and user satisfaction.
-  Inject humor where appropriate to keep interactions engaging.

quantalogic/codeact/executor.py

@@ -1,186 +0,0 @@
-import asyncio
-import types
-from abc import ABC, abstractmethod
-from typing import Any, Callable, Dict, List, Optional  # Added Optional, Any
-
-from lxml import etree
-from quantalogic_pythonbox import AsyncExecutionResult, execute_async
-
-from quantalogic.tools import Tool
-
-from .events import ToolExecutionCompletedEvent, ToolExecutionErrorEvent, ToolExecutionStartedEvent
-from .tools_manager import ToolRegistry
-from .utils import validate_code
-from .xml_utils import XMLResultHandler
-
-
-class BaseExecutor(ABC):
-    """Abstract base class for execution components."""
-
-    @abstractmethod
-    async def execute_action(self, code: str, context_vars: Dict, step: int, timeout: int) -> str:
-        pass
-
-    @abstractmethod
-    def register_tool(self, tool: Tool) -> None:
-        pass
-
-
-class Executor(BaseExecutor):
-    """Manages action execution and context updates with dynamic tool registration."""
-
-    def __init__(self, tools: List[Tool], notify_event: Callable, config: Optional[Dict[str, Any]] = None, verbose: bool = True):
-        self.registry = ToolRegistry()
-        for tool in tools:
-            self.registry.register(tool)
-        self.tools: Dict[tuple[str, str], Tool] = self.registry.tools
-        self.notify_event = notify_event
-        self.config = config or {}
-        self.verbose = verbose
-        self.tool_namespace = self._build_tool_namespace()
-
-    def _build_tool_namespace(self) -> Dict:
-        """Build the namespace with tools grouped by toolbox using SimpleNamespace."""
-        if not self.verbose:
-            toolboxes = {}
-            for (toolbox_name, tool_name), tool in self.tools.items():
-                if toolbox_name not in toolboxes:
-                    toolboxes[toolbox_name] = types.SimpleNamespace()
-                setattr(toolboxes[toolbox_name], tool_name, tool.async_execute)
-            return {
-                "asyncio": asyncio,
-                "context_vars": {},
-                **toolboxes,
-            }
-
-        def wrap_tool(tool):
-            async def wrapped_tool(**kwargs):
-                current_step = self.tool_namespace.get("current_step", None)
-                parameters_summary = {
-                    k: str(v)[:100] + "..." if len(str(v)) > 100 else str(v) for k, v in kwargs.items()
-                }
-                await self.notify_event(
-                    ToolExecutionStartedEvent(
-                        event_type="ToolExecutionStarted",
-                        step_number=current_step,
-                        tool_name=f"{tool.toolbox_name or 'default'}.{tool.name}",
-                        parameters_summary=parameters_summary,
-                    )
-                )
-                try:
-                    result = await tool.async_execute(**kwargs)
-                    result_summary = str(result)[:100] + "..." if len(str(result)) > 100 else str(result)
-                    await self.notify_event(
-                        ToolExecutionCompletedEvent(
-                            event_type="ToolExecutionCompleted",
-                            step_number=current_step,
-                            tool_name=f"{tool.toolbox_name or 'default'}.{tool.name}",
-                            result_summary=result_summary,
-                        )
-                    )
-                    return result
-                except Exception as e:
-                    await self.notify_event(
-                        ToolExecutionErrorEvent(
-                            event_type="ToolExecutionError",
-                            step_number=current_step,
-                            tool_name=f"{tool.toolbox_name or 'default'}.{tool.name}",
-                            error=str(e)
-                        )
-                    )
-                    raise
-
-            return wrapped_tool
-
-        toolboxes = {}
-        for (toolbox_name, tool_name), tool in self.tools.items():
-            if toolbox_name not in toolboxes:
-                toolboxes[toolbox_name] = types.SimpleNamespace()
-            setattr(toolboxes[toolbox_name], tool_name, wrap_tool(tool))
-
-        return {
-            "asyncio": asyncio,
-            "context_vars": {},
-            **toolboxes,
-        }
-
-    def register_tool(self, tool: Tool) -> None:
-        """Register a new tool dynamically at runtime."""
-        self.registry.register(tool)
-        key = (tool.toolbox_name or "default", tool.name)
-        self.tools[key] = tool
-        toolbox_name = tool.toolbox_name or "default"
-        if toolbox_name not in self.tool_namespace:
-            self.tool_namespace[toolbox_name] = types.SimpleNamespace()
-        setattr(self.tool_namespace[toolbox_name], tool.name, 
-                self._wrap_tool(tool) if self.verbose else tool.async_execute)
-
-    def _wrap_tool(self, tool: Tool) -> Callable:
-        """Wrap a tool function to handle execution events (internal use)."""
-        async def wrapped_tool(**kwargs):
-            current_step = self.tool_namespace.get("current_step", None)
-            parameters_summary = {k: str(v)[:100] + "..." if len(str(v)) > 100 else str(v) for k, v in kwargs.items()}
-            await self.notify_event(
-                ToolExecutionStartedEvent(
-                    event_type="ToolExecutionStarted",
-                    step_number=current_step,
-                    tool_name=f"{tool.toolbox_name or 'default'}.{tool.name}",
-                    parameters_summary=parameters_summary,
-                )
-            )
-            try:
-                result = await tool.async_execute(**kwargs)
-                result_summary = str(result)[:100] + "..." if len(str(result)) > 100 else str(result)
-                await self.notify_event(
-                    ToolExecutionCompletedEvent(
-                        event_type="ToolExecutionCompleted",
-                        step_number=current_step,
-                        tool_name=f"{tool.toolbox_name or 'default'}.{tool.name}",
-                        result_summary=result_summary,
-                    )
-                )
-                return result
-            except Exception as e:
-                await self.notify_event(
-                    ToolExecutionErrorEvent(
-                        event_type="ToolExecutionError",
-                        step_number=current_step,
-                        tool_name=f"{tool.toolbox_name or 'default'}.{tool.name}",
-                        error=str(e)
-                    )
-                )
-                raise
-
-        return wrapped_tool
-
-    async def execute_action(self, code: str, context_vars: Dict, step: int, timeout: int = 300) -> str:
-        """Execute the generated code and return the result with local variables, setting the step number."""
-        self.tool_namespace["context_vars"] = context_vars
-        self.tool_namespace["current_step"] = step
-        timeout = self.config.get("timeout", timeout)  # Use config timeout if provided
-        if not validate_code(code):
-            return etree.tostring(
-                etree.Element("ExecutionResult", status="Error", message="Code lacks async main()"), encoding="unicode"
-            )
-
-        try:
-            result: AsyncExecutionResult = await execute_async(
-                code=code,
-                timeout=timeout,
-                entry_point="main",
-                allowed_modules=["asyncio", "math", "random", "time"],
-                namespace=self.tool_namespace,
-                ignore_typing=True
-            )
-            if result.local_variables:
-                context_vars.update(
-                    {k: v for k, v in result.local_variables.items() if not k.startswith("__") and not callable(v)}
-                )
-            return XMLResultHandler.format_execution_result(result)
-        except Exception as e:
-            root = etree.Element("ExecutionResult")
-            root.append(etree.Element("Status", text="Error"))
-            root.append(etree.Element("Value", text=f"Execution error: {str(e)}"))
-            root.append(etree.Element("ExecutionTime", text="0.00 seconds"))
-            root.append(etree.Element("Completed", text="false"))
-            return etree.tostring(root, pretty_print=True, encoding="unicode")

quantalogic/codeact/history_manager.py

@@ -1,94 +0,0 @@
-"""History management module for storing and formatting agent steps."""
-
-from typing import Dict, List
-
-from loguru import logger
-from lxml import etree
-
-from .xml_utils import XMLResultHandler
-
-
-class HistoryManager:
-    """Manages the storage and formatting of agent step history with persistent context."""
-    
-    def __init__(self, max_tokens: int = 64*1024, system_prompt: str = "", task_description: str = ""):
-        """
-        Initialize the HistoryManager with a token limit and persistent context.
-
-        Args:
-            max_tokens (int): Maximum number of tokens for history formatting (default: 16000).
-            system_prompt (str): Persistent system-level instructions for the agent (default: "").
-            task_description (str): Persistent description of the current task (default: "").
-        """
-        self.max_tokens: int = max_tokens
-        self.system_prompt: str = system_prompt
-        self.task_description: str = task_description
-        self.store: List[Dict] = []
-        logger.debug(f"Initialized HistoryManager with system_prompt: '{system_prompt}', task_description: '{task_description}'")
-
-    def add_step(self, step_data: Dict) -> None:
-        """
-        Add a step to the history store.
-
-        Args:
-            step_data (Dict): Dictionary containing step details (step_number, thought, action, result).
-        """
-        self.store.append(step_data)
-        logger.debug(f"Added step {step_data['step_number']} to history")
-
-    def format_history(self, max_iterations: int) -> str:
-        """
-        Format the history with available variables, truncating to fit within max_tokens.
-
-        Args:
-            max_iterations (int): Maximum allowed iterations for context.
-
-        Returns:
-            str: Formatted string of previous steps, or "No previous steps" if empty.
-        """
-        included_steps: List[str] = []
-        total_tokens: int = 0
-        for step in reversed(self.store):
-            try:
-                root = etree.fromstring(step['result'])
-                vars_elem = root.find("Variables")
-                available_vars = (
-                    [var.get('name') for var in vars_elem.findall("Variable")]
-                    if vars_elem is not None else []
-                )
-            except etree.XMLSyntaxError:
-                available_vars = []
-
-            step_str: str = (
-                f"===== Step {step['step_number']} of {max_iterations} max =====\n"
-                f"Thought:\n{step['thought']}\n\n"
-                f"Action:\n{step['action']}\n\n"
-                f"Result:\n{XMLResultHandler.format_result_summary(step['result']) if step.get('result') else 'No result available'}\n"
-                f"Available variables: {', '.join(available_vars) or 'None'}"
-            )
-            step_tokens: int = len(step_str.split())
-            if total_tokens + step_tokens > self.max_tokens:
-                break
-            included_steps.append(step_str)
-            total_tokens += step_tokens
-        return "\n".join(reversed(included_steps)) or "No previous steps"
-
-    def get_full_context(self, max_iterations: int) -> str:
-        """
-        Return the full context including system prompt, task description, and formatted history.
-
-        Args:
-            max_iterations (int): Maximum allowed iterations for history formatting.
-
-        Returns:
-            str: Combined string of system prompt, task description, and history.
-        """
-        context_parts = []
-        if self.system_prompt:
-            context_parts.append(f"System Prompt:\n{self.system_prompt}")
-        if self.task_description:
-            context_parts.append(f"Task Description:\n{self.task_description}")
-        history_str = self.format_history(max_iterations)
-        if history_str != "No previous steps":
-            context_parts.append(f"History:\n{history_str}")
-        return "\n\n".join(context_parts)