abm-ks

v0.1.1

Published

5 days ago

Agent-Based Modeling Knowledge System - Framework de agentes especializados para desenvolvimento de modelos baseados em agentes (ABM)

🤖 ABM-KS (Agent-Based Modeling Knowledge System)

Framework de agentes especializados para desenvolvimento de modelos baseados em agentes (ABM)

📋 Índice

🎯 O que é ABM-KS?

ABM-KS é um sistema de conhecimento baseado em agentes que auxilia pesquisadores e desenvolvedores na criação de modelos de simulação baseados em agentes (Agent-Based Models).

O sistema fornece:

Agentes especializados que guiam cada etapa do desenvolvimento
Workflows estruturados seguindo melhores práticas (ODD Protocol)
Templates prontos para começar rapidamente
Documentação automatizada em formato científico

Para quem é?

🔬 Pesquisadores desenvolvendo modelos para publicação
🎓 Estudantes aprendendo modelagem baseada em agentes
💼 Profissionais criando simulações para tomada de decisão
👥 Equipes que precisam de processo estruturado

✨ Características

🤖 18 Agentes Especializados

| Equipe | Agentes | Função | |--------|---------|--------| | Core | 1 | Coordenação geral | | ABM Development | 7 | Design, código, testes | | Brainstorming | 5 | Ideação e planejamento | | Documentation | 5 | Escrita acadêmica |

📊 27 Workflows Guiados

Fase 0: Brainstorming e planejamento
Fase 1: Conceitualização do modelo
Fase 2: Design de entidades e comportamentos
Fase 3: Implementação e testes
Fase 4: Documentação ODD e publicação

📚 6 Templates Prontos

| Modelo | Python/Mesa | NetLogo | |--------|-------------|---------| | Predator-Prey | ✅ | ✅ | | SIR Epidemic | ✅ | ✅ | | Schelling Segregation | ✅ | ✅ |

🧪 331 Testes Automatizados

Validação de estrutura
Validação de YAML
Testes de integração
Testes end-to-end

🚀 Instalação Rápida

Pré-requisitos

Node.js 18+ (recomendado: 20 LTS)
IDE com suporte a Markdown (VS Code, Cursor, etc.)

Instalação via NPX

npx abm-ks install

Instalação Manual

# Clone o repositório
git clone https://github.com/muriloms/abm-ks.git

# Entre no diretório
cd abm-ks

# Instale dependências
npm install

# Execute o instalador
npm run install-system

Seleção de Equipes

Durante a instalação, você pode escolher quais equipes instalar:

╔══════════════════════════════════════════════════════════════╗
║           🤖 ABM-KS Team Selection                           ║
╠══════════════════════════════════════════════════════════════╣
║  [✓] 🤖 ABM-KS Core                    [Required]            ║
║  [✓] 🔬 ABM Development Team           [Required]            ║
║  [ ] 🧠 Brainstorming Team             [Optional]            ║
║  [ ] 📖 Documentation Team             [Optional]            ║
╚══════════════════════════════════════════════════════════════╝

🎮 Primeiros Passos

1. Iniciar um Novo Projeto

*init

O sistema irá guiá-lo através de 7 perguntas para configurar seu projeto.

2. Usar um Template (Recomendado para Iniciantes)

*list-models
*use-template predator-prey python

3. Verificar Status

*status

4. Obter Ajuda

*help
*help commands
*help workflows

🏗️ Arquitetura

abm-ks/
├── src/
│   ├── core/                    # Módulo principal
│   │   ├── agents/              # Agente master
│   │   └── workflows/           # Workflows core (init, status, help)
│   │
│   └── modules/
│       ├── abm/                 # 🔬 Equipe de Desenvolvimento
│       │   ├── agents/          # 7 agentes especializados
│       │   ├── workflows/       # 11 workflows (4 fases)
│       │   ├── templates/       # 6 templates de modelo
│       │   └── library/         # Sistema de biblioteca
│       │
│       ├── brainstorm/          # 🧠 Equipe de Brainstorming
│       │   ├── agents/          # 5 agentes
│       │   └── workflows/       # 5 workflows
│       │
│       └── documentation/       # 📖 Equipe de Documentação
│           ├── agents/          # 5 agentes
│           └── workflows/       # 5 workflows
│
├── docs/                        # Documentação
│   ├── guides/                  # Guias do usuário
│   └── reference/               # Referência rápida
│
├── tests/                       # Testes automatizados
│   ├── validation/              # Validação YAML
│   ├── integration/             # Testes de integração
│   └── e2e/                     # Testes end-to-end
│
└── tools/                       # Ferramentas
    ├── cli/                     # Interface de linha de comando
    └── installer/               # Sistema de instalação

👥 Equipes de Agentes

🤖 Core (Obrigatório)

| Agente | Função | |--------|--------| | ABM Master | Coordena todo o processo de desenvolvimento |

🔬 ABM Development (Obrigatório)

| Agente | Emoji | Especialidade | |--------|-------|---------------| | Model Designer | 🎨 | Arquitetura conceitual do modelo | | Simulation Architect | 🏗️ | Estrutura técnica e padrões | | Python Developer | 🐍 | Implementação em Python/Mesa | | NetLogo Developer | 🔷 | Implementação em NetLogo | | C++ Developer | ⚡ | Implementação em C++ (alta performance) | | ODD Writer | 📝 | Documentação no protocolo ODD | | Experiment Designer | 🧪 | Design de experimentos |

🧠 Brainstorming Team (Opcional)

