Escopo do Projeto — Local Coding Agent (Python)

Nome sugerido:

tinycoder-agent

Objetivo: Construir um agent coding local, leve e modular, otimizado para hardware fraco usando modelos locais via Ollama.

---

Objetivos do Projeto

O agent deve conseguir:

• conversar sobre código
• editar arquivos
• gerar código
• analisar projetos
• executar comandos
• rodar testes
• corrigir erros simples
• trabalhar incrementalmente
• operar localmente sem cloud
• consumir pouca RAM

---

Limitações do Projeto

Hardware-alvo

Seu notebook:

• i5-3210M
• 16GB RAM
• Intel HD 4000

Então o projeto deve:

✅ funcionar em CPU ✅ usar modelos 0.6B–2B ✅ usar contexto pequeno ✅ carregar 1 modelo por vez ✅ usar chunking inteligente

---

Arquitetura Geral

┌────────────────────┐
│ Interface (CLI)    │
└─────────┬──────────┘
          ↓
┌────────────────────┐
│ Agent Orchestrator │
└─────────┬──────────┘
          ↓
 ┌────────┴────────┐
 ↓                 ↓
Planner         Coding Model
(granite)       (qwen)
 ↓                 ↓
 └──────┬──────────┘
        ↓
┌────────────────────┐
│ Tools System       │
├────────────────────┤
│ File Reader        │
│ File Writer        │
│ Grep Search        │
│ AST Search         │
│ Git Diff           │
│ Test Runner        │
│ Shell Runner       │
└────────────────────┘
        ↓
┌────────────────────┐
│ Memory + RAG       │
└────────────────────┘

---

Estrutura de Pastas

tinycoder-agent/
│
├── app/
│   ├── main.py
│   ├── config.py
│   ├── agent.py
│   │
│   ├── llm/
│   │   ├── ollama_client.py
│   │   ├── planner.py
│   │   ├── coder.py
│   │   └── summarizer.py
│   │
│   ├── tools/
│   │   ├── files.py
│   │   ├── grep.py
│   │   ├── shell.py
│   │   ├── git.py
│   │   ├── tests.py
│   │   ├── ast_parser.py
│   │   └── tree.py
│   │
│   ├── memory/
│   │   ├── memory.py
│   │   ├── session.py
│   │   └── embeddings.py
│   │
│   ├── prompts/
│   │   ├── planner.txt
│   │   ├── coder.txt
│   │   └── summarize.txt
│   │
│   ├── rag/
│   │   ├── chunker.py
│   │   ├── retriever.py
│   │   └── indexer.py
│   │
│   └── utils/
│       ├── logger.py
│       ├── tokenizer.py
│       └── paths.py
│
├── workspace/
│
├── tests/
│
├── requirements.txt
├── README.md
└── run.py

---

Módulos do Sistema

1. Orchestrator

Arquivo:

app/agent.py

Responsável por:

• receber input do usuário
• decidir fluxo
• chamar planner
• selecionar tools
• enviar contexto ao coder
• executar loop

---

2. LLM Layer

ollama_client.py

Wrapper do Ollama.

Funções:

generate(model, prompt)
chat(model, messages)
stream(model, messages)

---

planner.py

Modelo:

granite3.3:2b

Responsável por:

• quebrar tarefas
• gerar plano
• decidir ferramentas

Saída JSON:

{
  "steps": [
    "find login route",
    "inspect auth middleware",
    "modify token validation"
  ]
}

---

coder.py

Modelo:

qwen3:1.7b

Responsável por:

• escrever código
• editar funções
• gerar patches
• corrigir bugs

---

summarizer.py

Modelo:

qwen3:0.6b

Responsável por:

• resumir sessão
• comprimir contexto
• gerar memória persistente

---

3. Sistema de Tools

files.py

Funções:

read_file()
write_file()
append_file()
list_files()

---

grep.py

Usa:

ripgrep

Funções:

search_code()
find_symbol()

---

ast_parser.py

Usa:

ast-grep

Responsável por:

• localizar funções
• localizar classes
• refactor seguro

---

shell.py

Executa:

run_command()

Com sandbox simples.

Permitir:

• pytest
• npm test
• python scripts

Bloquear:

• rm -rf
• sudo
• reboot

---

git.py

Funções:

git_diff()
git_commit()
git_restore()

---

tests.py

Executa:

• pytest
• unittest

Captura:

• stack trace
• logs
• erros

---

4. Sistema de Memória

session.py

Memória curta:

• últimas mensagens
• últimas ações
• últimos arquivos

---

memory.py

Memória longa:

• decisões
• contexto importante
• objetivos

Persistência:

SQLite

---

embeddings.py

Opcional.

Pode usar:

• sentence-transformers pequenos
• ou embeddings fake por TF-IDF

No seu hardware: TF-IDF já funciona muito bem.

---

5. Sistema RAG

chunker.py

Divide arquivos grandes.

Estratégia:

200–400 linhas
overlap pequeno

---

retriever.py

Busca:

• funções relevantes
• arquivos relevantes
• imports relacionados

---

indexer.py

Indexa:

• nomes
• funções
• classes
• docstrings

---

Fluxo Principal

Usuário faz pedido
        ↓
Planner gera passos
        ↓
Agent seleciona tools
        ↓
Busca arquivos relevantes
        ↓
Coder recebe contexto mínimo
        ↓
Gera patch
        ↓
Executa testes
        ↓
Corrige erros
        ↓
Salva memória

---

Dependências

requirements.txt

ollama
fastapi
uvicorn
pydantic
rich
typer
pytest
gitpython
sqlite-utils
scikit-learn

---

Dependências externas

Instalar:

ripgrep

ripgrep

---

fd

fd

---

ast-grep

ast-grep

---

Interface Inicial

CLI primeiro

Mais leve e rápido.

Exemplo:

python run.py

---

Comandos

/ask
/edit
/fix
/test
/search
/context
/reset

---

MVP (v1)

O MVP deve conseguir:

✅ conversar ✅ ler arquivos ✅ editar arquivos ✅ buscar código ✅ rodar testes ✅ corrigir erro simples ✅ usar Ollama

---

v2

Adicionar:

• memória persistente
• RAG
• múltiplos modelos
• contexto inteligente
• auto-fix loop

---

v3

Adicionar:

• interface web
• websocket streaming
• autocomplete
• plugin VSCode
• multi-agent

---

Estratégia de Performance

Regras importantes

1. Nunca mandar projeto inteiro

Sempre:

• grep primeiro
• recuperar contexto mínimo

---

2. Máximo 4k contexto

Ideal:

2048–4096

---

3. Um modelo por vez

No seu hardware:

OLLAMA_MAX_LOADED_MODELS=1

---

4. Limitar loops

Máximo:

3 retries

---

Roadmap

Semana 1

• CLI
• integração Ollama
• planner
• coder
• file tools

---

Semana 2

• grep
• shell
• testes
• git diff

---

Semana 3

• memória
• RAG
• indexação

---

Semana 4

• auto-fix
• streaming
• otimização CPU

---

Resultado Final Esperado

Você terá:

✅ coding assistant local ✅ agent terminal ✅ edição de projetos ✅ debug automático básico ✅ memória local ✅ sem depender de API paga ✅ funcionando em hardware fraco

---

Inspirações

Aider

Aider

---

Open Interpreter

Open Interpreter

---

OpenDevin

OpenDevin