🔧 Instalação Passo a Passo

O que é: Os requisitos mínimos de hardware e sistema operacional para rodar o MiroFish: 8GB de RAM, processador com 4+ cores, e suporte a Linux, macOS ou Windows (via WSL2).

Por que aprender: Tentar rodar em hardware insuficiente causa simulações lentas, falhas de memória e travamentos. Validar antes de instalar evita frustração.

Conceitos-chave: RAM mínima 8GB, 4+ cores CPU, Linux/macOS/Windows WSL2, espaço em disco 10GB+, GPU não obrigatória.

O que é: Node.js 18 ou superior é necessário para o frontend Vue.js e scripts de build. A instalação via nvm (Node Version Manager) permite gerenciar múltiplas versões sem conflito.

Por que aprender: O frontend e os scripts npm dependem do Node.js. Usar nvm evita conflitos com versões do sistema e facilita atualizações futuras.

Conceitos-chave: nvm install 20, node --version, npm --version, LTS vs Current, gerenciamento de versões.

O que é: Python 3.11 ou 3.12 é obrigatório. Python 3.13+ NÃO é compatível com algumas dependências do OASIS/CAMEL-AI. Use pyenv para instalar a versão correta.

Por que aprender: A versão errada do Python é a causa #1 de falhas na instalação. Dependências como CAMEL-AI não suportam Python 3.13+.

Conceitos-chave: pyenv install 3.12.7, pyenv local 3.12.7, python --version, incompatibilidade 3.13+, CAMEL-AI.

O que é: uv é um gerenciador de pacotes Python ultrarrápido (escrito em Rust) que substitui pip+venv. Instalação via curl -LsSf https://astral.sh/uv/install.sh | sh.

Por que aprender: O fork inematds usa uv para gerenciar o ambiente Python. É 10-100x mais rápido que pip e resolve dependências com mais precisão.

Conceitos-chave: uv pip install, uv venv, uv sync, Astral, substituição do pip, resolução de dependências.

O que é: Docker é necessário para deploy em produção. Docker Compose orquestra os containers (app + Traefik). Verificar com docker --version e docker compose version.

Por que aprender: Docker é o método recomendado para deploy. Sem ele, você precisaria configurar manualmente Nginx, SSL e processos de background.

Conceitos-chave: Docker Engine, Docker Compose v2, containers, imagens, docker compose up.

O que é: Você precisa de acesso a um LLM. Opções: Claude CLI (usa assinatura existente, sem API key), ou API keys da OpenAI/Anthropic (plataformas de desenvolvedor).

Por que aprender: Sem acesso a um LLM, nada funciona. Claude CLI é a opção mais barata ($0 extra), mas API keys dão mais controle sobre modelos e custos.

Conceitos-chave: API keys, Claude CLI, platform.openai.com, console.anthropic.com, billing, rate limits.

O que é: O comando git clone https://github.com/inematds/mirofish.git baixa o fork com todas as correções, suporte multi-LLM e KuzuDB local já integrados.

Por que aprender: O fork inematds é a versão recomendada. O original tem bugs e dependências de serviços pagos (Zep Cloud) que foram eliminados neste fork.

Conceitos-chave: git clone, fork inematds, estrutura de diretórios, frontend/, backend/, docker-compose.yml.

O que é: O arquivo .env contém todas as configurações do sistema. Copie de .env.example e edite: LLM_PROVIDER, LLM_API_KEY, LLM_MODEL_NAME, LLM_BASE_URL, GRAPH_DB_PATH.

Por que aprender: O .env é o coração da configuração. Um valor errado pode causar falhas silenciosas ou custos inesperados com API.

Conceitos-chave: cp .env.example .env, variáveis de ambiente, LLM_PROVIDER, LLM_API_KEY, GRAPH_DB_PATH.

O que é: A variável LLM_PROVIDER define qual backend de IA usar: claude-cli (sem custo), codex-cli (sem custo), openai (API paga) ou anthropic (API paga).

Por que aprender: A escolha do provedor afeta custo, velocidade e qualidade. Claude CLI é ideal para testes; APIs pagas são melhores para produção.

