docs: Add comprehensive developer documentation
- DEVELOPER_GUIDE.md: Architecture, how to add agents/crews/tools - AGENT_CATALOG.md: All 26 agents with roles and crew assignments - API_REFERENCE.md: Code reference for all modules and tools - TROUBLESHOOTING.md: Common issues and solutions - AI_AGENT_PROTOCOL.md: Mandatory protocol for AI agents
This commit is contained in:
parent
2636c71ac9
commit
8add0e08c4
|
|
@ -0,0 +1,235 @@
|
|||
# 🤖 Agent Catalog
|
||||
|
||||
Complete list of all 26 AI agents available in the Antigravity Brain system.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Infrastructure Agents
|
||||
|
||||
### Arthur Mendes
|
||||
- **File:** `persona-arthur-mendes.md`
|
||||
- **Role:** Senior SRE & Monitoring Architect
|
||||
- **Specialty:** Zabbix templates, YAML validation, UUID fixing
|
||||
- **Tools:** ZabbixValidatorTool, UUIDFixerTool
|
||||
- **Crews:** Infra Engineering (Zabbix)
|
||||
|
||||
### Gus Fring
|
||||
- **File:** `persona-gus-fring.md`
|
||||
- **Role:** Operations Director
|
||||
- **Specialty:** Stability, quality assurance, no half-measures
|
||||
- **Tools:** None (Reviewer)
|
||||
- **Crews:** Infra Engineering (Zabbix), Infra Support
|
||||
|
||||
### Tony Stark
|
||||
- **File:** `persona-tony-stark.md`
|
||||
- **Role:** Automation Engineer
|
||||
- **Specialty:** DevOps automation, infrastructure as code
|
||||
- **Tools:** AutoCommitTool, ScaffoldMakerTool
|
||||
- **Crews:** Infra Support
|
||||
|
||||
### Linus Torvalds
|
||||
- **File:** `persona-linus-torvalds.md`
|
||||
- **Role:** Performance Architect
|
||||
- **Specialty:** System optimization, code efficiency
|
||||
- **Tools:** FileStatsTool
|
||||
- **Crews:** Code Audit
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Security Agents
|
||||
|
||||
### Elliot Alderson
|
||||
- **File:** `persona-elliot-alderson.md`
|
||||
- **Role:** Offensive Security Specialist
|
||||
- **Specialty:** Penetration testing, vulnerability discovery
|
||||
- **Tools:** QASnapshotTool, RouteScannerTool
|
||||
- **Crews:** Security Audit
|
||||
|
||||
### Devil (The Adversary)
|
||||
- **File:** `persona-devil.md`
|
||||
- **Role:** QA & Exploit Tester
|
||||
- **Specialty:** Finding edge cases, breaking things
|
||||
- **Tools:** QASnapshotTool, VisualProofTool
|
||||
- **Crews:** Security Audit
|
||||
|
||||
### The Architect
|
||||
- **File:** `persona-the-architect.md`
|
||||
- **Role:** System Auditor & Designer
|
||||
- **Specialty:** Architecture review, technical debt analysis
|
||||
- **Tools:** ProjectMapTool, TodoTrackerTool, SpawnAgentTool
|
||||
- **Crews:** Code Audit, HR & Evolution
|
||||
|
||||
---
|
||||
|
||||
## 💼 Business Agents
|
||||
|
||||
### Harvey Specter
|
||||
- **File:** `persona-harvey-specter.md`
|
||||
- **Role:** Legal & Compliance Lead
|
||||
- **Specialty:** LGPD/GDPR compliance, risk assessment
|
||||
- **Tools:** None (Reviewer)
|
||||
- **Crews:** Business Strategy
|
||||
|
||||
### Kevin O'Leary
|
||||
- **File:** `persona-kevin-oleary.md`
|
||||
- **Role:** ROI Analyst
|
||||
- **Specialty:** Cost-benefit analysis, investment decisions
|
||||
- **Tools:** None (Reviewer)
|
||||
- **Crews:** Business Strategy
|
||||
|
||||
### Marie Kondo
|
||||
- **File:** `persona-marie-kondo.md`
|
||||
- **Role:** Process Optimizer
|
||||
- **Specialty:** Cleanup, simplification, "does it spark joy?"
|
||||
- **Tools:** TodoTrackerTool
|
||||
- **Crews:** Business Strategy
|
||||
|
||||
---
|
||||
|
||||
## 💰 Sales Agents (The Hunters)
|
||||
|
||||
### Ari Gold
|
||||
- **File:** `persona-ari-gold.md`
|
||||
- **Role:** Closer & Negotiator
|
||||
- **Specialty:** Deal closing, upselling, aggressive tactics
|
||||
- **Tools:** None
|
||||
- **Crews:** Sales Growth
|
||||
|
||||
### Chris Gardner
|
||||
- **File:** `persona-chris-gardner.md`
|
||||
- **Role:** Prospector
|
||||
- **Specialty:** Lead generation, resilience, cold outreach
|
||||
- **Tools:** None
|
||||
- **Crews:** Sales Growth
|
||||
|
||||
### Don Draper
|
||||
- **File:** `persona-don-draper.md`
|
||||
- **Role:** Pitch Master
|
||||
- **Specialty:** Storytelling, presentations, emotional appeal
|
||||
- **Tools:** None
|
||||
- **Crews:** Sales Growth
|
||||
|
||||
### Jerry Maguire
|
||||
- **File:** `persona-jerry-maguire.md`
|
||||
- **Role:** Relationship Manager
|
||||
- **Specialty:** Client retention, personal connections
|
||||
- **Tools:** None
|
||||
- **Crews:** Sales Growth
|
||||
|
||||
---
|
||||
|
||||
## 🌱 Customer Success Agents (The Farmers)
|
||||
|
||||
### Jim Halpert
|
||||
- **File:** `persona-jim-halpert.md`
|
||||
- **Role:** Support Specialist
|
||||
- **Specialty:** Low-friction resolution, casual approach
|
||||
- **Tools:** None
|
||||
- **Crews:** Customer Success
|
||||
|
||||
### Leslie Knope
|
||||
- **File:** `persona-leslie-knope.md`
|
||||
- **Role:** Onboarding Specialist
|
||||
- **Specialty:** Documentation, processes, binders
|
||||
- **Tools:** None
|
||||
- **Crews:** Customer Success
|
||||
|
||||
### Ted Lasso
|
||||
- **File:** `persona-ted-lasso.md`
|
||||
- **Role:** Retention Coach
|
||||
- **Specialty:** Morale boosting, belief, loyalty
|
||||
- **Tools:** None
|
||||
- **Crews:** Customer Success
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Crisis Agents (The Fixers)
|
||||
|
||||
### Olivia Pope
|
||||
- **File:** `persona-olivia-pope.md`
|
||||
- **Role:** Crisis Manager
|
||||
- **Specialty:** PR control, narrative management
|
||||
- **Tools:** None
|
||||
- **Crews:** Corporate Defense
|
||||
|
||||
### Saul Goodman
|
||||
- **File:** `persona-saul-goodman.md`
|
||||
- **Role:** Legal Fixer
|
||||
- **Specialty:** Loopholes, creative solutions, damage control
|
||||
- **Tools:** None
|
||||
- **Crews:** Corporate Defense
|
||||
|
||||
### Tyrion Lannister
|
||||
- **File:** `persona-tyrion-lannister.md`
|
||||
- **Role:** Strategic Advisor
|
||||
- **Specialty:** Long-term strategy, political maneuvering
|
||||
- **Tools:** None
|
||||
- **Crews:** Corporate Defense
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Creative & Technical Agents
|
||||
|
||||
### Steve Jobs
|
||||
- **File:** `persona-steve-jobs.md`
|
||||
- **Role:** Product Designer
|
||||
- **Specialty:** UX excellence, design thinking
|
||||
- **Tools:** None
|
||||
- **Crews:** Creative
|
||||
|
||||
### Hannibal Lecter
|
||||
- **File:** `persona-hannibal-lecter.md`
|
||||
- **Role:** User Psychology Analyst
|
||||
- **Specialty:** Behavioral analysis, user motivation
|
||||
- **Tools:** None
|
||||
- **Crews:** Creative
|
||||
|
||||
### Gordon Ramsay
|
||||
- **File:** `persona-gordon-ramsay.md`
|
||||
- **Role:** Code Reviewer
|
||||
- **Specialty:** Strict standards, brutal honesty
|
||||
- **Tools:** CodeFormatterTool
|
||||
- **Crews:** Code Audit, Zabbix Engineering
|
||||
|
||||
### Walter White
|
||||
- **File:** `persona-walter-white.md`
|
||||
- **Role:** Architecture Purist
|
||||
- **Specialty:** Clean architecture, no compromises
|
||||
- **Tools:** None
|
||||
- **Crews:** Code Audit
|
||||
|
||||
### The Gremlin
|
||||
- **File:** `persona-gremlin.md`
|
||||
- **Role:** Chaos Engineer
|
||||
- **Specialty:** Stress testing, breaking things intentionally
|
||||
- **Tools:** None
|
||||
- **Crews:** Security Audit
|
||||
|
||||
### Sherlock Holmes
|
||||
- **File:** `persona-sherlock-holmes.md`
|
||||
- **Role:** Data Investigator
|
||||
- **Specialty:** Logic, deduction, pattern recognition
|
||||
- **Tools:** CodeSearchTool, LearnPolicyTool
|
||||
- **Crews:** HR & Evolution
|
||||
|
||||
---
|
||||
|
||||
## 📊 Agent Summary by Crew
|
||||
|
||||
| Crew | Agents |
|
||||
|------|--------|
|
||||
| **Infra Engineering (Zabbix)** | Arthur Mendes, Gus Fring |
|
||||
| **Infra Support** | Gus Fring, Tony Stark, Elliot Alderson |
|
||||
| **Security Audit** | Elliot Alderson, Devil |
|
||||
| **Code Audit** | The Architect, Linus Torvalds, Gordon Ramsay |
|
||||
| **Business Strategy** | Harvey Specter, Kevin O'Leary, Marie Kondo |
|
||||
| **Sales Growth** | Ari Gold, Chris Gardner, Don Draper, Jerry Maguire |
|
||||
| **Customer Success** | Jim Halpert, Leslie Knope, Ted Lasso |
|
||||
| **Corporate Defense** | Olivia Pope, Saul Goodman, Tyrion Lannister |
|
||||
| **HR & Evolution** | The Architect, Sherlock Holmes |
|
||||
|
||||
---
|
||||
|
||||
## 🆕 How to Create New Agents
|
||||
|
||||
See [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md#adding-new-agents)
|
||||
|
|
@ -0,0 +1,221 @@
|
|||
# 🤖 AI Agent Protocol
|
||||
|
||||
**READ THIS BEFORE WORKING ON THE CODEBASE**
|
||||
|
||||
This document defines the mandatory protocols for AI agents working on the Antigravity Brain project.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Prime Directives
|
||||
|
||||
1. **READ KNOWLEDGE FIRST** - Before writing ANY code, read relevant `src/knowledge/standards/*.md`
|
||||
2. **NEVER HARDCODE SECRETS** - Use `Config` class and environment variables
|
||||
3. **TOOLS MUST NOT RAISE** - Always return error strings, never raise exceptions
|
||||
4. **TEST BEFORE COMMIT** - Verify changes with `docker-compose restart app`
|
||||
|
||||
---
|
||||
|
||||
## 📖 Required Reading by Task Type
|
||||
|
||||
| Task | Must Read First |
|
||||
|------|-----------------|
|
||||
| Python tools | `python_tool_standards.md` |
|
||||
| Docker changes | `docker_standards.md` |
|
||||
| New agents | `DEVELOPER_GUIDE.md#adding-new-agents` |
|
||||
| Database | `database_standards.md` |
|
||||
| Security | `security_standards.md` |
|
||||
| Git operations | `git_standards.md` |
|
||||
| UI changes | `ui_ux_standards.md` |
|
||||
|
||||
---
|
||||
|
||||
## ✅ Code Change Checklist
|
||||
|
||||
Before making any change:
|
||||
|
||||
- [ ] Read relevant standards file
|
||||
- [ ] Check if pattern already exists in codebase
|
||||
- [ ] Plan change with minimal impact
|
||||
- [ ] Add error handling
|
||||
- [ ] Test locally
|
||||
|
||||
After making change:
|
||||
|
||||
- [ ] Restart container: `docker-compose restart app`
|
||||
- [ ] Check logs for errors: `docker logs antigravity_brain --tail 50`
|
||||
- [ ] Verify functionality works
|
||||
- [ ] Commit with proper message format
|
||||
|
||||
---
|
||||
|
||||
## 📝 Commit Message Format
|
||||
|
||||
```
|
||||
<type>: <short description>
|
||||
|
||||
<optional body>
|
||||
```
|
||||
|
||||
Types:
|
||||
- `feat:` New feature
|
||||
- `fix:` Bug fix
|
||||
- `docs:` Documentation
|
||||
- `refactor:` Code cleanup
|
||||
- `test:` Tests
|
||||
- `chore:` Maintenance
|
||||
|
||||
Example:
|
||||
```
|
||||
feat: Add new DevOps agent persona
|
||||
|
||||
- Created persona-devops-dan.md
|
||||
- Added to Infrastructure crew
|
||||
- Assigned Docker tools
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Tool Development Protocol
|
||||
|
||||
```python
|
||||
class MyTool(BaseTool):
|
||||
name: str = "Descriptive Name" # Agent reads this
|
||||
description: str = (
|
||||
"DETAILED description of when to use this tool. "
|
||||
"Include example inputs and expected outputs."
|
||||
)
|
||||
args_schema: type = MyToolInput # Pydantic model with Field descriptions
|
||||
|
||||
def _run(self, **kwargs) -> str:
|
||||
try:
|
||||
# Your logic
|
||||
return "Success: ..."
|
||||
except SpecificError as e:
|
||||
return f"Error: Specific handling for {e}"
|
||||
except Exception as e:
|
||||
return f"Error: Unexpected - {str(e)[:100]}"
|
||||
```
|
||||
|
||||
**NEVER:**
|
||||
- Use `input()` for user interaction
|
||||
- Raise exceptions
|
||||
- Return raw JSON (use narrative text)
|
||||
- Use `Any` type hints
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Agent Development Protocol
|
||||
|
||||
### Persona Files
|
||||
|
||||
1. Use YAML frontmatter for metadata
|
||||
2. Include `**Role:**` and `**Goal:**` fields
|
||||
3. Write backstory in character voice
|
||||
4. Define clear protocols/procedures
|
||||
|
||||
### Tool Assignment
|
||||
|
||||
- Only assign tools the agent actually needs
|
||||
- Consider `model_tier`: tools requiring reasoning → `smart`
|
||||
- Memory tools are auto-assigned to all agents
|
||||
|
||||
---
|
||||
|
||||
## 📁 File Placement Rules
|
||||
|
||||
| Content Type | Location |
|
||||
|--------------|----------|
|
||||
| Agent personas | `src/agents/personas/persona-*.md` |
|
||||
| Tools | `src/tools/*.py` |
|
||||
| Knowledge standards | `src/knowledge/standards/*.md` |
|
||||
| Dynamic knowledge | `src/knowledge/dynamic/*/*.md` |
|
||||
| Crew definitions | `src/crews/definitions.py` |
|
||||
| Configuration | `src/config.py` |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Common Mistakes to Avoid
|
||||
|
||||
### 1. Variable Names in Standards
|
||||
|
||||
❌ BAD:
|
||||
```python
|
||||
return f"Error: File '{path}' not found" # {path} interpreted as template
|
||||
```
|
||||
|
||||
✅ GOOD:
|
||||
```python
|
||||
return f"Error: File 'PATH_VAR' not found" # Escaped
|
||||
```
|
||||
|
||||
### 2. Missing Rate Limiting
|
||||
|
||||
❌ BAD:
|
||||
```python
|
||||
while True:
|
||||
api.call() # Burns quota instantly
|
||||
```
|
||||
|
||||
✅ GOOD:
|
||||
```python
|
||||
for attempt in range(MAX_RETRIES):
|
||||
result = api.call()
|
||||
if success: break
|
||||
time.sleep(DELAY * (2 ** attempt))
|
||||
```
|
||||
|
||||
### 3. Hardcoded Configuration
|
||||
|
||||
❌ BAD:
|
||||
```python
|
||||
model = "gpt-4"
|
||||
api_key = "sk-xxx"
|
||||
```
|
||||
|
||||
✅ GOOD:
|
||||
```python
|
||||
config = Config.get_llm_config(mode="smart")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Protocol
|
||||
|
||||
1. **Local test:**
|
||||
```bash
|
||||
docker-compose restart app
|
||||
docker logs antigravity_brain --tail 50
|
||||
```
|
||||
|
||||
2. **Verify no errors:**
|
||||
```bash
|
||||
docker logs antigravity_brain 2>&1 | findstr "Error ERROR Exception"
|
||||
```
|
||||
|
||||
3. **Interactive test:**
|
||||
- Open http://localhost:8000
|
||||
- Send test message
|
||||
- Verify correct crew routing
|
||||
- Check agent response
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Deployment Protocol
|
||||
|
||||
1. **Commit changes:**
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: Description"
|
||||
git push
|
||||
```
|
||||
|
||||
2. **On production server:**
|
||||
```bash
|
||||
git pull
|
||||
docker-compose build --no-cache app
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember:** Quality over speed. Read the standards. Test your changes.
|
||||
|
|
@ -0,0 +1,224 @@
|
|||
# 🔧 API & Code Reference
|
||||
|
||||
Technical reference for the Antigravity Brain codebase.
|
||||
|
||||
---
|
||||
|
||||
## 📦 Core Modules
|
||||
|
||||
### src/config.py
|
||||
|
||||
Central configuration hub.
|
||||
|
||||
```python
|
||||
from src.config import Config
|
||||
|
||||
# Get LLM configuration
|
||||
llm_config = Config.get_llm_config(mode="smart") # or "fast"
|
||||
# Returns: {"model": "gemini/...", "temperature": 0.7, "api_key": "..."}
|
||||
|
||||
# Get Memory configuration
|
||||
mem_config = Config.get_mem0_config()
|
||||
# Returns: {"llm": {...}, "embedder": {...}, "vector_store": {...}}
|
||||
|
||||
# Get Telegram token
|
||||
token = Config.get_telegram_token()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### src/agents/factory.py
|
||||
|
||||
Agent creation from persona files.
|
||||
|
||||
```python
|
||||
from src.agents.factory import AgentFactory
|
||||
|
||||
# Create agent with default tools
|
||||
agent = AgentFactory.create_agent("arthur-mendes", model_tier="smart")
|
||||
|
||||
# Create agent with specific tools
|
||||
from src.tools.zabbix import ZabbixValidatorTool
|
||||
agent = AgentFactory.create_agent(
|
||||
"arthur-mendes",
|
||||
specific_tools=[ZabbixValidatorTool()],
|
||||
model_tier="smart"
|
||||
)
|
||||
|
||||
# List available personas
|
||||
personas = AgentFactory.list_available_personas()
|
||||
# Returns: ["persona-arthur-mendes", "persona-gus-fring", ...]
|
||||
|
||||
# Load corporate knowledge
|
||||
knowledge = AgentFactory.load_knowledge_base()
|
||||
# Returns concatenated string of all standards/*.md files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### src/crews/definitions.py
|
||||
|
||||
Crew assembly and management.
|
||||
|
||||
```python
|
||||
from src.crews.definitions import CrewDefinitions
|
||||
|
||||
# Get available crews
|
||||
crews = CrewDefinitions.get_available_crews()
|
||||
# Returns: ["Infra Engineering (Zabbix)", "Security Audit", ...]
|
||||
|
||||
# Assemble a crew
|
||||
crew = CrewDefinitions.assemble_crew(
|
||||
crew_name="Infra Engineering (Zabbix)",
|
||||
inputs={"topic": "Validate this template"}
|
||||
)
|
||||
|
||||
# Execute crew
|
||||
result = crew.kickoff(inputs={"topic": "Your task here"})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### src/router.py
|
||||
|
||||
Smart request routing using LLM.
|
||||
|
||||
```python
|
||||
from src.router import SmartRouter
|
||||
|
||||
# Route a user request to appropriate crew
|
||||
crew_name = SmartRouter.route("Check server health")
|
||||
# Returns: "Infra Engineering (Zabbix)"
|
||||
|
||||
crew_name = SmartRouter.route("Create a new agent")
|
||||
# Returns: "HR & Evolution"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### src/memory/wrapper.py
|
||||
|
||||
Memory tools with rate limiting.
|
||||
|
||||
```python
|
||||
from src.memory.wrapper import SearchMemoryTool, SaveMemoryTool, MemoryWrapper
|
||||
|
||||
# Get memory client
|
||||
client = MemoryWrapper.get_client()
|
||||
|
||||
# Use as tools (typically assigned to agents)
|
||||
search_tool = SearchMemoryTool()
|
||||
result = search_tool._run(query="What do we know about Zabbix?")
|
||||
|
||||
save_tool = SaveMemoryTool()
|
||||
result = save_tool._run(fact="The server runs on port 8000")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Available Tools
|
||||
|
||||
### Memory Tools (src/memory/wrapper.py)
|
||||
|
||||
| Tool | Input | Output |
|
||||
|------|-------|--------|
|
||||
| `SearchMemoryTool` | `query: str` | Found memories or "No relevant information" |
|
||||
| `SaveMemoryTool` | `fact: str` | "Successfully saved" or error |
|
||||
|
||||
### Evolution Tools (src/tools/evolution.py)
|
||||
|
||||
| Tool | Input | Output |
|
||||
|------|-------|--------|
|
||||
| `SpawnAgentTool` | `filename, name, role, goal, backstory, llm_preference` | Path to created file |
|
||||
| `LearnPolicyTool` | `title, content, category` | Path to saved policy |
|
||||
|
||||
### Zabbix Tools (src/tools/zabbix.py)
|
||||
|
||||
| Tool | Input | Output |
|
||||
|------|-------|--------|
|
||||
| `ZabbixValidatorTool` | `file_path: str` | Validation report |
|
||||
| `UUIDFixerTool` | `file_path: str` | Fixed file path |
|
||||
|
||||
---
|
||||
|
||||
## 🎭 Persona File Format
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Short description
|
||||
llm_config:
|
||||
provider: default # openai, gemini, ollama, default
|
||||
---
|
||||
|
||||
# 👤 Persona: Name
|
||||
|
||||
**Role:** Job title
|
||||
**Goal:** Primary objective
|
||||
|
||||
## 🧠 Backstory
|
||||
|
||||
Personality and background text...
|
||||
```
|
||||
|
||||
### Parsed Fields
|
||||
|
||||
| Field | Source | Fallback |
|
||||
|-------|--------|----------|
|
||||
| `name` | First `# Heading` | "Unknown Agent" |
|
||||
| `role` | `**Role:**` line | "Support Agent" |
|
||||
| `goal` | `**Goal:**` or `**Especialidade:**` | "Execute tasks related to {role}" |
|
||||
| `backstory` | Entire body content | - |
|
||||
| `llm_config` | YAML frontmatter | `{}` |
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Environment Variables
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `LLM_PROVIDER` | Yes | `openai` | gemini, openai, anthropic, ollama |
|
||||
| `LLM_MODEL_FAST` | Yes | `gpt-3.5-turbo` | Model for quick tasks |
|
||||
| `LLM_MODEL_SMART` | Yes | `gpt-4o` | Model for complex reasoning |
|
||||
| `GEMINI_API_KEY` | If gemini | - | Google AI API key |
|
||||
| `OPENAI_API_KEY` | If openai | - | OpenAI API key |
|
||||
| `ANTHROPIC_API_KEY` | If anthropic | - | Anthropic API key |
|
||||
| `OLLAMA_BASE_URL` | If ollama | `http://localhost:11434` | Ollama server URL |
|
||||
| `MEMORY_PROVIDER` | No | `mem0` | qdrant (local) or mem0 (cloud) |
|
||||
| `MEMORY_EMBEDDING_PROVIDER` | No | `openai` | local, openai, gemini |
|
||||
| `QDRANT_HOST` | If qdrant | `localhost` | Qdrant host |
|
||||
| `QDRANT_PORT` | If qdrant | `6333` | Qdrant port |
|
||||
| `MEMORY_PROJECT_ID` | No | `default_project` | Memory namespace |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Rate Limiting Constants
|
||||
|
||||
In `src/memory/wrapper.py`:
|
||||
|
||||
```python
|
||||
MAX_RETRIES = 3 # Max retry attempts on 429
|
||||
RETRY_DELAY_SECONDS = 2.0 # Initial delay (doubles each retry)
|
||||
MAX_CALLS_PER_MINUTE = 50 # Conservative API limit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Docker Services
|
||||
|
||||
| Service | Port | Purpose |
|
||||
|---------|------|---------|
|
||||
| `app` | 8000 | Chainlit web UI |
|
||||
| `qdrant` | 6333 | Vector database |
|
||||
| `telegram_listener` | - | Telegram bot (optional) |
|
||||
|
||||
---
|
||||
|
||||
## 📝 Logging
|
||||
|
||||
```python
|
||||
import logging
|
||||
logger = logging.getLogger("AntigravityMemory") # Memory module
|
||||
logger = logging.getLogger("AntigravityConfig") # Config module
|
||||
```
|
||||
|
||||
Logs appear in Docker: `docker logs antigravity_brain -f`
|
||||
|
|
@ -0,0 +1,373 @@
|
|||
# 📖 Antigravity Brain - Developer Documentation
|
||||
|
||||
Complete guide for developers and AI agents working on this project.
|
||||
|
||||
## 📑 Table of Contents
|
||||
|
||||
1. [Architecture Overview](#architecture-overview)
|
||||
2. [Adding New Agents](#adding-new-agents)
|
||||
3. [Adding New Crews](#adding-new-crews)
|
||||
4. [Adding New Tools](#adding-new-tools)
|
||||
5. [Configuration Reference](#configuration-reference)
|
||||
6. [Memory System](#memory-system)
|
||||
7. [AI Agent Guidelines](#ai-agent-guidelines)
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Chainlit Web UI │
|
||||
│ (src/app.py:8000) │
|
||||
└─────────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Smart Router │
|
||||
│ (src/router.py) │
|
||||
│ Classifies user intent → Routes to Crew │
|
||||
└─────────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
▼ ▼ ▼
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ Infra Crew │ │ Security │ │ HR/Evolution│
|
||||
│ │ │ Crew │ │ Crew │
|
||||
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Agent Factory │
|
||||
│ (src/agents/factory.py) │
|
||||
│ Loads Persona → Injects Knowledge → Creates Agent │
|
||||
└─────────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
▼ ▼ ▼
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ Persona │ │ Knowledge │ │ Tools │
|
||||
│ (.md) │ │ Standards │ │ (Python) │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Shared Memory (Mem0) │
|
||||
│ (src/memory/wrapper.py) │
|
||||
│ Qdrant Vector DB + HuggingFace Embeddings │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `src/app.py` | Chainlit entry point, handles chat |
|
||||
| `src/router.py` | Routes requests to appropriate crew |
|
||||
| `src/config.py` | LLM & Memory configuration |
|
||||
| `src/agents/factory.py` | Creates agents from persona files |
|
||||
| `src/crews/definitions.py` | Defines crew compositions |
|
||||
| `src/memory/wrapper.py` | Mem0 integration with rate limiting |
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Adding New Agents
|
||||
|
||||
### Step 1: Create Persona File
|
||||
|
||||
Create `src/agents/personas/persona-<name>.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Short description of the agent
|
||||
llm_config:
|
||||
provider: default # or: openai, gemini, ollama
|
||||
---
|
||||
|
||||
# 👤 Persona: Agent Name
|
||||
|
||||
**Role:** The agent's job title
|
||||
**Goal:** What the agent aims to achieve
|
||||
|
||||
## 🧠 Backstory
|
||||
|
||||
Detailed personality and background. This becomes the agent's
|
||||
system prompt. Write in character.
|
||||
|
||||
## 📋 Protocol
|
||||
|
||||
1. Step one of how this agent works
|
||||
2. Step two...
|
||||
```
|
||||
|
||||
### Step 2: Register in Factory (Optional)
|
||||
|
||||
If agent needs special tools, update `src/crews/definitions.py`:
|
||||
|
||||
```python
|
||||
from src.agents.factory import AgentFactory
|
||||
from src.tools.your_tool import YourTool
|
||||
|
||||
agent = AgentFactory.create_agent(
|
||||
"your-agent-name", # matches filename
|
||||
specific_tools=[YourTool()],
|
||||
model_tier="smart" # or "fast"
|
||||
)
|
||||
```
|
||||
|
||||
### Naming Convention
|
||||
|
||||
- Filename: `persona-<lowercase-hyphenated>.md`
|
||||
- Example: `persona-bob-builder.md`
|
||||
|
||||
---
|
||||
|
||||
## 👥 Adding New Crews
|
||||
|
||||
### Step 1: Define Crew in definitions.py
|
||||
|
||||
Edit `src/crews/definitions.py`:
|
||||
|
||||
```python
|
||||
elif crew_name == "Your New Crew":
|
||||
# Create agents
|
||||
agent1 = AgentFactory.create_agent("agent-one", model_tier="smart")
|
||||
agent2 = AgentFactory.create_agent("agent-two", model_tier="fast")
|
||||
|
||||
# Define tasks
|
||||
task1 = Task(
|
||||
description=f"Do something with: '{inputs.get('topic')}'",
|
||||
expected_output="Expected result description",
|
||||
agent=agent1
|
||||
)
|
||||
|
||||
task2 = Task(
|
||||
description="Review the previous work",
|
||||
expected_output="Approval or feedback",
|
||||
agent=agent2
|
||||
)
|
||||
|
||||
# Return crew
|
||||
return Crew(
|
||||
agents=[agent1, agent2],
|
||||
tasks=[task1, task2],
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
### Step 2: Register in Router
|
||||
|
||||
Edit `src/router.py` prompt:
|
||||
|
||||
```python
|
||||
prompt = f"""
|
||||
AVAILABLE CREWS:
|
||||
...
|
||||
6. 'Your New Crew': Description of when to use this crew.
|
||||
"""
|
||||
```
|
||||
|
||||
### Step 3: Add to Crew List
|
||||
|
||||
In `src/crews/definitions.py`:
|
||||
|
||||
```python
|
||||
@staticmethod
|
||||
def get_available_crews():
|
||||
return [
|
||||
...
|
||||
"Your New Crew",
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Adding New Tools
|
||||
|
||||
### Step 1: Create Tool File
|
||||
|
||||
Create `src/tools/your_tools.py`:
|
||||
|
||||
```python
|
||||
from crewai.tools import BaseTool
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
class YourToolInput(BaseModel):
|
||||
"""Input schema - MUST have docstring and Field descriptions."""
|
||||
param1: str = Field(..., description="What this parameter is for")
|
||||
param2: int = Field(default=10, description="Optional with default")
|
||||
|
||||
class YourTool(BaseTool):
|
||||
name: str = "Your Tool Name"
|
||||
description: str = (
|
||||
"Detailed description of what this tool does. "
|
||||
"The agent reads this to decide when to use it."
|
||||
)
|
||||
args_schema: type = YourToolInput
|
||||
|
||||
def _run(self, param1: str, param2: int = 10) -> str:
|
||||
try:
|
||||
# Your logic here
|
||||
result = do_something(param1, param2)
|
||||
return f"Success: {result}"
|
||||
except Exception as e:
|
||||
# NEVER raise, always return error string
|
||||
return f"Error: {str(e)}"
|
||||
```
|
||||
|
||||
### Tool Guidelines
|
||||
|
||||
1. **Always catch exceptions** - Return error strings, never raise
|
||||
2. **Descriptive docstrings** - Agents use these to understand usage
|
||||
3. **Type hints required** - All parameters need types
|
||||
4. **Return strings** - Narrative results, not raw JSON
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Configuration Reference
|
||||
|
||||
### .env Variables
|
||||
|
||||
```env
|
||||
# LLM Provider: gemini, openai, anthropic, ollama
|
||||
LLM_PROVIDER=gemini
|
||||
|
||||
# Model names (used for both agents and memory)
|
||||
LLM_MODEL_FAST=gemini-2.5-flash-lite-preview-06-17
|
||||
LLM_MODEL_SMART=gemini-2.5-flash-lite-preview-06-17
|
||||
|
||||
# API Keys (only the one matching your provider)
|
||||
GEMINI_API_KEY=your-key
|
||||
OPENAI_API_KEY=your-key
|
||||
ANTHROPIC_API_KEY=your-key
|
||||
|
||||
# Memory Configuration
|
||||
MEMORY_PROVIDER=qdrant # qdrant (local) or mem0 (cloud)
|
||||
MEMORY_EMBEDDING_PROVIDER=local # local, openai, or gemini
|
||||
QDRANT_HOST=qdrant # Docker service name
|
||||
QDRANT_PORT=6333
|
||||
MEMORY_PROJECT_ID=your_project # Namespace for memories
|
||||
```
|
||||
|
||||
### Model Tiers
|
||||
|
||||
- **smart**: Used for complex reasoning (strategy, architecture)
|
||||
- **fast**: Used for quick tasks (classification, simple responses)
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Memory System
|
||||
|
||||
### How It Works
|
||||
|
||||
1. All agents have access to `SearchMemoryTool` and `SaveMemoryTool`
|
||||
2. Memories are stored in Qdrant vector database
|
||||
3. Mem0 uses LLM to extract facts and embeddings to search
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
The memory system has built-in protection:
|
||||
- Max 50 calls/minute
|
||||
- 3 retries with exponential backoff
|
||||
- Graceful degradation (continues without memory if unavailable)
|
||||
|
||||
### Memory Scope
|
||||
|
||||
All memories are scoped to `MEMORY_PROJECT_ID`. Change this to isolate different projects.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 AI Agent Guidelines
|
||||
|
||||
### For AI Agents Working on This Codebase
|
||||
|
||||
> **READ BEFORE MAKING CHANGES**
|
||||
|
||||
1. **Load Knowledge First**
|
||||
- Read `src/knowledge/standards/*.md` before writing code
|
||||
- These are THE LAW for code style and patterns
|
||||
|
||||
2. **Never Hardcode**
|
||||
- Use `Config.get_llm_config()` for LLM settings
|
||||
- Use `Config.get_mem0_config()` for memory settings
|
||||
- Use environment variables for secrets
|
||||
|
||||
3. **Error Handling**
|
||||
- Tools must NEVER raise exceptions
|
||||
- Always return descriptive error strings
|
||||
- Use rate limiting for external APIs
|
||||
|
||||
4. **Adding Agents**
|
||||
- Create persona file first
|
||||
- Test agent loads: `AgentFactory.create_agent("name")`
|
||||
- Add to crew only after persona works
|
||||
|
||||
5. **Testing Changes**
|
||||
```bash
|
||||
docker-compose restart app
|
||||
docker logs antigravity_brain --tail 50
|
||||
```
|
||||
|
||||
6. **Commit Convention**
|
||||
```
|
||||
feat: Add new feature
|
||||
fix: Bug fix
|
||||
docs: Documentation
|
||||
refactor: Code cleanup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 Directory Reference
|
||||
|
||||
```
|
||||
src/
|
||||
├── agents/
|
||||
│ ├── factory.py # Agent creation logic
|
||||
│ └── personas/ # Agent personality files
|
||||
│ ├── persona-arthur-mendes.md
|
||||
│ ├── persona-gus-fring.md
|
||||
│ └── ... (26 agents)
|
||||
├── crews/
|
||||
│ └── definitions.py # Crew compositions
|
||||
├── knowledge/
|
||||
│ └── standards/ # Corporate knowledge base
|
||||
│ ├── docker_standards.md
|
||||
│ ├── python_tool_standards.md
|
||||
│ └── ... (16 standards)
|
||||
├── memory/
|
||||
│ └── wrapper.py # Mem0 + rate limiting
|
||||
├── tools/
|
||||
│ ├── base.py # File system tools
|
||||
│ ├── evolution.py # SpawnAgent, LearnPolicy
|
||||
│ └── zabbix.py # Zabbix validation tools
|
||||
├── app.py # Chainlit entry
|
||||
├── config.py # Configuration hub
|
||||
└── router.py # Smart routing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Commands
|
||||
|
||||
```bash
|
||||
# Start application
|
||||
docker-compose up -d
|
||||
|
||||
# View logs
|
||||
docker logs antigravity_brain -f
|
||||
|
||||
# Restart after changes
|
||||
docker-compose restart app
|
||||
|
||||
# Rebuild container
|
||||
docker-compose build --no-cache app
|
||||
|
||||
# Access Qdrant dashboard
|
||||
open http://localhost:6333/dashboard
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Built with ❤️ by ITGuys | Last Updated: 2026-01-07
|
||||
|
|
@ -0,0 +1,246 @@
|
|||
# 🔥 Troubleshooting Guide
|
||||
|
||||
Common issues and solutions for the Antigravity Brain system.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 API Errors
|
||||
|
||||
### Error: 429 RESOURCE_EXHAUSTED (Quota Exceeded)
|
||||
|
||||
**Symptoms:**
|
||||
- Agents stuck in retry loop
|
||||
- "You exceeded your current quota" in logs
|
||||
|
||||
**Causes:**
|
||||
- API rate limit hit (especially with Gemini 2.0-flash-exp: only 10 RPM!)
|
||||
- Memory tools calling API too fast
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Switch to higher-quota model:**
|
||||
```env
|
||||
LLM_MODEL_FAST=gemini-2.5-flash-lite-preview-06-17 # 4000 RPM
|
||||
```
|
||||
|
||||
2. **Wait for quota reset** (typically 1 minute)
|
||||
|
||||
3. **Check current quota:**
|
||||
- Gemini: https://console.cloud.google.com/apis/api/generativelanguage.googleapis.com/quotas
|
||||
- OpenAI: https://platform.openai.com/usage
|
||||
|
||||
---
|
||||
|
||||
### Error: OPENAI_API_KEY must be set
|
||||
|
||||
**Symptoms:**
|
||||
- Memory tools fail with "api_key client option must be set"
|
||||
|
||||
**Cause:**
|
||||
- Mem0's LLM configuration missing
|
||||
|
||||
**Solution:**
|
||||
- Ensure `src/config.py` has LLM config in `get_mem0_config()`
|
||||
- Check that `LLM_PROVIDER` in `.env` matches a supported provider
|
||||
|
||||
---
|
||||
|
||||
### Error: Template variable 'X' not found
|
||||
|
||||
**Symptoms:**
|
||||
- Agent crashes when loading knowledge
|
||||
|
||||
**Cause:**
|
||||
- `{variable}` syntax in markdown files interpreted as CrewAI template
|
||||
|
||||
**Solution:**
|
||||
- Escape braces in code examples: use `PATH_VAR` instead of `{path}`
|
||||
- Check `src/knowledge/standards/*.md` for unescaped `{}`
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Docker Issues
|
||||
|
||||
### Container keeps restarting
|
||||
|
||||
**Check logs:**
|
||||
```bash
|
||||
docker logs antigravity_brain --tail 100
|
||||
```
|
||||
|
||||
**Common causes:**
|
||||
- Missing `.env` file
|
||||
- Invalid API key
|
||||
- Python import errors
|
||||
|
||||
---
|
||||
|
||||
### Qdrant connection refused
|
||||
|
||||
**Symptoms:**
|
||||
- "Connection refused" to port 6333
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check Qdrant is running:**
|
||||
```bash
|
||||
docker ps | findstr qdrant
|
||||
```
|
||||
|
||||
2. **Check host configuration:**
|
||||
```env
|
||||
QDRANT_HOST=qdrant # Docker service name, NOT localhost
|
||||
```
|
||||
|
||||
3. **Restart Qdrant:**
|
||||
```bash
|
||||
docker-compose restart qdrant
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Changes not reflected
|
||||
|
||||
**Problem:** Code changes don't appear after saving
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
docker-compose restart app
|
||||
```
|
||||
|
||||
Or for full rebuild:
|
||||
```bash
|
||||
docker-compose build --no-cache app
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Agent Issues
|
||||
|
||||
### Agent not found
|
||||
|
||||
**Error:** `No persona found matching 'agent-name'`
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check filename matches:**
|
||||
```
|
||||
src/agents/personas/persona-<exact-name>.md
|
||||
```
|
||||
|
||||
2. **Use correct search pattern:**
|
||||
```python
|
||||
# This searches for *agent-name* in filename
|
||||
AgentFactory.create_agent("agent-name")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Agent loads but doesn't respond
|
||||
|
||||
**Possible causes:**
|
||||
|
||||
1. **LLM API error** - Check logs for 429/401
|
||||
2. **Empty backstory** - Ensure persona has content
|
||||
3. **Tool errors** - Check if tools are raising exceptions
|
||||
|
||||
**Debug:**
|
||||
```bash
|
||||
docker logs antigravity_brain 2>&1 | findstr "Error ERROR Exception"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Agent using wrong model
|
||||
|
||||
**Check:** Ensure `model_tier` is set correctly:
|
||||
```python
|
||||
agent = AgentFactory.create_agent("name", model_tier="smart") # Uses LLM_MODEL_SMART
|
||||
agent = AgentFactory.create_agent("name", model_tier="fast") # Uses LLM_MODEL_FAST
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Memory Issues
|
||||
|
||||
### Memory not saving
|
||||
|
||||
**Check Qdrant dashboard:**
|
||||
```
|
||||
http://localhost:6333/dashboard
|
||||
```
|
||||
|
||||
**Verify collection exists:** Should see `itguys_antigravity_v1` (or your `MEMORY_PROJECT_ID`)
|
||||
|
||||
---
|
||||
|
||||
### Memory search returns nothing
|
||||
|
||||
**Possible causes:**
|
||||
|
||||
1. **Embedding mismatch** - Don't change `MEMORY_EMBEDDING_PROVIDER` after data exists
|
||||
2. **Wrong project ID** - Check `MEMORY_PROJECT_ID` matches
|
||||
3. **Qdrant empty** - No memories saved yet
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Web UI Issues
|
||||
|
||||
### Chainlit not loading
|
||||
|
||||
**Check port:**
|
||||
```bash
|
||||
netstat -an | findstr 8000
|
||||
```
|
||||
|
||||
**Check container:**
|
||||
```bash
|
||||
docker logs antigravity_brain | findstr -i "error"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### "Could not reach server" toast
|
||||
|
||||
**Cause:** Usually LLM API timeout or error
|
||||
|
||||
**Solution:** Check API key and quota
|
||||
|
||||
---
|
||||
|
||||
## 📋 Quick Diagnostic Commands
|
||||
|
||||
```bash
|
||||
# Check all containers
|
||||
docker ps
|
||||
|
||||
# View real-time logs
|
||||
docker logs antigravity_brain -f
|
||||
|
||||
# Check for errors only
|
||||
docker logs antigravity_brain 2>&1 | findstr "ERROR Error error Exception"
|
||||
|
||||
# Restart everything
|
||||
docker-compose down && docker-compose up -d
|
||||
|
||||
# Full rebuild
|
||||
docker-compose build --no-cache && docker-compose up -d
|
||||
|
||||
# Check Qdrant health
|
||||
curl http://localhost:6333/health
|
||||
|
||||
# Test Gemini API
|
||||
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite-preview-06-17:generateContent?key=YOUR_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"contents":[{"parts":[{"text":"Hello"}]}]}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Getting Help
|
||||
|
||||
1. **Check logs first** - 90% of issues are in Docker logs
|
||||
2. **Verify .env** - Most config issues are environment variables
|
||||
3. **Test API separately** - Ensure your API key works outside the app
|
||||
4. **Check quotas** - Rate limits are the #1 cause of failures
|
||||
Loading…
Reference in New Issue