374 lines
12 KiB
Markdown
374 lines
12 KiB
Markdown
# 📖 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
|