Conceitos-chave: claude-cli, codex-cli, openai, anthropic, LLM_PROVIDER, trade-offs custo vs qualidade.

O que é: GRAPH_DB_PATH=./backend/data/graphdb configura o KuzuDB local para armazenar o grafo de conhecimento. O fork eliminou a dependência do Zep Cloud.

Por que aprender: Sem Zep Cloud, tudo roda localmente sem custos adicionais. O caminho do banco precisa ter permissões de escrita e espaço em disco.

Conceitos-chave: KuzuDB, banco de grafos embarcado, GRAPH_DB_PATH, sem Zep, armazenamento local.

O que é: O comando npm run setup:all instala todas as dependências de uma vez: Node.js packages (frontend) e Python packages (backend via uv). Um único comando para tudo.

Por que aprender: Este comando automatiza a instalação completa. Se falhar, geralmente indica problema com a versão do Python ou Node.js.

Conceitos-chave: npm run setup:all, dependências Node, dependências Python, uv sync, package.json scripts.

O que é: Checklist para confirmar que tudo está pronto: Node 18+ OK, Python 3.11-3.12 OK, .env configurado, npm run setup:all sem erros, backend inicia sem erros.

Por que aprender: Verificar antes de rodar a primeira simulação evita erros confusos. A maioria dos problemas são detectados nesta etapa.

Conceitos-chave: Checklist pré-execução, node --version, python --version, npm run dev, logs de inicialização.

O que é: Claude CLI usa sua assinatura Claude existente (Pro/Team) para fazer chamadas LLM. Configure LLM_PROVIDER=claude-cli no .env. Sem necessidade de API key.

Por que aprender: É a opção mais barata ($0 de custo extra) e mais simples. Ideal para testes e simulações pequenas (< 40 rodadas).

Conceitos-chave: LLM_PROVIDER=claude-cli, assinatura Pro, sem API key, rate limits da CLI, stdin para prompts longos.

O que é: Codex CLI é uma alternativa similar ao Claude CLI que usa assinatura Codex existente. Configure LLM_PROVIDER=codex-cli no .env.

Por que aprender: Oferece uma segunda opção sem custo de API. Útil quando Claude CLI atinge rate limits ou como backup.

Conceitos-chave: LLM_PROVIDER=codex-cli, assinatura Codex, alternativa a Claude CLI, mesma interface de uso.

O que é: Use a API da OpenAI com GPT-4o ou GPT-4o-mini. Configure LLM_PROVIDER=openai, LLM_API_KEY=sk-..., e LLM_MODEL_NAME=gpt-4o-mini.

Por que aprender: API da OpenAI é a opção mais compatível com OASIS (que requer formato OpenAI-compatible). GPT-4o-mini é excelente custo-benefício.

Conceitos-chave: LLM_API_KEY=sk-..., gpt-4o-mini, gpt-4o, platform.openai.com, custo por token, rate limits.

O que é: Use a API da Anthropic diretamente com Claude Sonnet ou Opus. Configure LLM_PROVIDER=anthropic, LLM_API_KEY=sk-ant-..., LLM_MODEL_NAME=claude-sonnet-4-20250514.

Por que aprender: A API Anthropic oferece os modelos Claude mais recentes com controle fino de parâmetros. Ideal para simulações que exigem alta qualidade de raciocínio.

Conceitos-chave: LLM_PROVIDER=anthropic, Claude Sonnet, Claude Opus, console.anthropic.com, custo por token.

O que é: LLM_BOOST é um segundo provedor LLM opcional usado para simulações OASIS em massa. Permite usar um modelo mais barato para as rodadas de simulação enquanto o principal faz análise.

Por que aprender: Em simulações com muitos agentes e rodadas, o custo de API pode explodir. O LLM_BOOST permite otimizar custo sem sacrificar qualidade da análise.

Conceitos-chave: LLM_BOOST, dual-LLM, modelo principal vs boost, otimização de custos, simulações em massa.

O que é: Tabela de custos por simulação: Claude CLI $0 extra, GPT-4o-mini ~$1-5, GPT-4o ~$10-50, Claude Opus ~$50-100. Simulações grandes com modelos caros podem chegar a $1-10K.

