quantalogic 0.93

QuantaLogic ReAct Agents

QuantaLogic: Unleash AI for Coding, Automation, and Conversations

QuantaLogic is your all-in-one AI framework for building smart agents that code, automate workflows, and chat like pros. Powered by large language models (LLMs) and a versatile toolset, it offers three killer modes: ReAct for tackling tough tasks, Flow for streamlined processes, and Chat for natural, tool-savvy conversations. Whether you’re a coder, a business innovator, or an AI enthusiast, QuantaLogic delivers fast, flexible, and fun solutions. Let’s blast off!

New: CodeAct

QuantaLogic CodeAct is a powerful, modular extension for creating AI agents that not only reason and act (ReAct) but also use executable code as their primary action language. Inspired by the latest research, CodeAct enables agents to solve complex, multi-step tasks by generating, running, and iterating on Python code, all while maintaining context and leveraging a robust tool system. This makes it ideal for advanced automation, mathematical problem-solving, and user-friendly conversational interfaces.

📖 Full Docs | ⚡ Quick Guide

---

Why QuantaLogic?

Why pick QuantaLogic? It turns the complexity of LLMs into practical magic, making AI work for you. From coding scripts to automating business tasks or chatting about the universe, QuantaLogic is your creative sidekick, saving time and unlocking possibilities.

• Versatile Power: Code, automate, or converse—handle any task.
• Your Rules: Customize agents and tools to match your needs.
• Scales Big: From CLI hacks to enterprise workflows.
• Free & Open: Apache 2.0 license—use it, tweak it, share it.

“AI should spark joy, not stress. QuantaLogic makes it happen!”

---

What is QuantaLogic?

What’s the vibe? QuantaLogic is a Python framework that harnesses LLMs (like GPT-4o, Claude, or DeepSeek) to create AI agents. These agents wield tools for coding, searching, file ops, and more, all accessible via a slick CLI or Python API. With ReAct, Flow, and Chat modes, it adapts to any challenge—dynamic tasks, structured pipelines, or friendly chats.

Core Features

• ReAct Mode: Solve problems with LLM reasoning + tool actions.
• Flow Mode: Craft structured workflows with nodes and transitions.
• Chat Mode: Converse naturally with tool-calling smarts.
• LLM Integration: Supports OpenAI, Anthropic, DeepSeek via LiteLLM.
• Toolset: Code execution, web search, file management, and custom tools.
• Smart Memory: Keeps context lean for long tasks or chats.
• Real-Time Insights: Track progress with events and logs.
• Safe Execution: Docker-based tool isolation.

---

CodeAct vs ReAct: What's the Difference?

QuantaLogic supports both the classic ReAct paradigm and its advanced extension, CodeAct:

• ReAct (Reason + Act):

  • Based on the ReAct paper, this approach lets agents reason (think step-by-step) and act (use tools or code) in a loop. It's great for tasks where language models need to plan, use tools, and adapt to feedback.

• CodeAct:

  • Builds on ReAct by making executable Python code the main language for agent actions. Instead of just calling tools or outputting text, the agent writes and runs code, observes the results (including errors), and iterates until the task is solved.
  • This approach is inspired by recent research (Yang et al., 2024) showing that executable code actions enable more capable and reliable LLM agents.
  • CodeAct is ideal for complex, multi-step tasks, advanced automation, and scenarios where precise, verifiable actions are needed.

Summary:

• Use ReAct for flexible reasoning with tool use.
• Use CodeAct for tasks where generating and executing code is the best way to solve a problem or automate a workflow.

Here’s how it flows:

graph TD
    A[User] -->|Input| B[QuantaLogic]
    B --> C1[Pure ReAct]
    B --> C2[CodeAct]
    B --> D[Flow: Automate]
    B --> E[Chat: Converse]
    C1 --> F1[LLM + Tools]
    C2 --> F2[LLM + Code Actions]
    D --> G[Nodes + Engine]
    E --> H[Persona + Tools]
    F1 --> I[Output]
    F2 --> I
    G --> I
    H --> I
    I --> A
    style A fill:#ffe5b4,stroke:#555
    style B fill:#cfe0e8,stroke:#555
    style C1 fill:#e6e6fa,stroke:#555
    style C2 fill:#ffd1dc,stroke:#555
    style D fill:#c8e6c9,stroke:#555
    style E fill:#fff9c4,stroke:#555
    style F1 fill:#f0f0f0,stroke:#555
    style F2 fill:#f0f0f0,stroke:#555
    style G fill:#d0f0c0,stroke:#555
    style H fill:#ffefdb,stroke:#555
    style I fill:#cfe0e8,stroke:#555

