Explore as camadas técnicas do MiroFish: do frontend Vue.js ao motor de simulação OASIS, passando pelo backend Flask e pela camada de IA.
A interface do MiroFish é uma Single Page Application (SPA) construída com Vue.js 3 e o build tool Vite, com visualizações de grafos e simulações renderizadas pelo D3.js. O frontend roda na porta 3000 e se comunica com o backend via APIs REST e WebSocket.
Vue.js 3 fornece a estrutura de componentes reativos - cada parte da interface (lista de agentes, grafo de conhecimento, timeline da simulação) é um componente independente. Vite garante hot module replacement (HMR) para desenvolvimento rápido. D3.js renderiza visualizações interativas: o grafo de conhecimento como rede de nós e arestas, a timeline da simulação como diagrama temporal e os sentimentos como heatmap.
O frontend é completamente desacoplado do backend - qualquer interface pode consumir as APIs. Isso significa que é possível criar dashboards customizados, integrações com ferramentas de BI ou até interfaces de linha de comando para automatizar simulações. A porta padrão 3000 pode ser alterada no arquivo de configuração do Vite.
Para desenvolvimento, rode o frontend com npm run dev que ativa o HMR do Vite. Para produção, npm run build gera arquivos estáticos otimizados que podem ser servidos por qualquer servidor web.
O backend é um servidor Python com Flask rodando na porta 5001. Ele é responsável por toda a lógica de negócio: orquestração de simulações, gerenciamento do grafo de conhecimento, comunicação com LLMs e persistência de dados.
O backend expõe APIs REST para operações CRUD (criar/ler/atualizar/deletar simulações) e usa WebSocket para comunicação em tempo real durante simulações ativas. As principais rotas incluem: /api/simulation (gerenciamento de simulações), /api/graphrag (operações no grafo de conhecimento) e /api/agents (interação com agentes individuais).
O OASIS (Open Agent Social Interaction Simulations) é o motor de simulação social desenvolvido pelo CAMEL-AI que o MiroFish utiliza. Ele define 23 ações sociais que os agentes podem executar em ambientes que simulam Twitter e Reddit simultaneamente.
As 23 ações sociais incluem operações como: postar conteúdo original, responder a posts, curtir, compartilhar, seguir/deixar de seguir usuários, criar threads, votar em enquetes e mais. Cada agente, a cada turno da simulação, observa seu feed e decide qual ação executar baseado na sua personalidade e no contexto. O OASIS suporta simulação simultânea em ambientes tipo Twitter (posts curtos, retweets) e Reddit (threads, upvotes/downvotes, subreddits).
O OASIS foi desenvolvido pelo CAMEL-AI (Communicative Agents for Machine Learning), um framework open-source para criação de sistemas multiagente. A simulação simultânea em dois ambientes (Twitter + Reddit) permite observar como a mesma população se comporta de forma diferente em contextos distintos - mensagens curtas vs discussões longas.
Ao configurar uma simulação, considere qual ambiente é mais relevante para seu cenário. Notícias e reações rápidas funcionam melhor no ambiente Twitter. Discussões aprofundadas e análises são mais ricas no ambiente Reddit. Simular ambos oferece a visão mais completa.
Os LLMs são o "cérebro" de cada agente no MiroFish. Cada vez que um agente precisa tomar uma decisão, um prompt é construído com sua personalidade, memória e contexto atual, e enviado ao LLM para gerar uma resposta.
O prompt de cada agente é composto por: (1) System prompt com a persona do agente (personalidade, valores, estilo); (2) Contexto do grafo de conhecimento relevante para a interação atual; (3) Memória das últimas interações; (4) O conteúdo que o agente está respondendo; (5) Instruções sobre as ações disponíveis. O LLM retorna tanto o conteúdo (texto do post/comentário) quanto a ação escolhida (postar, curtir, compartilhar, etc.).
Persona + contexto do grafo + memória recente + conteúdo atual + ações disponíveis são combinados em um prompt.
O prompt é enviado ao LLM configurado (DeepSeek, Gemini, Qwen, etc.) via API.
A resposta é parseada para extrair a ação escolhida e o conteúdo gerado pelo agente.
A ação é executada no ambiente simulado e a interação é salva na memória do agente.
O MiroFish usa uma combinação pragmática de tecnologias de armazenamento: SQLite para dados estruturados, JSON para configurações e resultados, e o filesystem para logs e artefatos gerados durante simulações.
SQLite: Armazena metadados de simulações, perfis de agentes e dados de interação em um banco relacional embarcado. Zero configuração, perfeito para uso local. JSON: Configurações de simulação, resultados de relatórios e exportações são armazenados em JSON para fácil leitura e portabilidade. Filesystem: Logs detalhados de cada turno da simulação, grafos de conhecimento exportados e artefatos visuais são salvos em diretórios organizados por simulação.
O MiroFish pode ser implantado de duas formas: via Docker Compose (recomendado para produção e compartilhamento) ou via scripts npm (recomendado para desenvolvimento). Ambos os métodos orquestram frontend, backend e banco de dados.
Docker Compose: Um único docker-compose up sobe todos os serviços (frontend na porta 3000, backend na porta 5001, banco de dados). Ideal para ambientes de produção e para compartilhar o setup com equipes. Scripts npm: O npm run dev inicia frontend e backend simultaneamente com hot reload. Ideal para desenvolvimento e debug.
Configure as variáveis de ambiente antes de fazer deploy. As mais importantes são: as API keys dos LLMs que você pretende usar (DEEPSEEK_API_KEY, GEMINI_API_KEY, etc.), a porta do backend (FLASK_PORT) e o diretório de dados (DATA_DIR). Nunca comite API keys no repositório - use arquivo .env.
Os requisitos mínimos de hardware são: 4GB RAM (8GB recomendado), 2 cores de CPU e 5GB de espaço em disco. O maior consumo de recursos vem das chamadas paralelas aos LLMs durante a simulação. Se rodar LLMs locais (como Ollama), considere 16GB+ RAM e GPU dedicada.