Por que aprender: Sem entender os custos, é fácil gastar centenas de dólares em uma única simulação. Começar com CLI/mini e escalar gradualmente é a estratégia correta.

Conceitos-chave: Custo por token, custo por simulação, Claude CLI $0, GPT-4o-mini mais barato, escalar gradualmente.

O que é: O docker-compose.yml define os serviços: app (MiroFish na porta 5001) e traefik (proxy reverso com SSL). Configura redes, volumes e variáveis de ambiente.

Por que aprender: Entender o docker-compose.yml é essencial para customizar portas, volumes, domínios e configurações de SSL para seu ambiente.

Conceitos-chave: services, volumes, networks, ports, environment, depends_on, labels Traefik.

O que é: O Dockerfile usa build multi-stage: node:20-bookworm-slim para o frontend e python:3.11-slim para o backend. Resultado: imagem otimizada com ambos os runtimes.

Por que aprender: O build multi-stage mantém a imagem final pequena. Entender as stages ajuda a debugar problemas de build e customizar o processo.

Conceitos-chave: Multi-stage build, node:20-bookworm-slim, python:3.11-slim, COPY --from, otimização de camadas.

O que é: Volumes Docker montam diretórios do host: uploads/ (documentos), data/ (banco de dados), ~/.claude e ~/.local/share/claude (configurações do Claude CLI).

Por que aprender: Sem montar os volumes do Claude CLI, o container não consegue autenticar. Sem montar data/, você perde o banco de dados ao recriar o container.

Conceitos-chave: Docker volumes, bind mounts, persistência de dados, ~/.claude, ~/.local/share/claude, permissões.

O que é: Traefik é um proxy reverso que gerencia SSL automaticamente via Let's Encrypt. Configura-se com labels no docker-compose.yml apontando para seu domínio (ex: synth.scty.org).

Por que aprender: Para deploy em produção, HTTPS é obrigatório. Traefik automatiza a renovação de certificados e o roteamento de tráfego.

Conceitos-chave: Traefik, Let's Encrypt, certificados SSL, proxy reverso, labels, acme.json, domínio customizado.

O que é: O comando docker compose up -d --build constrói a imagem e sobe os containers em background. O primeiro build leva 5-10 minutos; os seguintes são rápidos.

Por que aprender: É o comando que coloca tudo no ar. Os flags -d (detached) e --build (rebuild) são essenciais para operação correta.

Conceitos-chave: docker compose up -d --build, primeiro build, cache de camadas, restart policy, health checks.

O que é: Use docker compose logs -f para acompanhar logs em tempo real. Filtre por serviço: docker compose logs -f app. Verifique erros de inicialização e status do backend.

Por que aprender: Os logs são sua principal ferramenta de diagnóstico. Erros de configuração, falhas de API e problemas de memória aparecem aqui primeiro.

Conceitos-chave: docker compose logs -f, filtrar por serviço, docker compose ps, docker compose restart, diagnóstico.

O que é: Acesse http://localhost:3000 para a interface do MiroFish. Em produção, use o domínio configurado com Traefik (ex: https://synth.scty.org). A interface Vue.js carrega automaticamente.

Por que aprender: A interface web é onde você interage com o sistema. Se não carregar, verifique se o frontend está rodando e se as portas estão corretas.

Conceitos-chave: localhost:3000, domínio customizado, Vue.js frontend, proxy para backend:5001, CORS.

O que é: Faça upload de documentos nos formatos PDF, Markdown (.md) ou texto (.txt). Os documentos são a base de conhecimento para a simulação - quanto mais relevantes, melhor o resultado.

Por que aprender: A qualidade do input determina a qualidade do output. Documentos devem conter contexto rico sobre o tema a ser simulado.

Conceitos-chave: Formatos aceitos, qualidade do conteúdo, tamanho dos documentos, diretório uploads/, pré-processamento.

O que é: Após o upload, o sistema extrai entidades (pessoas, organizações, conceitos) e relações dos documentos usando o LLM, construindo o grafo de conhecimento no KuzuDB.