For detailed CodeAct documentation, see CodeAct Module.

---

How to Get Started

How do you dive in? Install it, set it up, and start creating. We’ll guide you through setup, examples, and pro tips to master QuantaLogic in minutes.

Installation & Setup

Prerequisites

• Python >= 3.10+ (required)
• Docker (optional; sandboxed execution)
• Poetry (optional; for source builds)

Installation

Install the core CLI and (optionally) CodeAct extension:

pip install quantalogic
pip install quantalogic-codeact

Or with pipx:

pipx install quantalogic
pipx install quantalogic-codeact

Developer Build (optional)

git clone https://github.com/quantalogic/quantalogic.git
cd quantalogic
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\\Scripts\\activate
poetry install

Verify Installation

quantalogic --help
quantalogic_codeact --help

Configure API Keys

cat <<EOF > .env
OPENAI_API_KEY=sk-your-key
DEEPSEEK_API_KEY=ds-your-key
EOF

For advanced settings, see docs/config.md

---

Quick Start Examples

Let’s see QuantaLogic shine with these quick demos.

CLI: Solve a Task

quantalogic task "Write a Python script to reverse a string"

Output: A clean, working string-reversal script!

CLI: Chat It Up

quantalogic chat --persona "You’re a cosmic guide" "What’s the tallest mountain?"

Output: A lively response, possibly with search results!

CLI: CodeAct Shell

quantalogic_codeact shell

CLI: CodeAct Task

quantalogic_codeact task "Solve 2 + 2" --model deepseek/deepseek-chat --timeout 60 --streaming

Python: ReAct Agent

from quantalogic import Agent

agent = Agent(model_name="deepseek/deepseek-chat")
result = agent.solve_task("Write a Python function to reverse a string")
print(result)
# Output: "def reverse_string(s): return s[::-1]"

Python: Chat Mode

from quantalogic import Agent, DuckDuckGoSearchTool

agent = Agent(
    model_name="gpt-4o-mini",
    chat_system_prompt="You’re a curious explorer",
    tools=[DuckDuckGoSearchTool()]
)
response = agent.chat("What’s new in quantum computing?")
print(response)
# Output: "I checked the latest news! Here’s a breakthrough in quantum computing: [details]."

---

The Three Modes: Your Superpowers

1. ReAct Framework: Dynamic Task-Solving

Why: Tackle open-ended tasks like coding or research with creative flair.
What: Combines LLM reasoning with tools to iterate toward solutions.
How: The agent thinks, acts, and loops until the task is complete.

Example: Debug some code.

quantalogic task "Debug this Python code: def add(a, b): return a - b"

Flow:

sequenceDiagram
    User->>Agent: "Debug code"
    Agent->>LLM: "Analyze error"
    LLM-->>Agent: "Subtraction should be addition"
    Agent->>PythonTool: "Fix code"
    PythonTool-->>Agent: "def add(a, b): return a + b"
    Agent-->>User: "Fixed code!"

Memorization Trick: ReAct = Reason + Act, like a detective solving a mystery step-by-step.

2. Flow Module: Structured Automation

Why: Perfect for repeatable processes like data pipelines or content creation.
What: A system of nodes (tasks) connected by transitions, run by an engine.
How: Define nodes, link them, and let the workflow hum.

Example: Process text.

from quantalogic.flow import Workflow, Nodes

@Nodes.define(output="processed")
def uppercase(text: str) -> str:
    return text.upper()

workflow = Workflow("uppercase").build()
result = await workflow.run({"text": "hello world"})
print(result["processed"])  # "HELLO WORLD"

Diagram:

graph LR
    A[Start] --> B[Uppercase Node]
    B --> C[End]
    A -->|Observer| D[Log: NODE_START]
    B -->|Observer| E[Log: NODE_END]
    style A fill:#dfd,stroke:#333
    style C fill:#dfd,stroke:#333

Memorization Trick: Flow = a recipe—nodes are ingredients, transitions are steps, and the engine is the chef.

Learn More: Explore the Flow YAML DSL Specification for advanced workflows.

3. Chat Mode: Natural Conversations

