<p align="center">
  <img src="assets/elgringo-logo.png" alt="El Gringo" width="200">
</p>

<h1 align="center">El Gringo</h1>

<p align="center">
  <a href="https://pypi.org/project/el-gringo/"><img src="https://img.shields.io/pypi/v/el-gringo.svg" alt="PyPI"></a>
  <a href="https://github.com/TheGringo-ai/ElGringo/actions/workflows/ci.yml"><img src="https://github.com/TheGringo-ai/ElGringo/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python 3.9+"></a>
</p>

<p align="center"><strong>Multi-agent AI dev tool. Ask 5 AI models, get one answer.</strong></p>

---

## Install

```bash
pip install el-gringo
```

## Setup (60 seconds)

```bash
elgringo setup
```

The wizard walks you through adding API keys, detects local models, and writes `~/.elgringo/config.yml`. Skip any provider you don't have.

**No keys at all?** Use local models for free:
```bash
ollama pull llama3.2:3b
elgringo setup    # select local only
```

## Quick Start

```bash
# Ask anything
elgringo ask "explain this error: TypeError: 'NoneType' object is not subscriptable"

# Code review
elgringo review server.py

# Fix code (reads, plans, writes, tests)
elgringo fix "add error handling to the login endpoint" auth.py

# Generate tests
elgringo test utils.py

# Security audit
cat app.py | elgringo secure

# Autonomous build
elgringo build "a FastAPI REST API with JWT auth"
```

## Claude Code Integration

```bash
elgringo mcp install
# Restart Claude Code — 73 MCP tools now available
```

Or check status:
```bash
elgringo mcp status
```

---

## Commands (30+)

### Code
| Command | What it does |
|---------|-------------|
| `elgringo review <file>` | Multi-agent code review |
| `elgringo debug <error>` | Debug an error |
| `elgringo test <file>` | Generate tests |
| `elgringo refactor <file>` | Refactor code |
| `elgringo secure <file>` | Security audit |
| `elgringo optimize <file>` | Performance tuning |
| `elgringo explain <file>` | Explain code |

### Coding (writes files)
| Command | What it does |
|---------|-------------|
| `elgringo fix "task" [files]` | Edit existing code |
| `elgringo code "task" [files]` | Write new code |
| `elgringo implement "task" --commit` | Implement + auto-commit |
| `elgringo build "description"` | Full autonomous build |
| `elgringo undo` | Revert last change |
| `elgringo diff` | Show last change |

### Business
| Command | What it does |
|---------|-------------|
| `elgringo pitch "idea"` | Investor-ready pitch |
| `elgringo mvp "idea"` | MVP spec + timeline |
| `elgringo ship "product"` | Launch checklist |
| `elgringo market "product"` | Marketing strategy |
| `elgringo revenue "idea"` | Revenue model |
| `elgringo compete "vs X"` | Competitive analysis |

### General
| Command | What it does |
|---------|-------------|
| `elgringo ask "question"` | Ask anything |
| `elgringo write "topic"` | Write content |
| `elgringo analyze <file>` | Analyze data/logs |
| `elgringo research "topic"` | Deep research |
| `elgringo plan "goal"` | Action plan |
| `elgringo summarize <file>` | Summarize content |
| `elgringo deploy "task"` | DevOps guidance |

### System
| Command | What it does |
|---------|-------------|
| `elgringo setup` | Configure API keys |
| `elgringo mcp install` | Add to Claude Code |
| `elgringo stats` | Cost breakdown + performance |
| `elgringo models` | Show all agents + status |

### Pipe support
```bash
cat error.log | elgringo debug
git diff | elgringo review
cat data.csv | elgringo analyze
cat README.md | elgringo summarize
```

---

## How It Works

```
Your task
    |
+---+---+
| Router |  Picks the best agent(s) based on task type + past performance
+--+-+--+
   | |
+--+ +--+--------+
|GPT| |Gemini| |Grok|   Agents work in parallel
+--+ +------+ +----+
   | |    |
+--+-+----+--+
|  Consensus  |  Weighted synthesis (not concatenation)
+------+------+
       |
+------+------+
| Self-Correct |  If tests fail, retry with new strategy
+------+------+
       |
+------+------+
|   Memory    |  Store what worked, prevent repeat mistakes
+-------------+
```

The orchestrator:
1. **Plans** -- decomposes goals into dependency-aware subtasks
2. **Routes** -- picks the best agent per subtask (learned from feedback)
3. **Executes** -- runs subtasks in parallel batches
4. **Validates** -- sandboxes and tests generated code
5. **Corrects** -- retries failures with 7 adaptive strategies
6. **Learns** -- records outcomes so the next run is smarter

---

## Free Tier

Works fully offline with Ollama. No API keys needed.

```bash
ollama pull llama3.2:3b
elgringo setup        # skip all cloud providers
elgringo ask "hello"  # runs locally
```

## Cloud Agents

Add API keys for higher quality. Each provider adds one or more agents:

| Provider | Agent | What it's good at |
|----------|-------|------------------|
| OpenAI | ChatGPT | Coding, debugging, optimization |
| Google | Gemini | Creative solutions, UI/UX |
| xAI | Grok | Reasoning, strategy, fast coding |
| Anthropic | Claude | Architecture, analysis, planning |

---

## Python API

```python
from elgringo.orchestrator import AIDevTeam

team = AIDevTeam(project_name="my-app", enable_memory=True)

result = await team.collaborate("Design a database schema for a blog")
print(result.final_answer)
print(result.confidence_score)  # 0.0-1.0
print(result.participating_agents)  # ['chatgpt-coder', 'grok-reasoner']
```

## REST API

```bash
uvicorn products.fred_api.server:app --port 8090

curl -X POST http://localhost:8090/v1/collaborate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Review this auth system", "mode": "parallel"}'
```

---

## Stats

- **69,000+** lines of Python across **149** modules
- **6** AI providers (ChatGPT, Gemini, Grok, Claude, Ollama, LlamaCloud)
- **8** collaboration modes
- **73** MCP tools
- **18** development tools
- **7** self-correction strategies
- **544+** tests passing

## What This Is NOT

- **Not a wrapper around one model** -- orchestrates multiple models with routing, consensus, and memory
- **Not a chatbot** -- agents execute tools, write code, run tests, deploy
- **Not autonomous without consent** -- coding commands confirm before writing files
- **Not a hosted service** -- runs on your machine, your keys stay local

## Security

See [SECURITY.md](SECURITY.md) for the security model, tool permissions, and vulnerability reporting.

## License

Apache 2.0 - see [LICENSE](LICENSE)

Copyright 2024-2026 TheGringo AI