| Agente | Emoji | Função | |--------|-------|--------| | Facilitador | 🎯 | Coordena sessões de brainstorming | | Pesquisador | 📚 | Busca literatura e modelos existentes | | Crítico | 🔍 | Questiona suposições | | Visionário | 💡 | Propõe ideias criativas | | Sintetizador | 📝 | Consolida discussões em documentos |

📖 Documentation Team (Opcional)

| Agente | Emoji | Função | |--------|-------|--------| | Editor Científico | 🎓 | Escrita acadêmica | | Documentador Técnico | 📋 | Manuais e guias | | Analista de Dados | 📊 | Protocolos de coleta e análise | | Revisor | ✅ | Controle de qualidade | | Comunicador | 📢 | Adaptação para públicos diversos |

🔄 Workflows

Fase 0: Brainstorming (Equipe Brainstorm)

| Comando | Workflow | Descrição | |---------|----------|-----------| | *problem-definition | Definição do Problema | Define e delimita o problema | | *literature-review | Revisão de Literatura | Revisa modelos existentes | | *hypothesis-generation | Geração de Hipóteses | Gera hipóteses testáveis | | *model-scoping | Escopo do Modelo | Define limites do modelo | | *ideation-session | Sessão de Ideação | Brainstorming estruturado |

Fase 1: Conceitualização

| Comando | Workflow | Descrição | |---------|----------|-----------| | *model-brief | Model Brief | Cria documento de visão | | *patterns | Pattern Identification | Identifica padrões alvo |

Fase 2: Design

| Comando | Workflow | Descrição | |---------|----------|-----------| | *entities | Entity Design | Define agentes e entidades | | *behaviors | Behavior Rules | Especifica comportamentos | | *environment | Environment Setup | Configura ambiente | | *scheduling | Process Scheduling | Define ordem de execução |

Fase 3: Implementação

| Comando | Workflow | Descrição | |---------|----------|-----------| | *generate-code | Code Generation | Gera código do modelo | | *test-model | Model Testing | Testa e valida modelo | | *experiments | Experiment Setup | Configura experimentos |

Fase 4: Documentação

| Comando | Workflow | Descrição | |---------|----------|-----------| | *generate-odd | Generate ODD | Cria documentação ODD | | *generate-readme | README Generation | Gera README do projeto | | *academic-paper | Artigo Acadêmico | Gera draft de paper | | *technical-manual | Manual Técnico | Cria manual de execução |

📦 Templates de Modelos

Python/Mesa

*use-template predator-prey python
*use-template sir-epidemic python
*use-template schelling python

NetLogo

*use-template predator-prey netlogo
*use-template sir-epidemic netlogo
*use-template schelling netlogo

Listar Templates Disponíveis

*list-models
*browse-library

⌨️ Comandos

Comandos Essenciais

| Comando | Descrição | |---------|-----------| | *init | Inicializa novo projeto | | *status | Mostra progresso atual | | *help | Exibe ajuda geral | | *help [topic] | Ajuda sobre tópico específico |

Comandos de Biblioteca

| Comando | Descrição | |---------|-----------| | *list-models | Lista modelos disponíveis | | *use-template | Usa template de modelo | | *browse-library | Navega pela biblioteca |

Invocar Agentes

| Comando | Agente | |---------|--------| | *agent model-designer | Model Designer | | *agent python-dev | Python Developer | | *agent odd-writer | ODD Writer | | *facilitator | Facilitador (Brainstorm) | | *scientific-editor | Editor Científico |

📚 Documentação

Guias

Getting Started - Primeiros passos
ABM Concepts - Conceitos de ABM

Referência

Quick Reference - Cartão de referência rápida

Tópicos de Help

*help commands        # Lista de comandos
*help workflows       # Workflows disponíveis
*help agents          # Agentes e suas funções
*help templates       # Templates de modelo
*help phases          # Fases de desenvolvimento
*help getting-started # Como começar
*help faq             # Perguntas frequentes

🧪 Testes

Executar Todos os Testes

node tests/run-all-tests.cjs

Executar Testes Individuais

# Testes de estrutura
node src/test-modules.js

# Validação YAML
node tests/validation/yaml-validator.cjs

# Testes de integração
node tests/integration/integration-tests.cjs

# Testes E2E
node tests/e2e/flow-tests.cjs

Resultado Esperado

╔════════════════════════════════════════════════════════════╗
║                 ABM-KS TEST SUMMARY                        ║
╠════════════════════════════════════════════════════════════╣
║ Structure Tests           ✓ passed   265        0          ║
║ YAML Validation           ✓ passed   54         0          ║
║ Integration Tests         ✓ passed   7          0          ║
║ E2E Flow Tests            ✓ passed   5          0          ║
╠════════════════════════════════════════════════════════════╣
║ TOTAL                                331        0          ║
╚════════════════════════════════════════════════════════════╝

🤝 Contribuindo

Contribuições são bem-vindas! Veja CONTRIBUTING.md para detalhes.

Formas de Contribuir

Reportar bugs - Abra uma issue
Sugerir features - Proponha melhorias
Adicionar templates - Contribua novos modelos
Melhorar documentação - Corrija ou expanda docs
Traduzir - Ajude com traduções

Adicionar Modelo à Biblioteca

Veja library/CONTRIBUTING.md para instruções.

📄 Licença

Este projeto está licenciado sob a MIT License.

🙏 Agradecimentos

Mesa - Framework ABM para Python
NetLogo - Ambiente de modelagem
ODD Protocol - Padrão de documentação
BMAD Method - Inspiração para arquitetura

ABM-KS v0.1.0 | Feito com ❤️ para a comunidade de modelagem

Documentação · Issues · Discussões