Why: Ideal for interactive Q&A or quick info with a touch of tool power.
What: A conversational AI that calls tools when needed, keeping chats smooth.
How: Engages naturally, using tools via ReAct’s XML system.

Example: Check the weather.

from quantalogic import Agent

agent = Agent(model_name="gpt-4o", chat_system_prompt="You’re a travel guide")
response = agent.chat("What’s the weather in Paris?")
print(response)
# Output: "I’ll look it up! Paris is sunny, 20°C today."

Memorization Trick: Chat = your AI bestie—talks, listens, and grabs tools like a search engine when curious.

---

Which Mode to Pick?

Mode	Best For	Style	Tools
ReAct	Coding, research, Q&A	Iterative, adaptive	Dynamic, on-demand
Flow	Pipelines, automation	Structured, orderly	Node-specific
Chat	Conversations, quick queries	Free-flowing	Contextual

Pro Tip: Combine modes! Use Chat for user input, Flow for backend automation, and ReAct for complex tasks.

---

CLI Mastery

The QuantaLogic CLI is your mission control. Here’s the scoop:

quantalogic [COMMAND] [OPTIONS]

Commands

• task: Run a task.

  quantalogic task "Calculate 5 + 3" --model-name gpt-4o-mini
  

• chat: Start a conversation.

  quantalogic chat --persona "AI expert" "What’s the latest in machine learning?"
  

• list-models: List LLMs.

  quantalogic list-models --search claude
  

Key Options

• --model-name: Select your LLM (e.g., anthropic/claude-3.5-sonnet).
• --mode: Choose ReAct, Flow, or Chat.
• --tool-mode: Prioritize tools in Chat (e.g., code).
• --verbose: See detailed logs.

Insider Secret: Add --no-stream for cleaner output on slow terminals!

---

Advanced Tricks

Build Custom Tools

Create your own tools for unique tasks:

from quantalogic.tools import Tool

class TimeTool(Tool):
    name = "time_tool"
    def execute(self) -> str:
        from datetime import datetime
        return f"Current time: {datetime.now()}"

agent = Agent(model_name="gpt-4o")
agent.add_tool(TimeTool())

Go Async

Boost performance with async:

import asyncio
from quantalogic import Agent

async def main():
    agent = Agent(model_name="gpt-4o")
    result = await agent.async_chat("Tell me a joke", streaming=True)
    print(result)

asyncio.run(main())

Monitor Events

Track every step:

from quantalogic import Agent, console_print_events

agent = Agent(model_name="gpt-4o")
agent.event_emitter.on(["task_start", "tool_execution_start"], console_print_events)
result = agent.solve_task("Write a poem")

---

Memorization Hacks

• Modes as Jobs: ReAct = Freelancer (flexible tasks), Flow = Engineer (structured builds), Chat = Barista (serves up chats).
• Tools as Toys: PythonTool = LEGO for coding, SearchTool = binoculars for info.
• Workflows as Maps: Nodes = destinations, transitions = roads, engine = GPS.

---

Simplified Concepts

Tools 101: Picture QuantaLogic as a handyman. You ask for a fix (task). It grabs tools—a hammer (WriteFileTool) or screwdriver (SearchTool)—to get the job done right.

Memory Magic: Imagine a sticky note board. As tasks or chats grow, QuantaLogic condenses old notes to keep space for new ones—efficient and clutter-free.

Contributing

Why: Make AI better for everyone!
What: Add features, squash bugs, or suggest ideas.
How: Fork, branch, code, and PR. Check CONTRIBUTING.md.

---

License

QuantaLogic is Apache 2.0—free to use, modify, and distribute. Built with ❤️ by Raphaël MANSUY at QuantaLogic.

---

API Keys & Models

Power up with LLM API keys in a .env file:

OPENAI_API_KEY=sk-your-key
ANTHROPIC_API_KEY=your-key
DEEPSEEK_API_KEY=ds-your-key

Top Models:

• openai/gpt-4o-mini: Speedy and budget-friendly.
• anthropic/claude-3.5-sonnet: Razor-sharp reasoning.
• deepseek/deepseek-reasoner: Deep problem-solving.

Insider Secret: Set LM_STUDIO_API_BASE for local LLMs—great for offline work!

---

Let’s Build the Future

QuantaLogic is your launchpad for AI awesomeness. Install it, try the examples, and create something epic—code, workflows, or chats. Star the repo, join the community, and let’s make AI unstoppable!