Baixe o código, configure o .env e instale todas as dependências com um único comando.
O que é: Clone o fork inematds do MiroFish. Este fork inclui suporte multi-LLM, KuzuDB local (sem Zep Cloud), correções de bugs e tradução para PT-BR/EN.
Por que aprender: O repositório original tem bugs e dependências de serviços pagos. O fork resolve esses problemas e é a base recomendada para uso.
# Clonar o repositório
git clone https://github.com/inematds/mirofish.git
cd mirofish
# Estrutura principal do projeto
mirofish/
├── frontend/ # Vue.js 3 + Vite
├── backend/ # Python + Flask
│ ├── data/ # KuzuDB e dados
│ ├── uploads/ # Documentos enviados
│ └── config.py # Configurações
├── docker-compose.yml # Deploy Docker
├── Dockerfile # Build da imagem
├── .env.example # Template de configuração
└── package.json # Scripts npm
O que é: O arquivo .env centraliza todas as configurações do sistema. Copie o template e edite conforme seu provedor LLM escolhido.
Por que aprender: Cada variável controla um aspecto crítico do sistema. Um .env mal configurado causa erros silenciosos ou custos inesperados.
# 1. Copiar template
cp .env.example .env
# 2. Conteúdo do .env (exemplo com Claude CLI)
# ---- Provedor LLM ----
LLM_PROVIDER=claude-cli
LLM_API_KEY= # vazio para claude-cli
LLM_MODEL_NAME= # usa padrão do CLI
LLM_BASE_URL= # não necessário
# ---- Banco de Dados ----
GRAPH_DB_PATH=./backend/data/graphdb
# ---- LLM de Boost (opcional) ----
LLM_BOOST_PROVIDER=
LLM_BOOST_API_KEY=
LLM_BOOST_MODEL_NAME=
IMPORTANTE: O .env contém API keys sensíveis. Nunca commite este arquivo no git (já está no .gitignore).
O que é: A variável LLM_PROVIDER aceita 4 valores: claude-cli, codex-cli, openai ou anthropic. Cada um configura como o sistema se comunica com o LLM.
Por que aprender: A escolha do provedor define custo, velocidade e compatibilidade. Claude CLI é sem custo; OpenAI tem melhor compatibilidade com OASIS.
# Opções de LLM_PROVIDER:
claude-cli → Usa Claude CLI local (sem API key)
codex-cli → Usa Codex CLI local (sem API key)
openai → API OpenAI (precisa de LLM_API_KEY)
anthropic → API Anthropic (precisa de LLM_API_KEY)
# Exemplo: OpenAI com GPT-4o-mini
LLM_PROVIDER=openai
LLM_API_KEY=sk-proj-abc123...
LLM_MODEL_NAME=gpt-4o-mini
LLM_BASE_URL=https://api.openai.com/v1
O que é: GRAPH_DB_PATH define onde o KuzuDB armazena o grafo de conhecimento. O padrão ./backend/data/graphdb cria o banco localmente, sem necessidade de serviços externos.
Por que aprender: O fork inematds substituiu o Zep Cloud (serviço pago) pelo KuzuDB embarcado. Isso significa zero custo de banco de dados e total privacidade dos dados.
# Configuração padrão (recomendada)
GRAPH_DB_PATH=./backend/data/graphdb
# O que mudou do original para o fork:
❌ Original: ZEP_API_KEY=z_abc123... (serviço pago)
✅ Fork: GRAPH_DB_PATH=./backend/data/graphdb (local, grátis)
# O banco é criado automaticamente na primeira execução
# Dados ficam persistidos no diretório especificado
# Para limpar: rm -rf ./backend/data/graphdb
O que é: Um único comando que instala todas as dependências: Node.js packages para o frontend e Python packages para o backend (via uv). Leva 2-5 minutos.
Por que aprender: Este comando automatiza o que seriam 5+ passos manuais. Se falhar, o erro indica qual dependência está com problema.
# Executar setup completo
npm run setup:all
# O que este comando faz internamente:
1. npm install → Dependências do frontend (Vue.js)
2. cd backend && uv sync → Dependências do backend (Python)
3. Cria ambiente virtual Python
4. Instala CAMEL-AI, KuzuDB, Flask, etc.
# Se falhar, verifique:
- Python 3.12 ativo? (python --version)
- uv instalado? (uv --version)
- Node 18+? (node --version)
O que é: Antes de rodar sua primeira simulação, passe por este checklist para garantir que tudo está configurado corretamente.
Por que aprender: 90% dos problemas são detectados nesta etapa. Melhor gastar 2 minutos verificando do que 2 horas debugando.
# Checklist de Verificação
node --version # ✅ v18+ ou v20+
python --version # ✅ 3.11.x ou 3.12.x
uv --version # ✅ instalado
cat .env # ✅ LLM_PROVIDER configurado
ls node_modules/ # ✅ existe (npm install OK)
ls backend/.venv/ # ✅ existe (uv sync OK)
# Teste rápido - iniciar em modo dev
npm run dev
# Frontend: http://localhost:3000
# Backend: http://localhost:5001
# Se ambos iniciaram sem erro → tudo pronto!