Por que aprender: O grafo é a fundação da simulação. Acompanhar a construção ajuda a identificar se o conteúdo do documento está sendo bem processado.

Conceitos-chave: Extração de entidades, relações, KuzuDB, build_graph.py, nós e arestas, qualidade do grafo.

O que é: Configure número de agentes e rodadas de simulação. IMPORTANTE: use menos de 40 rodadas para testes! Cada rodada multiplica chamadas ao LLM por número de agentes.

Por que aprender: Configurar muitas rodadas com muitos agentes pode custar centenas de dólares e levar horas. Começar pequeno (5 agentes, 10 rodadas) é essencial.

Conceitos-chave: Número de agentes, rodadas (< 40!), custo = agentes x rodadas x tokens, escala gradual, teste pequeno primeiro.

O que é: O frontend faz polling de status a cada 1 segundo, mostrando progresso da simulação: rodada atual, ações dos agentes e status geral (running/completed/failed).

Por que aprender: O acompanhamento em tempo real ajuda a detectar problemas cedo (como falhas de API) e estimar tempo restante da simulação.

Conceitos-chave: Polling 1s, status da simulação, progresso por rodada, detecção de erros, tempo estimado.

O que é: Ao final da simulação, um relatório é gerado com seções de análise, insights emergentes, tendências identificadas e comportamentos dos agentes. Navegue pelas seções para explorar.

Por que aprender: O relatório é o produto final de toda a simulação. Saber interpretar cada seção maximiza o valor extraído do processo.

Conceitos-chave: Relatório de simulação, seções de análise, insights emergentes, tendências, exportação de dados.

O que é: O original tem funções ausentes em config.py que impedem o backend de iniciar. O fork inematds já corrigiu isso adicionando as funções faltantes.

Por que aprender: Se você está usando o original (não recomendado), este é o primeiro erro que vai encontrar. Saber a causa economiza horas de debug.

Conceitos-chave: config.py, funções ausentes, MIGRATION-GUIDE.md, fork vs original, correções aplicadas.

O que é: Claude CLI falha com prompts muito longos passados por argumento de linha de comando. A solução é usar stdin (pipe) para enviar o prompt, evitando limites do shell.

Por que aprender: Este é um problema sutil que só aparece em simulações reais com contexto rico. A solução via stdin já está implementada no fork.

Conceitos-chave: Limite de argumentos do shell, stdin vs args, echo prompt | claude, limites do OS, ARG_MAX.

O que é: Simulações lentas/caras geralmente significam muitas rodadas ou modelo LLM caro demais. Solução: limitar rodadas (< 40), usar GPT-4o-mini ou Claude CLI, reduzir agentes.

Por que aprender: Otimizar custo/velocidade é essencial para iteração rápida. Comece pequeno, valide, e só então escale.

Conceitos-chave: Rodadas < 40, LLM mais barato para testes, escala gradual, custo = agentes x rodadas, LLM_BOOST.

O que é: Para usar Claude CLI dentro do Docker, monte os volumes ~/.claude e ~/.local/share/claude do host no container. Sem isso, o Claude CLI não consegue autenticar.

Por que aprender: Este é um dos problemas mais reportados. O container Docker não tem acesso às credenciais do host por padrão.

Conceitos-chave: Volumes Docker, ~/.claude:/root/.claude, ~/.local/share/claude, autenticação, bind mounts.

O que é: O código original tinha importação circular em build_graph.py que causava ImportError na inicialização. O fork corrigiu com lazy import (importação dentro da função).

Por que aprender: Importação circular é um erro Python comum em projetos grandes. A técnica de lazy import é a solução padrão.

Conceitos-chave: Importação circular, ImportError, lazy import, build_graph.py, dependências cíclicas.

O que é: Tabela de referência rápida: Problema → Causa → Solução. Cobre os erros mais frequentes: versão Python errada, .env mal configurado, porta em uso, falta de memória, etc.

Por que aprender: Ter uma referência rápida economiza horas de debug. A maioria dos problemas são os mesmos para todos os usuários.

Conceitos-chave: Diagnóstico rápido, erros comuns, Python 3.13+, porta 5001 em uso, ENOMEM, .env faltando.