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

Demo GIF

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.

🏗️ Component Architecture

QuantaLogic is built with a modular component architecture for maximum flexibility and extensibility:

graph TB
    subgraph "QuantaLogic Ecosystem"
        Main[quantalogic]
        React[quantalogic_react]
        CodeAct[quantalogic_codeact] 
        Flow[quantalogic_flow]
        Toolbox[quantalogic_toolbox]
    end
    
    User[Users] --> Main
    Main --> React
    Main --> CodeAct
    Main --> Flow
    Main --> Toolbox
    
    React --> Tools[40+ Built-in Tools]
    CodeAct --> Python[Python Code Execution]
    Flow --> YAML[YAML Workflows]
    Toolbox --> Plugins[Plugin System]
    
    style Main fill:#E8F4FD,stroke:#2E86AB,stroke-width:3px,color:#1B4F72
    style React fill:#FFF2CC,stroke:#D6B656,stroke-width:2px,color:#7D6608
    style CodeAct fill:#F8D7DA,stroke:#D73A49,stroke-width:2px,color:#721C24
    style Flow fill:#E8F5E8,stroke:#28A745,stroke-width:2px,color:#155724
    style Toolbox fill:#F3E5F5,stroke:#8E24AA,stroke-width:2px,color:#4A148C
    style User fill:#E0F2F1,stroke:#00695C,stroke-width:2px,color:#004D40

🧩 Component Overview

| Component | Purpose | When to Use | Documentation | |-----------|---------|-------------|---------------| | QuantaLogic React | Core ReAct agent with 40+ tools | General AI tasks, automation, tool-based workflows | 📖 Detailed Guide | | QuantaLogic CodeAct | Code-first agent implementation | Programming, data analysis, mathematical problems | 📖 Detailed Guide | | QuantaLogic Flow | YAML-based workflow engine | Structured processes, data pipelines, automation | 📖 Detailed Guide | | QuantaLogic Toolbox | External tool integrations | Custom tools, enterprise plugins, extensions | 📖 Detailed Guide |

🔧 How It Works

When you install quantalogic, you get:

Unified API: from quantalogic import Agent works seamlessly
Component Integration: Automatic access to all components
Backward Compatibility: All existing code continues to work
Modular Design: Use only what you need, extend with custom components

The main package acts as a intelligent wrapper that delegates to the appropriate component based on your needs.

� Behind the Scenes: The quantalogic package is a wrapper that re-exports functionality from quantalogic_react (the core implementation). When you import Agent, you're getting the proven ReAct agent with access to 40+ tools. Additional components like CodeAct and Flow extend this foundation with specialized capabilities.

�📋 Architecture Details: See docs/ARCHITECTURE.md for complete technical specifications and component interaction patterns.

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 framework and (optionally) specific components:

Core Installation (includes React agent):

pip install quantalogic

With CodeAct Extension:

pip install quantalogic quantalogic-codeact

All Components (for comprehensive functionality):

pip install quantalogic quantalogic-codeact quantalogic-flow quantalogic-toolbox

Using pipx (recommended for CLI usage):

pipx install quantalogic
pipx inject quantalogic quantalogic-codeact  # Add CodeAct to same environment

💡 What gets installed: The main quantalogic package provides the unified API and includes the React component. Additional components add specialized capabilities while maintaining the same simple import: from quantalogic import Agent.

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_cod

Quantalogic

Install / Use

README