🚀 Chat with Tools Framework

A powerful multi-agent AI framework with tool integration
Inspired by Grok's deep thinking mode

Features • Quick Start • Usage • Architecture • Tools • Contributing

---

🌟 Features

Core Capabilities

• 🧠 Multi-Agent Intelligence: Deploy multiple specialized agents working in parallel
• 🛠️ Extensible Tool System: Auto-discover and hot-swap tools via plugin architecture
• ⚡ Real-Time Orchestration: Live progress tracking during multi-agent execution
• 🎯 Dynamic Analysis: AI-generated research questions for comprehensive coverage
• 🔄 Intelligent Synthesis: Combine multiple perspectives into unified insights

Two Powerful Modes

💬 Single Agent Mode

Perfect for straightforward tasks with full tool access

• Direct interaction with one intelligent agent
• Access to all available tools
• Ideal for quick queries and simple automation

🧠 Council Mode (Heavy)

Deep multi-perspective analysis inspired by Grok

• 4+ agents working in parallel
• Each agent tackles different aspects
• Comprehensive synthesis of all findings
• Perfect for complex research and analysis

🚀 Quick Start

Prerequisites

• Python 3.9 or higher
• uv package manager (recommended)
• OpenRouter API key (get one here)

Installation

# Clone the repository
git clone https://github.com/Suparious/chat-with-tools.git
cd chat-with-tools

Option 1: Install with uv (Recommended)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package in editable mode
uv pip install -e .

# Or just install dependencies
uv pip install -r requirements.txt

Option 2: Run directly with uv (No venv needed)

# Run without activating a virtual environment
uv run python main.py

# Or run specific commands
uv run --with . python -m chat_with_tools

Option 3: Install with pip

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
pip install -e .

# Or just install dependencies
pip install -r requirements.txt

Configuration

# Copy the example configuration
cp config/config.example.yaml config/config.yaml

# Edit config/config.yaml and add your OpenRouter API key
# Replace "YOUR API KEY HERE" with your actual key

First Run

# Launch the interactive menu
python main.py

# Or use the CLI directly
./cwt chat        # Single agent mode
./cwt council     # Multi-agent council mode
./cwt tools       # Test tools without API

💡 Usage

Interactive Menu

The easiest way to get started:

python main.py

This launches an interactive menu with all features:

• Single Agent Chat
• Council Mode (Heavy)
• Tool Testing
• Configuration Management
• Test Suite
• Documentation

Command Line Interface

Use the cwt CLI for direct access:

# Single agent chat
./cwt chat

# Multi-agent council with 6 agents
./cwt council --agents 6

# Test tools interactively
./cwt tools

# Check configuration
./cwt config --check

# Run tests
./cwt test --coverage

Make Commands

Convenient shortcuts for development:

make install      # Install dependencies
make run          # Launch interactive menu
make chat         # Start single agent
make council      # Start council mode
make test         # Run test suite
make format       # Format code
make build        # Build for PyPI

🏗️ Architecture

System Overview

graph TB
    subgraph User Interface
        UI[User Input]
        CLI[CLI/Menu]
    end
    
    subgraph Core Framework
        ORC[Orchestrator]
        SA[Single Agent]
        MA[Multi-Agent Controller]
    end
    
    subgraph Agent Pool
        A1[Agent 1: Research]
        A2[Agent 2: Analysis]
        A3[Agent 3: Verification]
        A4[Agent 4: Synthesis]
    end
    
    subgraph Tool System
        TS[Tool Scanner]
        T1[Web Search]
        T2[Calculator]
        T3[File I/O]
        T4[Memory]
        T5[Code Execution]
        T6[Sequential Thinking]
    end
    
    UI --> CLI
    CLI --> ORC
    ORC --> SA
    ORC --> MA
    MA --> A1 & A2 & A3 & A4
    SA --> TS
    A1 & A2 & A3 & A4 --> TS
    TS --> T1 & T2 & T3 & T4 & T5 & T6

Loading

How Council Mode Works

1. Query Analysis: AI analyzes your question
2. Question Generation: Creates specialized sub-questions
3. Parallel Execution: Multiple agents work simultaneously
4. Tool Utilization: Each agent uses relevant tools
5. Result Synthesis: AI combines all findings
6. Comprehensive Response: Delivers multi-faceted answer

🛠️ Available Tools

Core Tools

Tool	Purpose	Key Features
Web Search	Internet research	DuckDuckGo integration, result parsing
Calculator	Mathematical operations	Safe evaluation, complex expressions
File I/O	File manipulation	Read, write, create, delete files
Task Complete	Signal completion	Mark tasks done, provide summaries

