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

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


---

📋 Índice

- O que é ABM-KS?
- Características
- Instalação Rápida
- Primeiros Passos
- Arquitetura
- Equipes de Agentes
- Workflows
- Templates de Modelos
- Comandos
- Documentação
- Testes
- Contribuindo
- Licença

---

🎯 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

$3

- 🔬 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

$3

| 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 |

$3

- 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

$3

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

$3

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

---

🚀 Instalação Rápida

$3

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

$3

``bash
npx abm-ks install
`

$3

`bash


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
`

$3

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

$3

`
*init
`

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

$3

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

$3

`
*status
`

$3

`
*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

$3

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

$3

| 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 |

$3

| 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 |

$3

| 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

$3

| 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 |

$3

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

$3

| 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 |

$3

| 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 |

$3

| 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

$3

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

$3

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

$3

`bash
*list-models
*browse-library
`

---

⌨️ Comandos

$3

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

$3

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

$3

| 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

$3

- Getting Started - Primeiros passos
- ABM Concepts - Conceitos de ABM

$3

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

$3

`bash
*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

$3

`bash
node tests/run-all-tests.cjs
`

$3

`bash


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
`

$3

`
╔════════════════════════════════════════════════════════════╗
║ 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.

$3

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

$3

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

---