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