Forks inematds e MiroFish-Offline, correções críticas, Docker customizado e guia de fork
O fork inematds é a versão mais extensivamente modificada do BettaFish, servindo como base para o ecossistema MiroFish. As mudanças principais: (1) Substituição do Zep Cloud por KuzuDB - toda a camada de memória reescrita para usar grafo embutido local, eliminando custos recorrentes e dependência de internet. (2) Multi-LLM via LiteLLM - router inteligente que direciona chamadas para OpenAI, Anthropic, Ollama, Groq ou qualquer provedor OpenAI-compatible, com fallback automático entre provedores. (3) Tradução PT-BR completa - todos os prompts do sistema, mensagens de interface e templates de relatório traduzidos para português brasileiro mantendo qualidade técnica. (4) Stop/resume para builds Docker - funcionalidade que persiste o estado de builds longas, permitindo interromper e retomar sem recomeçar do zero.
O fork inematds é a base de tudo no MiroFish. Entender suas mudanças permite: contribuir com melhorias, resolver conflitos de merge com o upstream, adaptar funcionalidades futuras, e tomar decisões informadas sobre quais mudanças adotar de volta do upstream.
O MiroFish-Offline é um fork que garante operação 100% local, sem nenhuma chamada a serviços externos. A stack: (1) Ollama para inferência LLM local - suporta Llama 3.1 8B/70B, Mistral 7B, Qwen2.5, e qualquer modelo GGUF. Performance: ~15 tokens/s com Llama 3.1 8B em GPU RTX 3060. (2) Neo4j Community Edition para grafo de conhecimento - substitui tanto o Zep Cloud quanto o KuzuDB com um grafo mais robusto, com UI de visualização nativa. (3) sentence-transformers locais para embeddings - modelo all-MiniLM-L6-v2 (22M params, 384 dims) rodando localmente. (4) Crawling via cache local apenas - sem web crawling ativo, opera sobre datasets pré-coletados. Requisitos mínimos: 16GB RAM, 8GB VRAM (GPU), 50GB disco.
O MiroFish-Offline atende cenários onde dados não podem sair da rede local: organizações governamentais, militares, financeiras com compliance rígido, ou simplesmente pesquisadores sem orçamento para APIs cloud. É a versão mais autônoma e privada do ecossistema.
O MIGRATION-GUIDE.md documenta 7 bugs críticos encontrados no BettaFish upstream e corrigidos nos forks: (1) Race condition no shared log - múltiplos agentes escrevendo simultaneamente causavam corrupção de dados; fix via asyncio.Lock(). (2) Memory leak no KuzuDB connection pool - conexões não eram fechadas em exceções; fix via context manager with/as. (3) UTF-8 encoding quebrado - prompts PT-BR com acentos causavam UnicodeDecodeError; fix via explicit encoding='utf-8' em todos os file opens. (4) Timeout silencioso no crawling - requests sem timeout travavam o pipeline indefinidamente; fix via timeout=30s com retry exponencial. (5) Duplicação de embeddings - documentos re-indexados geravam embeddings duplicados; fix via hash-based deduplication. (6) Formato de datas inconsistente - agentes usavam formatos diferentes (ISO vs US vs BR); fix via normalização para ISO 8601. (7) Token overflow - prompts para modelos com context window < 8K excediam o limite; fix via truncamento adaptativo que preserva as partes mais relevantes.
Esses 7 bugs são armadilhas para qualquer pessoa que use o upstream diretamente ou crie um fork sem o MIGRATION-GUIDE. Cada bug pode causar falhas silenciosas (dados corrompidos sem erro visível) ou crashes intermitentes (difíceis de reproduzir). Conhecê-los economiza horas de debug.
Os forks adicionam 4 endpoints REST que o upstream não possui, todos no path /api/v1/simulation/{id}/: (1) PATCH /rename - aceita {"name": "novo_nome"}, renomeia a simulação no banco e nos logs sem interromper execução, útil para organização. (2) POST /pause - serializa o estado completo (agentes, memórias, round atual, feeds) para disco via pickle + JSON, retorna {"status": "paused", "snapshot_path": "/data/snapshots/..."}. (3) POST /resume - deserializa o snapshot e continua a simulação exatamente do ponto onde parou, validando integridade do snapshot antes de resumir. (4) POST /snapshot - cria um checkpoint sem pausar, permitindo "branch" a simulação: rodar a mesma simulação a partir do mesmo ponto com parâmetros diferentes.
Simulações longas (horas ou dias) precisam de controle operacional. Pausar para reduzir custos de API durante horários caros, retomar após manutenção de servidor, e snapshots para experimentar "what-if" a partir do mesmo ponto são funcionalidades essenciais para uso profissional.
A configuração Docker customizada dos forks consolida a stack em um setup otimizado para produção: (1) Multi-stage Dockerfile - stage 1 (builder) instala dependências e compila; stage 2 (runtime) copia apenas os artefatos necessários, resultando em imagem final de ~500MB vs ~2GB da abordagem naive. (2) docker-compose.yml com Traefik - reverse proxy que auto-descobre serviços, faz load balancing, e gerencia SSL automaticamente via Let's Encrypt com renovação programada. (3) Persistent volumes - /data/simulations e /data/kuzudb montados como named volumes, sobrevivem a container restarts e rebuilds. (4) Health checks - endpoints /health para API e KuzuDB com auto-restart via Docker restart policy. (5) Resource limits - memory limits e CPU quotas para prevenir que uma simulação grande derrube o servidor.
Deploy em produção requer containerização robusta. A configuração com Traefik e SSL automático permite deploy em uma VPS (DigitalOcean, Hetzner, etc.) com HTTPS funcional em minutos, sem configuração manual de Nginx ou certificados. É a forma mais rápida de ir de "funciona no meu laptop" para "rodando em produção com SSL".
Guia passo-a-passo para criar um fork customizado: (1) Fork do repositório inematds no GitHub (não do upstream - o inematds já inclui as 7 correções e melhorias). (2) Clone local e setup de desenvolvimento: python -m venv .venv, pip install -e ".[dev]", pre-commit install. (3) Pontos de extensão documentados: engines/ para novos agentes, models/ para novos modelos de sentimento, providers/ para novos provedores LLM, prompts/ para templates customizados. Cada ponto de extensão tem uma interface abstrata (ABC) que deve ser implementada. (4) Testes: pytest tests/ com fixtures que mockam chamadas LLM para testes rápidos e determinísticos. (5) Sincronização com upstream: git remote add upstream, git fetch upstream, git rebase upstream/main periodicamente, resolvendo conflitos nos pontos de divergência documentados.
A capacidade de criar e manter um fork próprio transforma o MiroFish de uma ferramenta pronta em uma plataforma extensível. Organizações podem ter forks com customizações específicas (novos engines, novos modelos, integrações proprietárias) enquanto se beneficiam de melhorias do upstream via rebases periódicos.