# Quantalogic CodeAct
**Quantalogic CodeAct** is a powerful, modular framework for building AI agents that solve complex tasks through iterative reasoning and action. Built on the ReAct (Reasoning and Acting) paradigm, it integrates language models (via `litellm`), a robust tool ecosystem, and a secure Python execution environment powered by [quantalogic-pythonbox](https://github.com/quantalogic/quantalogic-pythonbox). With intuitive interfaces (CLI, interactive shell, and SDK), CodeAct supports a wide range of applications—from mathematical problem-solving to conversational interactions—making it ideal for developers, researchers, and end-users.
## Table of Contents
- [Why CodeAct?](#why-codeact)
- [What is CodeAct?](#what-is-codeact)
- [Core Modules](#core-modules)
- [CodeAct Principle and ReAct Paradigm](#codeact-principle-and-react-paradigm)
- [ReAct Agent](#react-agent)
- [Architecture](#architecture)
- [How to Use CodeAct](#how-to-use-codeact)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Interactive Shell](#interactive-shell)
- [Command-Line Interface (CLI)](#command-line-interface-cli)
- [Using the Agent SDK](#using-the-agent-sdk)
- [Commands](#commands)
- [Shell Commands](#shell-commands)
- [CLI Commands](#cli-commands)
- [Examples](#examples)
- [Configuration](#configuration)
- [Toolbox System](#toolbox-system)
- [Memory Systems](#memory-systems)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [References](#references)
- [License](#license)
---
## Why CodeAct?
Modern AI agents must tackle intricate, multi-step tasks, adapt to diverse contexts, and provide seamless user experiences. CodeAct meets these demands by offering:
- **Robust Task Solving**: Decomposes complex problems into iterative reasoning and executable actions for precise solutions.
- **Modularity and Extensibility**: Supports plug-and-play components like tools, reasoners, and executors for domain-specific customization.
- **Accessible Interfaces**: Provides CLI, interactive shell, and SDK, catering to both casual users and developers.
- **Scalability**: Handles applications from simple calculations to advanced automation and conversational workflows.
Whether you're automating processes, conducting AI research, or seeking an intelligent assistant, CodeAct delivers flexibility and power.
---
## What is CodeAct?
Quantalogic CodeAct is a framework within the Quantalogic ecosystem that enables the creation of AI agents capable of reasoning and acting using executable Python code as the primary action mechanism. It leverages the ReAct paradigm, integrating language models, extensible tools, and secure execution environments to solve tasks, engage in dialogues, and support custom workflows.
### Core Modules
CodeAct’s modular design ensures each component has a clear responsibility, making it easy to extend or customize:
- **`agent.py`**: Implements the `CodeActAgent`, orchestrating the ReAct loop.
- **`agent_config.py`**: Manages agent configuration via YAML files.
- **`reasoner.py`**: Generates reasoning steps and code using language models.
- **`executor.py`**: Safely executes Python code and tool calls using PythonBox.
- **`tools_manager.py`**: Registers and manages tools and toolboxes.
- **`tools/`**: Includes built-in tools (e.g., `AgentTool`, `RetrieveMessageTool`).
- **`conversation_manager.py`**: Tracks conversation history for context-aware interactions.
- **`working_memory.py`**: Manages task-specific execution history.
- **`completion_evaluator.py`**: Evaluates task completion using LLM verification.
- **`events.py`**: Defines event and result models with Pydantic.
- **`constants.py`**: Stores project constants (e.g., default model, token limits).
- **`cli.py` & `cli_commands/`**: Provides CLI entry points and subcommands.
- **`templates/` & `prompts/`**: Jinja2 templates for LLM prompts and responses.
- **`plugin_manager.py`**: Enables dynamic loading of plugins and toolboxes.
- **`xml_utils.py`**: Handles XML formatting for results and actions.
- **`llm_util.py`**: Manages LLM completion with streaming support.
### CodeAct Principle and ReAct Paradigm
CodeAct is inspired by the **ReAct paradigm** from ["ReAct: Synergizing Reasoning and Acting in Language Models"](https://arxiv.org/abs/2210.03629) (Yao et al., 2022) and advanced in ["Executable Code Actions Elicit Better LLM Agents"](https://arxiv.org/abs/2402.01030) (Yang et al., 2024).
#### ReAct Paradigm
ReAct combines **reasoning** (generating plans or thoughts) with **acting** (executing actions) in an iterative loop:
1. **Reason**: Analyze the task and plan actions using an LLM.
2. **Act**: Execute actions (e.g., code, tool calls) in the environment.
3. **Iterate**: Incorporate feedback from actions to refine reasoning until task completion.
This synergy reduces errors, improves adaptability, and enhances interpretability by producing explicit reasoning traces alongside actions.
#### CodeAct Enhancement
CodeAct builds on ReAct by using **executable Python code** as the action format, leveraging LLMs’ code-generation capabilities. Key benefits include:
- **Unified Action Space**: Python code allows flexible tool composition, control flow, and error handling.
- **Secure Execution**: Powered by [quantalogic-pythonbox](https://github.com/quantalogic/quantalogic-pythonbox), ensuring safe code execution with resource limits.
- **Empirical Superiority**: The CodeAct paper demonstrates up to 20% higher success rates compared to JSON or text-based actions.
**Example**:
```plaintext
Task: "Calculate 3 + 5"
Reasoning: "I’ll write a Python script to perform the addition."
Action:
<execute>
result = 3 + 5
print(result)
</execute>
Result: "8"
```
### ReAct Agent
The `CodeActAgent` is the heart of CodeAct, implementing the ReAct loop:
1. **Task Input**: Receives a task (e.g., "Calculate the factorial of 5").
2. **Reasoning Phase**: Uses a `Reasoner` to generate a plan or Python code.
3. **Action Phase**: Employs an `Executor` to run the code or invoke tools.
4. **Evaluation**: Checks task completion via `CompletionEvaluator`, iterating if needed.
It maintains context through `WorkingMemory` and `ConversationManager`, supporting multi-step tasks and dialogues.
### Architecture
CodeAct’s architecture is modular and scalable, as shown below:
```mermaid
graph TD
classDef user fill:#ffe2e2,stroke:#e3bcbc,stroke-width:2px,color:#333;
classDef shell fill:#e2f0ff,stroke:#bcd5e3,stroke-width:2px,color:#333;
classDef cli fill:#e2ffe9,stroke:#bce3c8,stroke-width:2px,color:#333;
classDef sdk fill:#f2e2ff,stroke:#d3bce3,stroke-width:2px,color:#333;
classDef agent fill:#fff7e2,stroke:#e3d9bc,stroke-width:2px,color:#333;
classDef reasoner fill:#e2fff7,stroke:#bce3d9,stroke-width:2px,color:#333;
classDef executor fill:#e2e7ff,stroke:#bcbce3,stroke-width:2px,color:#333;
classDef tools fill:#f9e2ff,stroke:#e3bcdc,stroke-width:2px,color:#333;
classDef pythonbox fill:#e2f7ff,stroke:#bcd5e3,stroke-width:2px,color:#333;
User[User] -->|Interacts| Shell[Shell Interface]
User -->|Runs| CLI[CLI Commands]
User -->|Programs| SDK[Agent SDK]
Shell -->|Commands| Agent[CodeActAgent]
CLI -->|Tasks| Agent
SDK -->|Controls| Agent
Agent -->|Reasons| Reasoner[Reasoner]
Agent -->|Executes| Executor[Executor]
Reasoner -->|Generates Actions| Agent
Executor -->|Uses| Tools[Tools]
Tools -->|Returns Results| Executor
Executor -->|Executes Code| PythonBox["Python Toolbox (PythonBox)"]
PythonBox -->|Returns Results| Executor
Executor -->|Updates Context| Agent
Agent -->|Responds| Shell
Agent -->|Outputs| CLI
Agent -->|Returns| SDK
class User user;
class Shell shell;
class CLI cli;
class SDK sdk;
class Agent agent;
class Reasoner reasoner;
class Executor executor;
class Tools tools;
class PythonBox pythonbox;
```
- **Agent**: Orchestrates the ReAct loop, managing state and history.
- **Reasoner**: Generates code or plans using LLMs (e.g., Gemini, DeepSeek).
- **Executor**: Executes actions securely with PythonBox.
- **Tools**: Modular functions for specialized tasks.
- **PythonBox**: Provides a sandboxed environment for safe code execution.
---
## How to Use CodeAct
### Installation
#### Prerequisites
- **Python**: 3.12 or higher
- **Poetry**: Install via `pip install poetry`
- **API Keys**: Required for LLMs (e.g., `GEMINI_API_KEY` for Gemini models)
#### Installation Steps
1. **Clone the Repository**:
```bash
git clone https://github.com/quantalogic/quantalogic-codeact.git
cd quantalogic-codeact
```
2. **Install Dependencies**:
```bash
poetry install
```
Alternatively, install via pip:
```bash
pip install quantalogic-codeact
```
3. **Set Environment Variables**:
```bash
export GEMINI_API_KEY="your-api-key"
```
4. **Verify Installation**:
```bash
poetry run quantalogic_codeact --help
```
### Quick Start
CodeAct offers two primary interaction modes: an **interactive shell** for real-time engagement and a **CLI** for direct task execution.
#### Interactive Shell
Start the shell:
```bash
poetry run quantalogic_codeact shell
```
Interact using commands like `/solve` for tasks or `/chat` for conversations. Example:
```
[cfg:config.yaml] [Agent] [codeact]> /solve "Calculate 2 + 2"
[Step 1 Result]
- Status: Success
- Value: 4
- Execution Time: 0.12 seconds
- Completed: True
[Final Answer]
4
```
#### Command-Line Interface (CLI)
Run tasks directly:
```bash
poetry run quantalogic_codeact task "Calculate 3 * 4" --streaming
```
List available resources:
```bash
poetry run quantalogic_codeact list-toolboxes
poetry run quantalogic_codeact list-models
```
### Using the Agent SDK
The Agent SDK enables programmatic control over agents, ideal for developers building custom applications. Below is an example integrating a custom tool and monitoring task progress.
```python
from quantalogic_codeact.codeact.agent import Agent
from quantalogic_codeact.codeact.agent_config import AgentConfig
from quantalogic_toolbox import create_tool, Tool
# Define a custom tool
@create_tool
async def factorial(n: int) -> int:
"""Calculate the factorial of a number."""
if n < 0:
raise ValueError("Factorial is not defined for negative numbers")
result = 1
for i in range(1, n + 1):
result *= i
return result
# Configure agent
config = AgentConfig(
model="deepseek/deepseek-chat",
max_iterations=5,
enabled_toolboxes=["math_tools"],
tools=[factorial],
personality={"traits": ["logical", "precise"]}
)
agent = Agent(config=config)
# Monitor progress
def monitor_event(event):
if event.event_type == "StepStarted":
print(f"Step {event.step_number} started")
elif event.event_type == "ActionExecuted":
print(f"Step {event.step_number} result: {event.result.to_summary()}")
elif event.event_type == "TaskCompleted":
print(f"Task completed with answer: {event.final_answer}")
agent.add_observer(monitor_event, ["StepStarted", "ActionExecuted", "TaskCompleted"])
# Solve a task
result = agent.sync_solve("Calculate the factorial of 5")
final_answer = result[-1].get("result", "No result")
print(f"Final Answer: {final_answer}")
# Chat asynchronously
async def run_chat():
response = await agent.chat("Explain factorials")
print(f"Explanation: {response}")
import asyncio
asyncio.run(run_chat())
```
**Example Output**:
```
Step 1 started
Step 1 result: - Status: Success
- Task Status: completed
- Result: 120
- Execution Time: 0.15 seconds
Task completed with answer: 120
Final Answer: 120
Explanation: A factorial of a non-negative integer n, denoted n!, is the product of all positive integers less than or equal to n. For example, 5! = 5 * 4 * 3 * 2 * 1 = 120.
```
**ReAct Loop Visualization**:
```mermaid
sequenceDiagram
participant U as User
participant A as Agent
participant R as Reasoner
participant E as Executor
participant T as Tools
U->>A: Solve "Factorial of 5"
A->>R: Generate plan
R-->>A: Plan: Use factorial tool
A->>E: Execute factorial(5)
E->>T: Call factorial tool
T-->>E: Result: 120
E-->>A: Result XML: 120
A-->>U: Final Answer: 120
```
### Commands
#### Shell Commands
Below is a comprehensive list of shell commands:
| Command | Description | Example Usage |
|-----------------------------|-------------------------------------------------------|-------------------------------------------|
| `/help [command]` | Show help for commands or a specific command | `/help solve` |
| `/chat <message>` | Send a chat message to the agent | `/chat How are you?` |
| `/solve <task>` | Solve a task | `/solve Calculate 2 + 2` |
| `/mode [chat|codeact]` | Switch between chat and task-solving modes | `/mode codeact` |
| `/stream [on|off]` | Toggle streaming output | `/stream on` |
| `/exit` | Exit the shell | `/exit` |
| `/history [n]` | Show last `n` messages (default: all) | `/history 5` |
| `/clear` | Clear conversation history | `/clear` |
| `/agent <name>` | Switch or show agent details | `/agent MathBot` |
| `/set <field> <value>` | Set a config field and create new agent | `/set model deepseek/deepseek-chat` |
| `/set temperature <value>` | Set or show LLM temperature (0 to 1) | `/set temperature 0.7` |
| `/config show` | Display current configuration | `/config show` |
| `/config save <file>` | Save config to a file | `/config save myconfig.yaml` |
| `/config load <file>` | Load config from a file | `/config load myconfig.yaml` |
| `/toolbox install <name>` | Install a toolbox | `/toolbox install math_tools` |
| `/toolbox uninstall <name>` | Uninstall a toolbox | `/toolbox uninstall math_tools` |
| `/toolbox enable <name>` | Enable a toolbox | `/toolbox enable math_tools` |
| `/toolbox disable <name>` | Disable a toolbox | `/toolbox disable math_tools` |
| `/toolbox installed` | Show installed toolboxes | `/toolbox installed` |
| `/toolbox tools <name>` | List tools in a toolbox | `/toolbox tools math_tools` |
| `/toolbox doc <name> <tool>` | Show tool documentation | `/toolbox doc math_tools integrate` |
| `/listmodels` | List available models | `/listmodels` |
| `/version` | Show package version | `/version` |
| `/tutorial` | Display a tutorial for new users | `/tutorial` |
| `/inputmode [single|multi]` | Toggle single-line or multiline input | `/inputmode multi` |
| `/contrast [on|off]` | Toggle high-contrast mode for accessibility | `/contrast on` |
| `/setmodel <model>` | Set model and switch to a new agent | `/setmodel deepseek/deepseek-chat` |
| `/loglevel [level]` | Set log level (DEBUG|INFO|WARNING|ERROR|CRITICAL) | `/loglevel DEBUG` |
| `/save <filename>` | Save conversation history to a file | `/save history.json` |
| `/load <filename>` | Load conversation history from a file | `/load history.json` |
| `/compose` | Compose input in an external editor | `/compose` |
| `/edit [INDEX_OR_ID]` | Edit a previous user message | `/edit 3` |
#### CLI Commands
```bash
Usage: quantalogic_codeact [OPTIONS] COMMAND [ARGS]...
Options:
--config, -c PATH Path to the configuration file to use
--loglevel, -l TEXT Override log level: DEBUG|INFO|WARNING|ERROR|CRITICAL
--install-completion Install shell completion
--show-completion Show shell completion script
--help Show this message and exit
Commands:
shell Start the interactive shell
task Run a task with event monitoring
create-toolbox Create a new toolbox project
config-load Load a configuration file
list-models List available LLM models
list-toolboxes List installed toolboxes
list-reasoners List available reasoners
list-executors List available executors
tool-info Display tool information
install-toolbox Install a toolbox
uninstall-toolbox Uninstall a toolbox
config Manage configuration (subcommands: show, reset)
toolbox Manage toolboxes (subcommands: install, uninstall, tools, doc)
```
**Tip**: Use `--config` to specify a custom configuration file:
```bash
quantalogic_codeact task "Solve 2 + 2" -c ./myconfig.yaml
```
### Examples
#### Shell
```plaintext
[cfg:config.yaml] [Agent] [codeact]> /chat Tell me a joke
Why did the computer go to art school? Because it wanted to learn how to draw a better "byte"!
```
#### CLI
```bash
poetry run quantalogic_codeact task "Calculate the square root of 16" --model gemini/gemini-2.0-flash
```
**Output**:
```
[Final Answer]
4
```
#### SDK
```python
from quantalogic_codeact.codeact.agent import Agent
agent = Agent()
result = agent.sync_solve("What is 3 * 5?")
print(result[-1]["result"]) # Output: 15
```
### Configuration
CodeAct uses a YAML configuration file, typically at `~/.quantalogic/config.yaml`. Example:
```yaml
model: "gemini/gemini-2.0-flash"
max_iterations: 5
max_history_tokens: 2000
enabled_toolboxes:
- math_tools
reasoner:
name: "default"
config:
temperature: 0.7
executor:
name: "default"
personality:
traits:
- witty
- helpful
tools_config:
- name: math_tools
enabled: true
config:
precision: "high"
```
Manage configurations in the shell with `/config save` or `/config load`, or edit the file directly.
### Toolbox System
Toolboxes extend CodeAct’s functionality with modular, reusable tools. Built-in toolboxes include `math_tools` for calculations. Create custom toolboxes with:
```bash
poetry run quantalogic_codeact create-toolbox my_toolbox
```
This generates a project structure with a `tools.py` file for defining tools. Example:
```python
@create_tool
async def echo_tool(message: str) -> str:
"""Echoes the input message."""
return f"Echo: {message}"
```
For detailed guidance, see [Toolbox Documentation](quantalogic_codeact/docs/01-quantalogic-toolbox.md), covering toolbox creation, tool registration, and management.
### Memory Systems
CodeAct employs two memory systems:
- **WorkingMemory**: Tracks task-specific steps, thoughts, actions, and results.
- **ConversationManager**: Stores user-agent interaction history for context-aware dialogues.
These systems enable multi-step reasoning and persistent conversations. See [Memory Systems Documentation](quantalogic_codeact/docs/02-quantalogic-codeagent-memory.md) for implementation details and examples.
### Troubleshooting
- **API Key Issues**: Verify `GEMINI_API_KEY` or other LLM keys are set.
- **Dependency Errors**: Run `poetry install` to ensure all packages are installed.
- **Timeout Errors**: Increase `--timeout` in CLI or `timeout` in SDK config.
- **Tool Failures**: Use `/toolbox doc <toolbox> <tool>` to check tool arguments.
- **Logging**: Enable debug mode with `/loglevel DEBUG` for detailed logs.
---
## Contributing
Contributions are welcome! Please follow [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines on code style, testing, and workflows.
## References
- Yao, S., et al. (2022). "ReAct: Synergizing Reasoning and Acting in Language Models." [arXiv:2210.03629](https://arxiv.org/abs/2210.03629).
- Yang, J., et al. (2024). "Executable Code Actions Elicit Better LLM Agents." [arXiv:2402.01030](https://arxiv.org/abs/2402.01030).
- Quantalogic PythonBox: [github.com/quantalogic/quantalogic-pythonbox](https://github.com/quantalogic/quantalogic-pythonbox).
## License
Quantalogic CodeAct is licensed under the **Apache License, Version 2.0**. See [LICENSE](../../LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "quantalogic-codeact",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Raphael Mansuy",
"author_email": "raphae.mansuy@quantalogic.app",
"download_url": "https://files.pythonhosted.org/packages/6b/cb/d6aa6f7dd8e45180a5f68e46290288ea07f67c0796925f4343584348df85/quantalogic_codeact-0.100.0.tar.gz",
"platform": null,
"description": "# Quantalogic CodeAct\n\n**Quantalogic CodeAct** is a powerful, modular framework for building AI agents that solve complex tasks through iterative reasoning and action. Built on the ReAct (Reasoning and Acting) paradigm, it integrates language models (via `litellm`), a robust tool ecosystem, and a secure Python execution environment powered by [quantalogic-pythonbox](https://github.com/quantalogic/quantalogic-pythonbox). With intuitive interfaces (CLI, interactive shell, and SDK), CodeAct supports a wide range of applications\u2014from mathematical problem-solving to conversational interactions\u2014making it ideal for developers, researchers, and end-users.\n\n## Table of Contents\n- [Why CodeAct?](#why-codeact)\n- [What is CodeAct?](#what-is-codeact)\n - [Core Modules](#core-modules)\n - [CodeAct Principle and ReAct Paradigm](#codeact-principle-and-react-paradigm)\n - [ReAct Agent](#react-agent)\n - [Architecture](#architecture)\n- [How to Use CodeAct](#how-to-use-codeact)\n - [Installation](#installation)\n - [Quick Start](#quick-start)\n - [Interactive Shell](#interactive-shell)\n - [Command-Line Interface (CLI)](#command-line-interface-cli)\n - [Using the Agent SDK](#using-the-agent-sdk)\n - [Commands](#commands)\n - [Shell Commands](#shell-commands)\n - [CLI Commands](#cli-commands)\n - [Examples](#examples)\n - [Configuration](#configuration)\n - [Toolbox System](#toolbox-system)\n - [Memory Systems](#memory-systems)\n - [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [References](#references)\n- [License](#license)\n\n---\n\n## Why CodeAct?\n\nModern AI agents must tackle intricate, multi-step tasks, adapt to diverse contexts, and provide seamless user experiences. CodeAct meets these demands by offering:\n\n- **Robust Task Solving**: Decomposes complex problems into iterative reasoning and executable actions for precise solutions.\n- **Modularity and Extensibility**: Supports plug-and-play components like tools, reasoners, and executors for domain-specific customization.\n- **Accessible Interfaces**: Provides CLI, interactive shell, and SDK, catering to both casual users and developers.\n- **Scalability**: Handles applications from simple calculations to advanced automation and conversational workflows.\n\nWhether you're automating processes, conducting AI research, or seeking an intelligent assistant, CodeAct delivers flexibility and power.\n\n---\n\n## What is CodeAct?\n\nQuantalogic CodeAct is a framework within the Quantalogic ecosystem that enables the creation of AI agents capable of reasoning and acting using executable Python code as the primary action mechanism. It leverages the ReAct paradigm, integrating language models, extensible tools, and secure execution environments to solve tasks, engage in dialogues, and support custom workflows.\n\n### Core Modules\n\nCodeAct\u2019s modular design ensures each component has a clear responsibility, making it easy to extend or customize:\n\n- **`agent.py`**: Implements the `CodeActAgent`, orchestrating the ReAct loop.\n- **`agent_config.py`**: Manages agent configuration via YAML files.\n- **`reasoner.py`**: Generates reasoning steps and code using language models.\n- **`executor.py`**: Safely executes Python code and tool calls using PythonBox.\n- **`tools_manager.py`**: Registers and manages tools and toolboxes.\n- **`tools/`**: Includes built-in tools (e.g., `AgentTool`, `RetrieveMessageTool`).\n- **`conversation_manager.py`**: Tracks conversation history for context-aware interactions.\n- **`working_memory.py`**: Manages task-specific execution history.\n- **`completion_evaluator.py`**: Evaluates task completion using LLM verification.\n- **`events.py`**: Defines event and result models with Pydantic.\n- **`constants.py`**: Stores project constants (e.g., default model, token limits).\n- **`cli.py` & `cli_commands/`**: Provides CLI entry points and subcommands.\n- **`templates/` & `prompts/`**: Jinja2 templates for LLM prompts and responses.\n- **`plugin_manager.py`**: Enables dynamic loading of plugins and toolboxes.\n- **`xml_utils.py`**: Handles XML formatting for results and actions.\n- **`llm_util.py`**: Manages LLM completion with streaming support.\n\n### CodeAct Principle and ReAct Paradigm\n\nCodeAct is inspired by the **ReAct paradigm** from [\"ReAct: Synergizing Reasoning and Acting in Language Models\"](https://arxiv.org/abs/2210.03629) (Yao et al., 2022) and advanced in [\"Executable Code Actions Elicit Better LLM Agents\"](https://arxiv.org/abs/2402.01030) (Yang et al., 2024).\n\n#### ReAct Paradigm\nReAct combines **reasoning** (generating plans or thoughts) with **acting** (executing actions) in an iterative loop:\n1. **Reason**: Analyze the task and plan actions using an LLM.\n2. **Act**: Execute actions (e.g., code, tool calls) in the environment.\n3. **Iterate**: Incorporate feedback from actions to refine reasoning until task completion.\n\nThis synergy reduces errors, improves adaptability, and enhances interpretability by producing explicit reasoning traces alongside actions.\n\n#### CodeAct Enhancement\nCodeAct builds on ReAct by using **executable Python code** as the action format, leveraging LLMs\u2019 code-generation capabilities. Key benefits include:\n- **Unified Action Space**: Python code allows flexible tool composition, control flow, and error handling.\n- **Secure Execution**: Powered by [quantalogic-pythonbox](https://github.com/quantalogic/quantalogic-pythonbox), ensuring safe code execution with resource limits.\n- **Empirical Superiority**: The CodeAct paper demonstrates up to 20% higher success rates compared to JSON or text-based actions.\n\n**Example**:\n```plaintext\nTask: \"Calculate 3 + 5\"\nReasoning: \"I\u2019ll write a Python script to perform the addition.\"\nAction:\n<execute>\nresult = 3 + 5\nprint(result)\n</execute>\nResult: \"8\"\n```\n\n### ReAct Agent\n\nThe `CodeActAgent` is the heart of CodeAct, implementing the ReAct loop:\n1. **Task Input**: Receives a task (e.g., \"Calculate the factorial of 5\").\n2. **Reasoning Phase**: Uses a `Reasoner` to generate a plan or Python code.\n3. **Action Phase**: Employs an `Executor` to run the code or invoke tools.\n4. **Evaluation**: Checks task completion via `CompletionEvaluator`, iterating if needed.\n\nIt maintains context through `WorkingMemory` and `ConversationManager`, supporting multi-step tasks and dialogues.\n\n### Architecture\n\nCodeAct\u2019s architecture is modular and scalable, as shown below:\n\n```mermaid\ngraph TD\n classDef user fill:#ffe2e2,stroke:#e3bcbc,stroke-width:2px,color:#333;\n classDef shell fill:#e2f0ff,stroke:#bcd5e3,stroke-width:2px,color:#333;\n classDef cli fill:#e2ffe9,stroke:#bce3c8,stroke-width:2px,color:#333;\n classDef sdk fill:#f2e2ff,stroke:#d3bce3,stroke-width:2px,color:#333;\n classDef agent fill:#fff7e2,stroke:#e3d9bc,stroke-width:2px,color:#333;\n classDef reasoner fill:#e2fff7,stroke:#bce3d9,stroke-width:2px,color:#333;\n classDef executor fill:#e2e7ff,stroke:#bcbce3,stroke-width:2px,color:#333;\n classDef tools fill:#f9e2ff,stroke:#e3bcdc,stroke-width:2px,color:#333;\n classDef pythonbox fill:#e2f7ff,stroke:#bcd5e3,stroke-width:2px,color:#333;\n\n User[User] -->|Interacts| Shell[Shell Interface]\n User -->|Runs| CLI[CLI Commands]\n User -->|Programs| SDK[Agent SDK]\n Shell -->|Commands| Agent[CodeActAgent]\n CLI -->|Tasks| Agent\n SDK -->|Controls| Agent\n Agent -->|Reasons| Reasoner[Reasoner]\n Agent -->|Executes| Executor[Executor]\n Reasoner -->|Generates Actions| Agent\n Executor -->|Uses| Tools[Tools]\n Tools -->|Returns Results| Executor\n Executor -->|Executes Code| PythonBox[\"Python Toolbox (PythonBox)\"]\n PythonBox -->|Returns Results| Executor\n Executor -->|Updates Context| Agent\n Agent -->|Responds| Shell\n Agent -->|Outputs| CLI\n Agent -->|Returns| SDK\n\n class User user;\n class Shell shell;\n class CLI cli;\n class SDK sdk;\n class Agent agent;\n class Reasoner reasoner;\n class Executor executor;\n class Tools tools;\n class PythonBox pythonbox;\n```\n\n- **Agent**: Orchestrates the ReAct loop, managing state and history.\n- **Reasoner**: Generates code or plans using LLMs (e.g., Gemini, DeepSeek).\n- **Executor**: Executes actions securely with PythonBox.\n- **Tools**: Modular functions for specialized tasks.\n- **PythonBox**: Provides a sandboxed environment for safe code execution.\n\n---\n\n## How to Use CodeAct\n\n### Installation\n\n#### Prerequisites\n- **Python**: 3.12 or higher\n- **Poetry**: Install via `pip install poetry`\n- **API Keys**: Required for LLMs (e.g., `GEMINI_API_KEY` for Gemini models)\n\n#### Installation Steps\n1. **Clone the Repository**:\n ```bash\n git clone https://github.com/quantalogic/quantalogic-codeact.git\n cd quantalogic-codeact\n ```\n2. **Install Dependencies**:\n ```bash\n poetry install\n ```\n Alternatively, install via pip:\n ```bash\n pip install quantalogic-codeact\n ```\n3. **Set Environment Variables**:\n ```bash\n export GEMINI_API_KEY=\"your-api-key\"\n ```\n4. **Verify Installation**:\n ```bash\n poetry run quantalogic_codeact --help\n ```\n\n### Quick Start\n\nCodeAct offers two primary interaction modes: an **interactive shell** for real-time engagement and a **CLI** for direct task execution.\n\n#### Interactive Shell\nStart the shell:\n```bash\npoetry run quantalogic_codeact shell\n```\nInteract using commands like `/solve` for tasks or `/chat` for conversations. Example:\n```\n[cfg:config.yaml] [Agent] [codeact]> /solve \"Calculate 2 + 2\"\n[Step 1 Result]\n- Status: Success\n- Value: 4\n- Execution Time: 0.12 seconds\n- Completed: True\n[Final Answer]\n4\n```\n\n#### Command-Line Interface (CLI)\nRun tasks directly:\n```bash\npoetry run quantalogic_codeact task \"Calculate 3 * 4\" --streaming\n```\nList available resources:\n```bash\npoetry run quantalogic_codeact list-toolboxes\npoetry run quantalogic_codeact list-models\n```\n\n### Using the Agent SDK\n\nThe Agent SDK enables programmatic control over agents, ideal for developers building custom applications. Below is an example integrating a custom tool and monitoring task progress.\n\n```python\nfrom quantalogic_codeact.codeact.agent import Agent\nfrom quantalogic_codeact.codeact.agent_config import AgentConfig\nfrom quantalogic_toolbox import create_tool, Tool\n\n# Define a custom tool\n@create_tool\nasync def factorial(n: int) -> int:\n \"\"\"Calculate the factorial of a number.\"\"\"\n if n < 0:\n raise ValueError(\"Factorial is not defined for negative numbers\")\n result = 1\n for i in range(1, n + 1):\n result *= i\n return result\n\n# Configure agent\nconfig = AgentConfig(\n model=\"deepseek/deepseek-chat\",\n max_iterations=5,\n enabled_toolboxes=[\"math_tools\"],\n tools=[factorial],\n personality={\"traits\": [\"logical\", \"precise\"]}\n)\nagent = Agent(config=config)\n\n# Monitor progress\ndef monitor_event(event):\n if event.event_type == \"StepStarted\":\n print(f\"Step {event.step_number} started\")\n elif event.event_type == \"ActionExecuted\":\n print(f\"Step {event.step_number} result: {event.result.to_summary()}\")\n elif event.event_type == \"TaskCompleted\":\n print(f\"Task completed with answer: {event.final_answer}\")\n\nagent.add_observer(monitor_event, [\"StepStarted\", \"ActionExecuted\", \"TaskCompleted\"])\n\n# Solve a task\nresult = agent.sync_solve(\"Calculate the factorial of 5\")\nfinal_answer = result[-1].get(\"result\", \"No result\")\nprint(f\"Final Answer: {final_answer}\")\n\n# Chat asynchronously\nasync def run_chat():\n response = await agent.chat(\"Explain factorials\")\n print(f\"Explanation: {response}\")\n\nimport asyncio\nasyncio.run(run_chat())\n```\n\n**Example Output**:\n```\nStep 1 started\nStep 1 result: - Status: Success\n- Task Status: completed\n- Result: 120\n- Execution Time: 0.15 seconds\nTask completed with answer: 120\nFinal Answer: 120\nExplanation: A factorial of a non-negative integer n, denoted n!, is the product of all positive integers less than or equal to n. For example, 5! = 5 * 4 * 3 * 2 * 1 = 120.\n```\n\n**ReAct Loop Visualization**:\n```mermaid\nsequenceDiagram\n participant U as User\n participant A as Agent\n participant R as Reasoner\n participant E as Executor\n participant T as Tools\n U->>A: Solve \"Factorial of 5\"\n A->>R: Generate plan\n R-->>A: Plan: Use factorial tool\n A->>E: Execute factorial(5)\n E->>T: Call factorial tool\n T-->>E: Result: 120\n E-->>A: Result XML: 120\n A-->>U: Final Answer: 120\n```\n\n### Commands\n\n#### Shell Commands\nBelow is a comprehensive list of shell commands:\n\n| Command | Description | Example Usage |\n|-----------------------------|-------------------------------------------------------|-------------------------------------------|\n| `/help [command]` | Show help for commands or a specific command | `/help solve` |\n| `/chat <message>` | Send a chat message to the agent | `/chat How are you?` |\n| `/solve <task>` | Solve a task | `/solve Calculate 2 + 2` |\n| `/mode [chat|codeact]` | Switch between chat and task-solving modes | `/mode codeact` |\n| `/stream [on|off]` | Toggle streaming output | `/stream on` |\n| `/exit` | Exit the shell | `/exit` |\n| `/history [n]` | Show last `n` messages (default: all) | `/history 5` |\n| `/clear` | Clear conversation history | `/clear` |\n| `/agent <name>` | Switch or show agent details | `/agent MathBot` |\n| `/set <field> <value>` | Set a config field and create new agent | `/set model deepseek/deepseek-chat` |\n| `/set temperature <value>` | Set or show LLM temperature (0 to 1) | `/set temperature 0.7` |\n| `/config show` | Display current configuration | `/config show` |\n| `/config save <file>` | Save config to a file | `/config save myconfig.yaml` |\n| `/config load <file>` | Load config from a file | `/config load myconfig.yaml` |\n| `/toolbox install <name>` | Install a toolbox | `/toolbox install math_tools` |\n| `/toolbox uninstall <name>` | Uninstall a toolbox | `/toolbox uninstall math_tools` |\n| `/toolbox enable <name>` | Enable a toolbox | `/toolbox enable math_tools` |\n| `/toolbox disable <name>` | Disable a toolbox | `/toolbox disable math_tools` |\n| `/toolbox installed` | Show installed toolboxes | `/toolbox installed` |\n| `/toolbox tools <name>` | List tools in a toolbox | `/toolbox tools math_tools` |\n| `/toolbox doc <name> <tool>` | Show tool documentation | `/toolbox doc math_tools integrate` |\n| `/listmodels` | List available models | `/listmodels` |\n| `/version` | Show package version | `/version` |\n| `/tutorial` | Display a tutorial for new users | `/tutorial` |\n| `/inputmode [single|multi]` | Toggle single-line or multiline input | `/inputmode multi` |\n| `/contrast [on|off]` | Toggle high-contrast mode for accessibility | `/contrast on` |\n| `/setmodel <model>` | Set model and switch to a new agent | `/setmodel deepseek/deepseek-chat` |\n| `/loglevel [level]` | Set log level (DEBUG|INFO|WARNING|ERROR|CRITICAL) | `/loglevel DEBUG` |\n| `/save <filename>` | Save conversation history to a file | `/save history.json` |\n| `/load <filename>` | Load conversation history from a file | `/load history.json` |\n| `/compose` | Compose input in an external editor | `/compose` |\n| `/edit [INDEX_OR_ID]` | Edit a previous user message | `/edit 3` |\n\n#### CLI Commands\n```bash\nUsage: quantalogic_codeact [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --config, -c PATH Path to the configuration file to use\n --loglevel, -l TEXT Override log level: DEBUG|INFO|WARNING|ERROR|CRITICAL\n --install-completion Install shell completion\n --show-completion Show shell completion script\n --help Show this message and exit\n\nCommands:\n shell Start the interactive shell\n task Run a task with event monitoring\n create-toolbox Create a new toolbox project\n config-load Load a configuration file\n list-models List available LLM models\n list-toolboxes List installed toolboxes\n list-reasoners List available reasoners\n list-executors List available executors\n tool-info Display tool information\n install-toolbox Install a toolbox\n uninstall-toolbox Uninstall a toolbox\n config Manage configuration (subcommands: show, reset)\n toolbox Manage toolboxes (subcommands: install, uninstall, tools, doc)\n```\n\n**Tip**: Use `--config` to specify a custom configuration file:\n```bash\nquantalogic_codeact task \"Solve 2 + 2\" -c ./myconfig.yaml\n```\n\n### Examples\n\n#### Shell\n```plaintext\n[cfg:config.yaml] [Agent] [codeact]> /chat Tell me a joke\nWhy did the computer go to art school? Because it wanted to learn how to draw a better \"byte\"!\n```\n\n#### CLI\n```bash\npoetry run quantalogic_codeact task \"Calculate the square root of 16\" --model gemini/gemini-2.0-flash\n```\n**Output**:\n```\n[Final Answer]\n4\n```\n\n#### SDK\n```python\nfrom quantalogic_codeact.codeact.agent import Agent\nagent = Agent()\nresult = agent.sync_solve(\"What is 3 * 5?\")\nprint(result[-1][\"result\"]) # Output: 15\n```\n\n### Configuration\n\nCodeAct uses a YAML configuration file, typically at `~/.quantalogic/config.yaml`. Example:\n```yaml\nmodel: \"gemini/gemini-2.0-flash\"\nmax_iterations: 5\nmax_history_tokens: 2000\nenabled_toolboxes:\n - math_tools\nreasoner:\n name: \"default\"\n config:\n temperature: 0.7\nexecutor:\n name: \"default\"\npersonality:\n traits:\n - witty\n - helpful\ntools_config:\n - name: math_tools\n enabled: true\n config:\n precision: \"high\"\n```\n\nManage configurations in the shell with `/config save` or `/config load`, or edit the file directly.\n\n### Toolbox System\n\nToolboxes extend CodeAct\u2019s functionality with modular, reusable tools. Built-in toolboxes include `math_tools` for calculations. Create custom toolboxes with:\n\n```bash\npoetry run quantalogic_codeact create-toolbox my_toolbox\n```\n\nThis generates a project structure with a `tools.py` file for defining tools. Example:\n```python\n@create_tool\nasync def echo_tool(message: str) -> str:\n \"\"\"Echoes the input message.\"\"\"\n return f\"Echo: {message}\"\n```\n\nFor detailed guidance, see [Toolbox Documentation](quantalogic_codeact/docs/01-quantalogic-toolbox.md), covering toolbox creation, tool registration, and management.\n\n### Memory Systems\n\nCodeAct employs two memory systems:\n- **WorkingMemory**: Tracks task-specific steps, thoughts, actions, and results.\n- **ConversationManager**: Stores user-agent interaction history for context-aware dialogues.\n\nThese systems enable multi-step reasoning and persistent conversations. See [Memory Systems Documentation](quantalogic_codeact/docs/02-quantalogic-codeagent-memory.md) for implementation details and examples.\n\n### Troubleshooting\n\n- **API Key Issues**: Verify `GEMINI_API_KEY` or other LLM keys are set.\n- **Dependency Errors**: Run `poetry install` to ensure all packages are installed.\n- **Timeout Errors**: Increase `--timeout` in CLI or `timeout` in SDK config.\n- **Tool Failures**: Use `/toolbox doc <toolbox> <tool>` to check tool arguments.\n- **Logging**: Enable debug mode with `/loglevel DEBUG` for detailed logs.\n\n---\n\n## Contributing\n\nContributions are welcome! Please follow [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines on code style, testing, and workflows.\n\n## References\n\n- Yao, S., et al. (2022). \"ReAct: Synergizing Reasoning and Acting in Language Models.\" [arXiv:2210.03629](https://arxiv.org/abs/2210.03629).\n- Yang, J., et al. (2024). \"Executable Code Actions Elicit Better LLM Agents.\" [arXiv:2402.01030](https://arxiv.org/abs/2402.01030).\n- Quantalogic PythonBox: [github.com/quantalogic/quantalogic-pythonbox](https://github.com/quantalogic/quantalogic-pythonbox).\n\n## License\n\nQuantalogic CodeAct is licensed under the **Apache License, Version 2.0**. See [LICENSE](../../LICENSE) for details.",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "CodeAct Agent.",
"version": "0.100.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7f0285094544c764c686eee42eda5bcda96e316f6aee7fc74b5a33cf6a6d541a",
"md5": "31fb4e6f625f0eacbd556b7adbfe76a0",
"sha256": "6711df7aa3a61f9aad019be3340edf4d6a237971742f0d7e2034e1a84c14f63b"
},
"downloads": -1,
"filename": "quantalogic_codeact-0.100.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "31fb4e6f625f0eacbd556b7adbfe76a0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 124852,
"upload_time": "2025-04-25T23:07:15",
"upload_time_iso_8601": "2025-04-25T23:07:15.593898Z",
"url": "https://files.pythonhosted.org/packages/7f/02/85094544c764c686eee42eda5bcda96e316f6aee7fc74b5a33cf6a6d541a/quantalogic_codeact-0.100.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6bcbd6aa6f7dd8e45180a5f68e46290288ea07f67c0796925f4343584348df85",
"md5": "4bba50e4696e7d41e72c36e16a056658",
"sha256": "7d56e147233af44ffa2ab25054bc0425b6573d89beea3d71da0a243a7802e17e"
},
"downloads": -1,
"filename": "quantalogic_codeact-0.100.0.tar.gz",
"has_sig": false,
"md5_digest": "4bba50e4696e7d41e72c36e16a056658",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 86945,
"upload_time": "2025-04-25T23:07:17",
"upload_time_iso_8601": "2025-04-25T23:07:17.132162Z",
"url": "https://files.pythonhosted.org/packages/6b/cb/d6aa6f7dd8e45180a5f68e46290288ea07f67c0796925f4343584348df85/quantalogic_codeact-0.100.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-04-25 23:07:17",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "quantalogic-codeact"
}
JSON