# 📖 Antigravity Brain - Documentação para Desenvolvedores

Guia completo para desenvolvedores e agentes de IA trabalhando neste projeto.

## 📑 Índice

1. [Visão Geral da Arquitetura](#visão-geral-da-arquitetura)
2. [Adicionando Novos Agentes](#adicionando-novos-agentes)
3. [Adicionando Novas Crews](#adicionando-novas-crews)
4. [Adicionando Novas Ferramentas](#adicionando-novas-ferramentas)
5. [Referência de Configuração](#referência-de-configuração)
6. [Sistema de Memória](#sistema-de-memória)
7. [Diretrizes para Agentes de IA](#diretrizes-para-agentes-de-ia)

---

## 🏗️ Visão Geral da Arquitetura

```
┌─────────────────────────────────────────────────────────────────┐
│                        Interface Web Chainlit                    │
│                      (src/app.py:8000)                          │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Roteador Inteligente                        │
│                    (src/router.py)                               │
│         Classifica intenção do usuário → Roteia para Crew        │
└─────────────────────────┬───────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│ Crew Infra  │   │ Crew        │   │ Crew RH/    │
│             │   │ Segurança   │   │ Evolução    │
└──────┬──────┘   └──────┬──────┘   └──────┬──────┘
       │                 │                 │
       ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Fábrica de Agentes                          │
│                  (src/agents/factory.py)                         │
│      Carrega Persona → Injeta Conhecimento → Cria Agente         │
└─────────────────────────┬───────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│   Persona   │   │ Conhecimento│   │ Ferramentas │
│    (.md)    │   │   Padrões   │   │  (Python)   │
└─────────────┘   └─────────────┘   └─────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                 Memória Compartilhada (Mem0)                     │
│                   (src/memory/wrapper.py)                        │
│              Qdrant Vector DB + HuggingFace Embeddings           │
└─────────────────────────────────────────────────────────────────┘
```

### Arquivos Principais

| Arquivo | Propósito |
|---------|-----------|
| `src/app.py` | Ponto de entrada Chainlit, gerencia chat |
| `src/router.py` | Roteia requisições para crew apropriada |
| `src/config.py` | Configuração LLM & Memória |
| `src/agents/factory.py` | Cria agentes a partir de arquivos de persona |
| `src/crews/definitions.py` | Define composições de crews |
| `src/memory/wrapper.py` | Integração Mem0 com rate limiting |

---

## 🤖 Adicionando Novos Agentes

### Passo 1: Criar Arquivo de Persona

Crie `src/agents/personas/persona-<nome>.md`:

```markdown
---
description: Descrição curta do agente
llm_config:
  provider: default  # ou: openai, gemini, ollama
---

# 👤 Persona: Nome do Agente

**Papel:** O cargo do agente
**Objetivo:** O que o agente busca alcançar

## 🧠 História

Personalidade e histórico detalhados. Isto se torna o
prompt de sistema do agente. Escreva na voz do personagem.

## 📋 Protocolo

1. Primeiro passo de como este agente trabalha
2. Segundo passo...
```

### Passo 2: Registrar na Fábrica (Opcional)

Se o agente precisa de ferramentas especiais, atualize `src/crews/definitions.py`:

```python
from src.agents.factory import AgentFactory
from src.tools.sua_tool import SuaTool

agent = AgentFactory.create_agent(
    "seu-agente-nome",  # corresponde ao nome do arquivo
    specific_tools=[SuaTool()],
    model_tier="smart"  # ou "fast"
)
```

### Convenção de Nomenclatura

- Nome do arquivo: `persona-<minusculo-hifenizado>.md`
- Exemplo: `persona-bob-builder.md`

---

## 👥 Adicionando Novas Crews

### Passo 1: Definir Crew em definitions.py

Edite `src/crews/definitions.py`:

```python
elif crew_name == "Sua Nova Crew":
    # Criar agentes
    agent1 = AgentFactory.create_agent("agente-um", model_tier="smart")
    agent2 = AgentFactory.create_agent("agente-dois", model_tier="fast")
    
    # Definir tarefas
    task1 = Task(
        description=f"Fazer algo com: '{inputs.get('topic')}'",
        expected_output="Descrição do resultado esperado",
        agent=agent1
    )
    
    task2 = Task(
        description="Revisar o trabalho anterior",
        expected_output="Aprovação ou feedback",
        agent=agent2
    )
    
    # Retornar crew
    return Crew(
        agents=[agent1, agent2],
        tasks=[task1, task2],
        process=Process.sequential,
        verbose=True
    )
```

### Passo 2: Registrar no Roteador

Edite o prompt em `src/router.py`:

```python
prompt = f"""
CREWS DISPONÍVEIS:
...
6. 'Sua Nova Crew': Descrição de quando usar esta crew.
"""
```

### Passo 3: Adicionar à Lista de Crews

Em `src/crews/definitions.py`:

```python
@staticmethod
def get_available_crews():
    return [
        ...
        "Sua Nova Crew",
    ]
```

---

## 🔧 Adicionando Novas Ferramentas

### Passo 1: Criar Arquivo de Ferramenta

Crie `src/tools/suas_tools.py`:

```python
from crewai.tools import BaseTool
from pydantic import BaseModel, Field

class SuaToolInput(BaseModel):
    """Schema de entrada - DEVE ter docstring e descrições Field."""
    param1: str = Field(..., description="Para que serve este parâmetro")
    param2: int = Field(default=10, description="Opcional com valor padrão")

class SuaTool(BaseTool):
    name: str = "Nome da Sua Ferramenta"
    description: str = (
        "Descrição detalhada do que esta ferramenta faz. "
        "O agente lê isto para decidir quando usar."
    )
    args_schema: type = SuaToolInput

    def _run(self, param1: str, param2: int = 10) -> str:
        try:
            # Sua lógica aqui
            result = fazer_algo(param1, param2)
            return f"Sucesso: {result}"
        except Exception as e:
            # NUNCA lance exceção, sempre retorne string de erro
            return f"Erro: {str(e)}"
```

### Diretrizes de Ferramentas

1. **Sempre capture exceções** - Retorne strings de erro, nunca lance
2. **Docstrings descritivas** - Agentes usam estas para entender o uso
3. **Type hints obrigatórios** - Todos os parâmetros precisam de tipos
4. **Retorne strings** - Resultados narrativos, não JSON bruto

---

## ⚙️ Referência de Configuração

### Variáveis .env

```env
# Provedor LLM: gemini, openai, anthropic, ollama
LLM_PROVIDER=gemini

# Nomes de modelos (usados para agentes e memória)
LLM_MODEL_FAST=gemini-2.5-flash-lite-preview-06-17
LLM_MODEL_SMART=gemini-2.5-flash-lite-preview-06-17

# Chaves de API (apenas a que corresponde ao seu provedor)
GEMINI_API_KEY=sua-chave
OPENAI_API_KEY=sua-chave
ANTHROPIC_API_KEY=sua-chave

# Configuração de Memória
MEMORY_PROVIDER=qdrant          # qdrant (local) ou mem0 (nuvem)
MEMORY_EMBEDDING_PROVIDER=local # local, openai, ou gemini
QDRANT_HOST=qdrant              # Nome do serviço Docker
QDRANT_PORT=6333
MEMORY_PROJECT_ID=seu_projeto   # Namespace para memórias
```

### Níveis de Modelo

- **smart**: Usado para raciocínio complexo (estratégia, arquitetura)
- **fast**: Usado para tarefas rápidas (classificação, respostas simples)

---

## 🧠 Sistema de Memória

### Como Funciona

1. Todos os agentes têm acesso a `SearchMemoryTool` e `SaveMemoryTool`
2. Memórias são armazenadas no banco de dados vetorial Qdrant
3. Mem0 usa LLM para extrair fatos e embeddings para busca

### Rate Limiting

O sistema de memória tem proteção integrada:
- Máximo 50 chamadas/minuto
- 3 tentativas com backoff exponencial
- Degradação graciosa (continua sem memória se indisponível)

### Escopo de Memória

Todas as memórias são escopadas para `MEMORY_PROJECT_ID`. Altere isto para isolar diferentes projetos.

---

## 🤖 Diretrizes para Agentes de IA

### Para Agentes de IA Trabalhando Neste Código

> **LEIA ANTES DE FAZER ALTERAÇÕES**

1. **Carregue Conhecimento Primeiro**
   - Leia `src/knowledge/standards/*.md` antes de escrever código
   - Estes são A LEI para estilo de código e padrões

2. **Nunca Hardcode**
   - Use `Config.get_llm_config()` para configurações LLM
   - Use `Config.get_mem0_config()` para configurações de memória
   - Use variáveis de ambiente para segredos

3. **Tratamento de Erros**
   - Ferramentas NUNCA devem lançar exceções
   - Sempre retorne strings de erro descritivas
   - Use rate limiting para APIs externas

4. **Adicionando Agentes**
   - Crie arquivo de persona primeiro
   - Teste se o agente carrega: `AgentFactory.create_agent("nome")`
   - Adicione à crew apenas depois que a persona funcionar

5. **Testando Alterações**
   ```bash
   docker-compose restart app
   docker logs antigravity_brain --tail 50
   ```

6. **Convenção de Commit**
   ```
   feat: Adicionar nova funcionalidade
   fix: Correção de bug
   docs: Documentação
   refactor: Limpeza de código
   ```

---

## 📁 Referência de Diretórios

```
src/
├── agents/
│   ├── factory.py          # Lógica de criação de agentes
│   └── personas/           # Arquivos de personalidade de agentes
│       ├── persona-arthur-mendes.md
│       ├── persona-gus-fring.md
│       └── ... (26 agentes)
├── crews/
│   └── definitions.py      # Composições de crews
├── knowledge/
│   └── standards/          # Base de conhecimento corporativo
│       ├── docker_standards.md
│       ├── python_tool_standards.md
│       └── ... (16 padrões)
├── memory/
│   └── wrapper.py          # Mem0 + rate limiting
├── tools/
│   ├── base.py             # Ferramentas de sistema de arquivos
│   ├── evolution.py        # SpawnAgent, LearnPolicy
│   └── zabbix.py           # Ferramentas de validação Zabbix
├── app.py                  # Entrada Chainlit
├── config.py               # Hub de configuração
└── router.py               # Roteamento inteligente
```

---

## 🚀 Comandos Rápidos

```bash
# Iniciar aplicação
docker-compose up -d

# Ver logs
docker logs antigravity_brain -f

# Reiniciar após alterações
docker-compose restart app

# Reconstruir container
docker-compose build --no-cache app

# Acessar dashboard Qdrant
open http://localhost:6333/dashboard
```

---

Feito com ❤️ pela ITGuys | Última Atualização: 2026-01-07