🚀 Chat with Tools Framework

• 🧠 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

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

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

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

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

# 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

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

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

# 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

# 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

# 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

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

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

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

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

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

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!

# 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)

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

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

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 .

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

# 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"

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

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

# Install development dependencies
make dev

# Run all checks before committing
make check

# Create a new tool from template
make new-tool

MIT License with Commercial Attribution

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

See LICENSE for details.

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

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

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

python main.py