Advanced Tools

Tool	Purpose	Key Features
Sequential Thinking	Step-by-step reasoning	Revisions, branching, confidence tracking
Memory	Persistent storage	Tags, search, categorization
Python Executor	Code execution	Sandboxed, resource limited, safe
Summarizer	Text analysis	Extractive summarization, key points

Adding Custom Tools

Create new tools easily:

# src/tools/my_custom_tool.py
from .base_tool import BaseTool

class MyCustomTool(BaseTool):
    @property
    def name(self) -> str:
        return "my_custom_tool"
    
    @property
    def description(self) -> str:
        return "What this tool does"
    
    @property
    def parameters(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "input": {"type": "string", "description": "Input data"}
            },
            "required": ["input"]
        }
    
    def execute(self, **kwargs) -> dict:
        input_data = kwargs.get("input")
        # Your tool logic here
        return {"status": "success", "result": f"Processed: {input_data}"}

The tool is automatically discovered and available!

⚙️ Configuration

Key Settings

# config/config.yaml

openrouter:
  api_key: "your-key-here"
  model: "openai/gpt-4-mini"  # or any OpenRouter model
  
orchestrator:
  parallel_agents: 4          # Number of agents in council mode
  task_timeout: 300          # Seconds per agent
  
agent:
  max_iterations: 10         # Max tool calls per query
  temperature: 0.7           # Response creativity (0-1)

Supported Models

Works with any OpenRouter-compatible model:

• OpenAI: gpt-4, gpt-3.5-turbo
• Anthropic: claude-3-opus, claude-3-sonnet
• Google: gemini-pro, gemini-flash
• Meta: llama-3.1-70b, llama-3.1-8b
• Open Source: mixtral, deepseek, qwen

📁 Project Structure

chat-with-tools/
├── src/                    # Core framework
│   ├── agent.py           # Single agent implementation
│   ├── orchestrator.py    # Multi-agent orchestration
│   └── tools/             # Tool implementations
├── demos/                  # Example applications
├── tests/                  # Test suite
├── config/                 # Configuration files
├── docs/                   # Documentation
├── main.py                # Interactive launcher
├── cwt                    # CLI interface
├── Makefile              # Development commands
├── pyproject.toml        # Modern Python packaging
└── requirements.txt      # Dependencies

🔧 Troubleshooting

Common Issues

uv build errors

If you encounter errors like package directory 'src/src' does not exist:

# Clear any existing build artifacts
rm -rf src/*.egg-info build/ dist/

# Reinstall in editable mode
uv pip install -e .

Module import errors

If you get import errors when running the code:

# Make sure you're in the project root
cd /path/to/chat-with-tools

# Install the package properly
uv pip install -e .

# Or run with uv directly
uv run python main.py

API Key not working

# Check your config file
cat config/config.yaml | grep api_key

# Make sure it's not the placeholder
# Should NOT be: api_key: "YOUR API KEY HERE"
# Should be: api_key: "sk-or-v1-your-actual-key"

🧪 Testing

Run the comprehensive test suite:

# Run all tests
make test

# With coverage report
make test-cov

# Quick tests only (no API calls)
make test-quick

# Watch mode (auto-run on changes)
make watch

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (make test)
5. Format code (make format)
6. Commit (git commit -m 'Add amazing feature')
7. Push (git push origin feature/amazing-feature)
8. Open a Pull Request

Development Setup

# Install development dependencies
make dev

# Run all checks before committing
make check

# Create a new tool from template
make new-tool

📝 License

MIT License with Commercial Attribution

For products with 100K+ users, please include attribution to the Chat with Tools framework.

See LICENSE for details.

🙏 Acknowledgments

• Built with OpenRouter for LLM access
• Inspired by Grok's deep thinking capabilities
• Uses uv for fast Python package management

📊 Performance

Metric	Single Agent	Council Mode (4 agents)
Response Time	~2-3s	~4-5s
Tool Calls/Query	1-3	4-12
Accuracy	Good	Excellent
Depth of Analysis	Moderate	Comprehensive

🚦 Status

• ✅ Core framework functional
• ✅ Tool system operational
• ✅ Multi-agent orchestration working
• 🚧 PyPI package (coming soon)
• 🚧 Web interface (planned)
• 🚧 API server mode (planned)

📬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

---

Ready to enhance your AI capabilities?

python main.py

⭐ Star us on GitHub if you find this useful!