# EQUITR Coder
**Advanced Multi-Agent AI Coding Assistant with Strategic Supervision**
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
[](https://textual.textualize.io/)
EQUITR Coder is a sophisticated AI coding assistant that combines **weak specialized workers** with a **strong reasoning supervisor** to create an intelligent, hierarchical system for software development. From simple single-agent tasks to complex multi-agent coordination, EQUITR Coder provides clean APIs, advanced TUI, and comprehensive tooling for modern AI-assisted development.
## 🌟 Key Features
### 🧠 **Hierarchical Intelligence System**
- **Strong Supervisor**: GPT-4/Claude for strategic guidance and architectural decisions
- **Weak Workers**: Specialized agents (GPT-3.5/smaller models) for efficient task execution
- **ask_supervisor Tool**: Workers can consult the supervisor for complex problems
### 🔧 **Multiple Interface Modes**
- **Programmatic**: Clean OOP interface following Python standards
- **Advanced TUI**: Rich terminal interface with live updates, parallel agent views, and real-time monitoring
- **CLI**: Command-line interface for single/multi-agent execution
- **API**: RESTful FastAPI server for integration
### 🔒 **Enterprise-Grade Security**
- Restricted file system access per worker
- Tool whitelisting and permission control
- Cost limits and iteration bounds
- Session isolation and audit trails
### 📊 **Comprehensive Monitoring**
- Real-time cost tracking across all agents
- Todo list progress monitoring
- Git integration with automatic commits
- Session management and history
## 🚀 Quick Start
### Installation
```bash
# Basic installation
pip install -e .
# With advanced TUI support
pip install -e .[all]
# Development installation
pip install -e .[dev]
```
### Environment Setup
```bash
# Required: Set your API key
export OPENAI_API_KEY="your-openai-key"
# OR
export ANTHROPIC_API_KEY="your-anthropic-key"
# Optional: Configure defaults
export EQUITR_MODE="single" # or "multi"
export EQUITR_MAX_COST="5.0"
export EQUITR_MODEL="gpt-4"
```
## 💻 Usage Modes
### 1. Programmatic Interface (Recommended)
The cleanest way to integrate EQUITR Coder into your applications:
```python
import asyncio
from equitrcoder import EquitrCoder, TaskConfiguration
async def main():
# Create coder instance
coder = EquitrCoder(mode="single", git_enabled=True)
# Configure task
config = TaskConfiguration(
description="Analyze and improve code",
max_cost=2.0,
max_iterations=15,
auto_commit=True
)
# Execute task
result = await coder.execute_task(
"Analyze the codebase and add comprehensive type hints",
config=config
)
# Check results
if result.success:
print(f"✅ Success! Cost: ${result.cost:.4f}")
if result.git_committed:
print(f"📝 Committed: {result.commit_hash}")
await coder.cleanup()
asyncio.run(main())
```
#### Multi-Agent Example
```python
from equitrcoder import create_multi_agent_coder, MultiAgentTaskConfiguration
async def multi_agent_example():
# Create multi-agent system
coder = create_multi_agent_coder(
max_workers=3,
supervisor_model="gpt-4",
worker_model="gpt-3.5-turbo"
)
# Configure complex task
config = MultiAgentTaskConfiguration(
description="Full-stack development",
max_workers=3,
max_cost=10.0,
auto_commit=True
)
# Execute complex task with multiple workers
result = await coder.execute_task(
"Build a complete user authentication system with database, API, and frontend",
config=config
)
print(f"Workers used: {result.iterations}")
print(f"Total cost: ${result.cost:.4f}")
await coder.cleanup()
```
### 2. Advanced TUI Mode
Rich terminal interface with real-time monitoring:
```bash
# Launch single-agent TUI
equitrcoder tui --mode single
# Launch multi-agent TUI
equitrcoder tui --mode multi
```
**TUI Features:**
- 📊 **Bottom Status Bar**: Shows mode, models, stage, agent count, and cost
- 📋 **Left Todo Sidebar**: Real-time todo progress with priority indicators
- 💬 **Center Chat Window**: Live agent outputs with syntax highlighting
- 🪟 **Parallel Agent Tabs**: Split windows for multiple agents
- ⌨️ **Keyboard Controls**: Enter to execute, Ctrl+C to quit
### 3. Command Line Interface
Direct task execution from command line:
```bash
# Single agent mode
equitrcoder single "Fix the authentication bug in user.py" \
--model gpt-4 \
--max-cost 2.0 \
--max-iterations 20
# Multi-agent mode
equitrcoder multi "Build a complete web application with authentication" \
--workers 3 \
--supervisor-model gpt-4 \
--worker-model gpt-3.5-turbo \
--max-cost 15.0
# Tool management
equitrcoder tools --list
equitrcoder tools --discover
```
### 4. API Server
RESTful API for integration:
```bash
# Start API server
equitrcoder api --host localhost --port 8000
# Execute tasks via HTTP
curl -X POST http://localhost:8000/execute_task \
-H "Content-Type: application/json" \
-d '{
"task_description": "Add unit tests to the project",
"mode": "single",
"max_cost": 2.0
}'
```
## 🧠 ask_supervisor Tool
The `ask_supervisor` tool is the key to EQUITR Coder's intelligence hierarchy. Worker agents can consult the strong supervisor model for:
- **Architectural Decisions**: "Should I use JWT or sessions for auth?"
- **Complex Debugging**: "How do I troubleshoot this intermittent database error?"
- **Code Review**: "Is this implementation following best practices?"
- **Strategic Planning**: "What's the best approach for this refactoring?"
### Example Worker Usage
```python
# Worker agent automatically has access to ask_supervisor in multi-agent mode
await worker.call_tool("ask_supervisor",
question="I need to implement caching. What approach should I take for a high-traffic web API?",
context_files=["src/api.py", "requirements.txt"],
include_repo_tree=True
)
```
The supervisor provides structured guidance:
- **Strategic Analysis**: Core challenges and trade-offs
- **Recommended Approach**: Step-by-step implementation plan
- **Architectural Considerations**: How it fits the broader codebase
- **Risk Assessment**: Potential issues and mitigation strategies
- **Next Steps**: Immediate actionable items
## 🔧 Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ EQUITR CODER SYSTEM │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ SUPERVISOR │◄──────────────►│ SUPERVISOR │ │
│ │ (Strong Model) │ ask_supervisor │ (Strong Model) │ │
│ │ GPT-4/Claude │ │ GPT-4/Claude │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ WORKER AGENT 1 │◄──messaging───►│ WORKER AGENT 2 │ │
│ │ (Weak Model) │ │ (Weak Model) │ │
│ │ GPT-3.5/Smaller │ │ GPT-3.5/Smaller │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ RESTRICTED FS │ │ RESTRICTED FS │ │
│ │ Tools/Scope │ │ Tools/Scope │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Core Components
#### Agents
- **BaseAgent**: Core functionality (messaging, tools, cost tracking, session management)
- **WorkerAgent**: Adds restricted file system access and tool whitelisting for security
#### Orchestrators
- **SingleAgentOrchestrator**: Simple wrapper for single-agent tasks with session management
- **MultiAgentOrchestrator**: Advanced coordination with parallel execution and supervisor oversight
#### Security Features
- **RestrictedFileSystem**: Path-based access control with traversal protection
- **Tool Whitelisting**: Fine-grained permission control per worker
- **Cost Limits**: Per-agent and global cost tracking and limits
- **Session Isolation**: Separate contexts for different workflows
## 🛠️ Tool System
EQUITR Coder has an extensible plugin architecture:
### Built-in Tools
```python
# File operations (with security restrictions for WorkerAgent)
await worker.call_tool("read_file", file_path="src/main.py")
await worker.call_tool("edit_file", file_path="src/main.py", content="new content")
# Git operations with auto-commit
await worker.call_tool("git_commit", message="Fix authentication bug")
# Shell commands
await worker.call_tool("run_cmd", cmd="pytest tests/")
# Supervisor consultation (multi-agent only)
await worker.call_tool("ask_supervisor",
question="Should I refactor this function?",
context_files=["src/auth.py"])
# Todo management
await worker.call_tool("create_todo", description="Add unit tests", priority="high")
```
### Custom Tools
```python
from equitrcoder.tools.base import Tool, ToolResult
from pydantic import BaseModel, Field
class MyCustomArgs(BaseModel):
input_text: str = Field(..., description="Text to process")
class MyCustomTool(Tool):
def get_name(self) -> str:
return "my_custom_tool"
def get_description(self) -> str:
return "Description of what this tool does"
def get_args_schema(self) -> type[BaseModel]:
return MyCustomArgs
async def run(self, **kwargs) -> ToolResult:
args = MyCustomArgs(**kwargs)
# Tool logic here
return ToolResult(success=True, data="Result")
# Register the tool
from equitrcoder.tools import registry
registry.register(MyCustomTool())
```
## 📚 Documentation
- **[Ask Supervisor Guide](equitrcoder/docs/ASK_SUPERVISOR_GUIDE.md)**: Complete guide to the supervisor consultation system
- **[Programmatic Usage](equitrcoder/docs/PROGRAMMATIC_USAGE_GUIDE.md)**: Comprehensive programmatic API documentation
- **[Configuration Guide](equitrcoder/docs/CONFIGURATION_GUIDE.md)**: System configuration options
- **[Development Setup](equitrcoder/docs/DEVELOPMENT_SETUP.md)**: Contributing and development guide
- **[Tool System](equitrcoder/docs/TOOL_LOGGING_AND_MULTI_MODEL_GUIDE.md)**: Tool development and logging
## 🎯 Examples
Run the comprehensive examples:
```bash
# Programmatic interface examples
cd equitrcoder/examples
python programmatic_example.py
# Multi-agent coordination
python multi_agent_coordination.py
# Custom tool development
python tool_logging_example.py
```
## 🔒 Security & Cost Management
### File System Security
```python
# Workers operate in restricted environments
worker = WorkerAgent(
worker_id="frontend_dev",
scope_paths=["src/frontend/", "public/"], # Only access these paths
allowed_tools=["read_file", "edit_file"], # Limited tool set
max_cost=2.0 # Cost boundary
)
```
### Cost Controls
```python
# Global cost limits
orchestrator = MultiAgentOrchestrator(
global_cost_limit=10.0, # Total spending cap
max_concurrent_workers=3 # Resource limits
)
# Per-task limits
config = TaskConfiguration(
max_cost=1.0, # Task-specific limit
max_iterations=20 # Iteration boundary
)
```
### Git Integration
```python
# Automatic commit management
coder = EquitrCoder(git_enabled=True)
config = TaskConfiguration(
auto_commit=True,
commit_message="AI-assisted feature implementation"
)
# Every successful task gets committed with metadata
result = await coder.execute_task("Add authentication", config)
if result.git_committed:
print(f"Committed as: {result.commit_hash}")
```
## 🚀 Advanced Patterns
### Retry Logic with Escalating Resources
```python
async def robust_execution(task_description, max_retries=3):
for attempt in range(max_retries):
config = TaskConfiguration(
max_cost=1.0 * (attempt + 1), # Increase cost limit
max_iterations=10 * (attempt + 1) # Increase iterations
)
result = await coder.execute_task(task_description, config)
if result.success:
return result
await asyncio.sleep(2 ** attempt) # Exponential backoff
return None # All attempts failed
```
### Session-Based Development
```python
# Continue previous work
config = TaskConfiguration(
session_id="auth_development",
description="Authentication system development"
)
# Each task builds on previous context
await coder.execute_task("Design user authentication schema", config)
await coder.execute_task("Implement login endpoint", config)
await coder.execute_task("Add password validation", config)
# Review session history
session = coder.get_session_history("auth_development")
print(f"Total cost: ${session.cost:.4f}")
```
### Multi-Worker Coordination
```python
# Specialized workers for different domains
frontend_worker = WorkerConfiguration(
worker_id="ui_specialist",
scope_paths=["src/frontend/", "assets/"],
allowed_tools=["read_file", "edit_file", "run_cmd"]
)
backend_worker = WorkerConfiguration(
worker_id="api_specialist",
scope_paths=["src/backend/", "database/"],
allowed_tools=["read_file", "edit_file", "run_cmd", "git_commit"]
)
# Parallel execution with automatic coordination
tasks = [
{"task_id": "ui", "worker_id": "ui_specialist", "task_description": "Build login UI"},
{"task_id": "api", "worker_id": "api_specialist", "task_description": "Build auth API"}
]
results = await coder.execute_parallel_tasks(tasks)
```
## 🤝 Contributing
1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Make** your changes with proper tests
4. **Commit** your changes (`git commit -m 'Add amazing feature'`)
5. **Push** to the branch (`git push origin feature/amazing-feature`)
6. **Open** a Pull Request
See [DEVELOPMENT_SETUP.md](equitrcoder/docs/DEVELOPMENT_SETUP.md) for detailed setup instructions.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **OpenAI** and **Anthropic** for providing the language models
- **Textual** for the advanced terminal UI framework
- **LiteLLM** for unified model interface
- **FastAPI** for the API server capabilities
---
**EQUITR Coder**: Where strategic intelligence meets tactical execution. 🧠⚡
Raw data
{
"_id": null,
"home_page": "https://github.com/equitr/equitrcoder",
"name": "equitrcoder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai coding assistant agent multi-agent llm automation",
"author": "EQUITR",
"author_email": "coder@equitr.com",
"download_url": "https://files.pythonhosted.org/packages/5c/0b/a03967e8a14f62f2707946bd168bb0564e56dcb2b84117a34acf7fd59610/equitrcoder-1.0.0.tar.gz",
"platform": null,
"description": "# EQUITR Coder\n\n**Advanced Multi-Agent AI Coding Assistant with Strategic Supervision**\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n[](https://textual.textualize.io/)\n\nEQUITR Coder is a sophisticated AI coding assistant that combines **weak specialized workers** with a **strong reasoning supervisor** to create an intelligent, hierarchical system for software development. From simple single-agent tasks to complex multi-agent coordination, EQUITR Coder provides clean APIs, advanced TUI, and comprehensive tooling for modern AI-assisted development.\n\n## \ud83c\udf1f Key Features\n\n### \ud83e\udde0 **Hierarchical Intelligence System**\n- **Strong Supervisor**: GPT-4/Claude for strategic guidance and architectural decisions\n- **Weak Workers**: Specialized agents (GPT-3.5/smaller models) for efficient task execution\n- **ask_supervisor Tool**: Workers can consult the supervisor for complex problems\n\n### \ud83d\udd27 **Multiple Interface Modes**\n- **Programmatic**: Clean OOP interface following Python standards\n- **Advanced TUI**: Rich terminal interface with live updates, parallel agent views, and real-time monitoring\n- **CLI**: Command-line interface for single/multi-agent execution\n- **API**: RESTful FastAPI server for integration\n\n### \ud83d\udd12 **Enterprise-Grade Security**\n- Restricted file system access per worker\n- Tool whitelisting and permission control\n- Cost limits and iteration bounds\n- Session isolation and audit trails\n\n### \ud83d\udcca **Comprehensive Monitoring**\n- Real-time cost tracking across all agents\n- Todo list progress monitoring\n- Git integration with automatic commits\n- Session management and history\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\n# Basic installation\npip install -e .\n\n# With advanced TUI support\npip install -e .[all]\n\n# Development installation\npip install -e .[dev]\n```\n\n### Environment Setup\n\n```bash\n# Required: Set your API key\nexport OPENAI_API_KEY=\"your-openai-key\"\n# OR\nexport ANTHROPIC_API_KEY=\"your-anthropic-key\"\n\n# Optional: Configure defaults\nexport EQUITR_MODE=\"single\" # or \"multi\"\nexport EQUITR_MAX_COST=\"5.0\"\nexport EQUITR_MODEL=\"gpt-4\"\n```\n\n## \ud83d\udcbb Usage Modes\n\n### 1. Programmatic Interface (Recommended)\n\nThe cleanest way to integrate EQUITR Coder into your applications:\n\n```python\nimport asyncio\nfrom equitrcoder import EquitrCoder, TaskConfiguration\n\nasync def main():\n # Create coder instance\n coder = EquitrCoder(mode=\"single\", git_enabled=True)\n \n # Configure task\n config = TaskConfiguration(\n description=\"Analyze and improve code\",\n max_cost=2.0,\n max_iterations=15,\n auto_commit=True\n )\n \n # Execute task\n result = await coder.execute_task(\n \"Analyze the codebase and add comprehensive type hints\",\n config=config\n )\n \n # Check results\n if result.success:\n print(f\"\u2705 Success! Cost: ${result.cost:.4f}\")\n if result.git_committed:\n print(f\"\ud83d\udcdd Committed: {result.commit_hash}\")\n \n await coder.cleanup()\n\nasyncio.run(main())\n```\n\n#### Multi-Agent Example\n\n```python\nfrom equitrcoder import create_multi_agent_coder, MultiAgentTaskConfiguration\n\nasync def multi_agent_example():\n # Create multi-agent system\n coder = create_multi_agent_coder(\n max_workers=3,\n supervisor_model=\"gpt-4\",\n worker_model=\"gpt-3.5-turbo\"\n )\n \n # Configure complex task\n config = MultiAgentTaskConfiguration(\n description=\"Full-stack development\",\n max_workers=3,\n max_cost=10.0,\n auto_commit=True\n )\n \n # Execute complex task with multiple workers\n result = await coder.execute_task(\n \"Build a complete user authentication system with database, API, and frontend\",\n config=config\n )\n \n print(f\"Workers used: {result.iterations}\")\n print(f\"Total cost: ${result.cost:.4f}\")\n \n await coder.cleanup()\n```\n\n### 2. Advanced TUI Mode\n\nRich terminal interface with real-time monitoring:\n\n```bash\n# Launch single-agent TUI\nequitrcoder tui --mode single\n\n# Launch multi-agent TUI \nequitrcoder tui --mode multi\n```\n\n**TUI Features:**\n- \ud83d\udcca **Bottom Status Bar**: Shows mode, models, stage, agent count, and cost\n- \ud83d\udccb **Left Todo Sidebar**: Real-time todo progress with priority indicators\n- \ud83d\udcac **Center Chat Window**: Live agent outputs with syntax highlighting\n- \ud83e\ude9f **Parallel Agent Tabs**: Split windows for multiple agents\n- \u2328\ufe0f **Keyboard Controls**: Enter to execute, Ctrl+C to quit\n\n### 3. Command Line Interface\n\nDirect task execution from command line:\n\n```bash\n# Single agent mode\nequitrcoder single \"Fix the authentication bug in user.py\" \\\n --model gpt-4 \\\n --max-cost 2.0 \\\n --max-iterations 20\n\n# Multi-agent mode \nequitrcoder multi \"Build a complete web application with authentication\" \\\n --workers 3 \\\n --supervisor-model gpt-4 \\\n --worker-model gpt-3.5-turbo \\\n --max-cost 15.0\n\n# Tool management\nequitrcoder tools --list\nequitrcoder tools --discover\n```\n\n### 4. API Server\n\nRESTful API for integration:\n\n```bash\n# Start API server\nequitrcoder api --host localhost --port 8000\n\n# Execute tasks via HTTP\ncurl -X POST http://localhost:8000/execute_task \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"task_description\": \"Add unit tests to the project\",\n \"mode\": \"single\",\n \"max_cost\": 2.0\n }'\n```\n\n## \ud83e\udde0 ask_supervisor Tool\n\nThe `ask_supervisor` tool is the key to EQUITR Coder's intelligence hierarchy. Worker agents can consult the strong supervisor model for:\n\n- **Architectural Decisions**: \"Should I use JWT or sessions for auth?\"\n- **Complex Debugging**: \"How do I troubleshoot this intermittent database error?\"\n- **Code Review**: \"Is this implementation following best practices?\"\n- **Strategic Planning**: \"What's the best approach for this refactoring?\"\n\n### Example Worker Usage\n\n```python\n# Worker agent automatically has access to ask_supervisor in multi-agent mode\nawait worker.call_tool(\"ask_supervisor\", \n question=\"I need to implement caching. What approach should I take for a high-traffic web API?\",\n context_files=[\"src/api.py\", \"requirements.txt\"],\n include_repo_tree=True\n)\n```\n\nThe supervisor provides structured guidance:\n- **Strategic Analysis**: Core challenges and trade-offs\n- **Recommended Approach**: Step-by-step implementation plan\n- **Architectural Considerations**: How it fits the broader codebase\n- **Risk Assessment**: Potential issues and mitigation strategies\n- **Next Steps**: Immediate actionable items\n\n## \ud83d\udd27 Architecture\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 EQUITR CODER SYSTEM \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 SUPERVISOR \u2502\u25c4\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25ba\u2502 SUPERVISOR \u2502 \u2502\n\u2502 \u2502 (Strong Model) \u2502 ask_supervisor \u2502 (Strong Model) \u2502 \u2502\n\u2502 \u2502 GPT-4/Claude \u2502 \u2502 GPT-4/Claude \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u2502 \u2502 \u2502\n\u2502 \u25bc \u25bc \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 WORKER AGENT 1 \u2502\u25c4\u2500\u2500messaging\u2500\u2500\u2500\u25ba\u2502 WORKER AGENT 2 \u2502 \u2502\n\u2502 \u2502 (Weak Model) \u2502 \u2502 (Weak Model) \u2502 \u2502\n\u2502 \u2502 GPT-3.5/Smaller \u2502 \u2502 GPT-3.5/Smaller \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u2502 \u2502 \u2502\n\u2502 \u25bc \u25bc \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 RESTRICTED FS \u2502 \u2502 RESTRICTED FS \u2502 \u2502\n\u2502 \u2502 Tools/Scope \u2502 \u2502 Tools/Scope \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n### Core Components\n\n#### Agents\n- **BaseAgent**: Core functionality (messaging, tools, cost tracking, session management) \n- **WorkerAgent**: Adds restricted file system access and tool whitelisting for security\n\n#### Orchestrators\n- **SingleAgentOrchestrator**: Simple wrapper for single-agent tasks with session management\n- **MultiAgentOrchestrator**: Advanced coordination with parallel execution and supervisor oversight\n\n#### Security Features\n- **RestrictedFileSystem**: Path-based access control with traversal protection\n- **Tool Whitelisting**: Fine-grained permission control per worker\n- **Cost Limits**: Per-agent and global cost tracking and limits\n- **Session Isolation**: Separate contexts for different workflows\n\n## \ud83d\udee0\ufe0f Tool System\n\nEQUITR Coder has an extensible plugin architecture:\n\n### Built-in Tools\n\n```python\n# File operations (with security restrictions for WorkerAgent)\nawait worker.call_tool(\"read_file\", file_path=\"src/main.py\")\nawait worker.call_tool(\"edit_file\", file_path=\"src/main.py\", content=\"new content\")\n\n# Git operations with auto-commit\nawait worker.call_tool(\"git_commit\", message=\"Fix authentication bug\")\n\n# Shell commands\nawait worker.call_tool(\"run_cmd\", cmd=\"pytest tests/\")\n\n# Supervisor consultation (multi-agent only)\nawait worker.call_tool(\"ask_supervisor\", \n question=\"Should I refactor this function?\",\n context_files=[\"src/auth.py\"])\n\n# Todo management\nawait worker.call_tool(\"create_todo\", description=\"Add unit tests\", priority=\"high\")\n```\n\n### Custom Tools\n\n```python\nfrom equitrcoder.tools.base import Tool, ToolResult\nfrom pydantic import BaseModel, Field\n\nclass MyCustomArgs(BaseModel):\n input_text: str = Field(..., description=\"Text to process\")\n\nclass MyCustomTool(Tool):\n def get_name(self) -> str:\n return \"my_custom_tool\"\n \n def get_description(self) -> str:\n return \"Description of what this tool does\"\n \n def get_args_schema(self) -> type[BaseModel]:\n return MyCustomArgs\n \n async def run(self, **kwargs) -> ToolResult:\n args = MyCustomArgs(**kwargs)\n # Tool logic here\n return ToolResult(success=True, data=\"Result\")\n\n# Register the tool\nfrom equitrcoder.tools import registry\nregistry.register(MyCustomTool())\n```\n\n## \ud83d\udcda Documentation\n\n- **[Ask Supervisor Guide](equitrcoder/docs/ASK_SUPERVISOR_GUIDE.md)**: Complete guide to the supervisor consultation system\n- **[Programmatic Usage](equitrcoder/docs/PROGRAMMATIC_USAGE_GUIDE.md)**: Comprehensive programmatic API documentation\n- **[Configuration Guide](equitrcoder/docs/CONFIGURATION_GUIDE.md)**: System configuration options\n- **[Development Setup](equitrcoder/docs/DEVELOPMENT_SETUP.md)**: Contributing and development guide\n- **[Tool System](equitrcoder/docs/TOOL_LOGGING_AND_MULTI_MODEL_GUIDE.md)**: Tool development and logging\n\n## \ud83c\udfaf Examples\n\nRun the comprehensive examples:\n\n```bash\n# Programmatic interface examples\ncd equitrcoder/examples\npython programmatic_example.py\n\n# Multi-agent coordination\npython multi_agent_coordination.py\n\n# Custom tool development\npython tool_logging_example.py\n```\n\n## \ud83d\udd12 Security & Cost Management\n\n### File System Security\n```python\n# Workers operate in restricted environments\nworker = WorkerAgent(\n worker_id=\"frontend_dev\",\n scope_paths=[\"src/frontend/\", \"public/\"], # Only access these paths\n allowed_tools=[\"read_file\", \"edit_file\"], # Limited tool set\n max_cost=2.0 # Cost boundary\n)\n```\n\n### Cost Controls\n```python\n# Global cost limits\norchestrator = MultiAgentOrchestrator(\n global_cost_limit=10.0, # Total spending cap\n max_concurrent_workers=3 # Resource limits\n)\n\n# Per-task limits\nconfig = TaskConfiguration(\n max_cost=1.0, # Task-specific limit\n max_iterations=20 # Iteration boundary\n)\n```\n\n### Git Integration\n```python\n# Automatic commit management\ncoder = EquitrCoder(git_enabled=True)\n\nconfig = TaskConfiguration(\n auto_commit=True,\n commit_message=\"AI-assisted feature implementation\"\n)\n\n# Every successful task gets committed with metadata\nresult = await coder.execute_task(\"Add authentication\", config)\nif result.git_committed:\n print(f\"Committed as: {result.commit_hash}\")\n```\n\n## \ud83d\ude80 Advanced Patterns\n\n### Retry Logic with Escalating Resources\n```python\nasync def robust_execution(task_description, max_retries=3):\n for attempt in range(max_retries):\n config = TaskConfiguration(\n max_cost=1.0 * (attempt + 1), # Increase cost limit\n max_iterations=10 * (attempt + 1) # Increase iterations\n )\n \n result = await coder.execute_task(task_description, config)\n if result.success:\n return result\n \n await asyncio.sleep(2 ** attempt) # Exponential backoff\n \n return None # All attempts failed\n```\n\n### Session-Based Development\n```python\n# Continue previous work\nconfig = TaskConfiguration(\n session_id=\"auth_development\",\n description=\"Authentication system development\"\n)\n\n# Each task builds on previous context\nawait coder.execute_task(\"Design user authentication schema\", config)\nawait coder.execute_task(\"Implement login endpoint\", config) \nawait coder.execute_task(\"Add password validation\", config)\n\n# Review session history\nsession = coder.get_session_history(\"auth_development\")\nprint(f\"Total cost: ${session.cost:.4f}\")\n```\n\n### Multi-Worker Coordination\n```python\n# Specialized workers for different domains\nfrontend_worker = WorkerConfiguration(\n worker_id=\"ui_specialist\",\n scope_paths=[\"src/frontend/\", \"assets/\"],\n allowed_tools=[\"read_file\", \"edit_file\", \"run_cmd\"]\n)\n\nbackend_worker = WorkerConfiguration(\n worker_id=\"api_specialist\", \n scope_paths=[\"src/backend/\", \"database/\"],\n allowed_tools=[\"read_file\", \"edit_file\", \"run_cmd\", \"git_commit\"]\n)\n\n# Parallel execution with automatic coordination\ntasks = [\n {\"task_id\": \"ui\", \"worker_id\": \"ui_specialist\", \"task_description\": \"Build login UI\"},\n {\"task_id\": \"api\", \"worker_id\": \"api_specialist\", \"task_description\": \"Build auth API\"}\n]\n\nresults = await coder.execute_parallel_tasks(tasks)\n```\n\n## \ud83e\udd1d Contributing\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Make** your changes with proper tests\n4. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n5. **Push** to the branch (`git push origin feature/amazing-feature`)\n6. **Open** a Pull Request\n\nSee [DEVELOPMENT_SETUP.md](equitrcoder/docs/DEVELOPMENT_SETUP.md) for detailed setup instructions.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- **OpenAI** and **Anthropic** for providing the language models\n- **Textual** for the advanced terminal UI framework\n- **LiteLLM** for unified model interface\n- **FastAPI** for the API server capabilities\n\n---\n\n**EQUITR Coder**: Where strategic intelligence meets tactical execution. \ud83e\udde0\u26a1 \n",
"bugtrack_url": null,
"license": null,
"summary": "Modular AI coding assistant supporting single and multi-agent workflows",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/equitr/equitrcoder/issues",
"Documentation": "https://equitrcoder.readthedocs.io/",
"Homepage": "https://github.com/equitr/equitrcoder",
"Source": "https://github.com/equitr/equitrcoder"
},
"split_keywords": [
"ai",
"coding",
"assistant",
"agent",
"multi-agent",
"llm",
"automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8d5b5ccb0116154fbbfbc6125aa569c6d7c9395d7483bc0549f854d98657d231",
"md5": "ebe1b453404d24a784a56ca55057010c",
"sha256": "795e22b3c9143aa07a32ebbe9e20ab8e544de7e2f2e4bcbb5328c46575997cf3"
},
"downloads": -1,
"filename": "equitrcoder-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ebe1b453404d24a784a56ca55057010c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 142526,
"upload_time": "2025-07-25T01:17:34",
"upload_time_iso_8601": "2025-07-25T01:17:34.211206Z",
"url": "https://files.pythonhosted.org/packages/8d/5b/5ccb0116154fbbfbc6125aa569c6d7c9395d7483bc0549f854d98657d231/equitrcoder-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5c0ba03967e8a14f62f2707946bd168bb0564e56dcb2b84117a34acf7fd59610",
"md5": "a66dd9575e20f961fedc82a59d1e6622",
"sha256": "df0b1f21571b6f87462d49e6f28821428294e3e05ac0cd531184db48dbfeae7c"
},
"downloads": -1,
"filename": "equitrcoder-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "a66dd9575e20f961fedc82a59d1e6622",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 123260,
"upload_time": "2025-07-25T01:17:35",
"upload_time_iso_8601": "2025-07-25T01:17:35.964537Z",
"url": "https://files.pythonhosted.org/packages/5c/0b/a03967e8a14f62f2707946bd168bb0564e56dcb2b84117a34acf7fd59610/equitrcoder-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 01:17:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "equitr",
"github_project": "equitrcoder",
"github_not_found": true,
"lcname": "equitrcoder"
}
JSON
