abm-ks 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.
+
+O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/),
+e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR/).
+
+## [0.1.0] - 2025-01-15
+
+### 🎉 Release Inicial
+
+Primeira versão pública do ABM-KS (Agent-Based Modeling Knowledge System).
+
+### Adicionado
+
+#### Core
+- Sistema modular com arquitetura extensível
+- Agente ABM Master para coordenação geral
+- Workflows de inicialização (`*init`) e status (`*status`)
+- Sistema de help contextual com 8 tópicos
+
+#### Equipe de Desenvolvimento ABM (7 agentes)
+- Model Designer - Design conceitual de modelos
+- Simulation Architect - Arquitetura técnica
+- Python Developer - Implementação Python/Mesa
+- NetLogo Developer - Implementação NetLogo
+- C++ Developer - Implementação C++ de alta performance
+- ODD Writer - Documentação ODD Protocol
+- Experiment Designer - Design de experimentos
+
+#### Workflows ABM (11 workflows em 4 fases)
+- **Fase 1**: model-brief, pattern-identification
+- **Fase 2**: entity-design, behavior-rules, environment-setup, process-scheduling
+- **Fase 3**: code-generation, model-testing, experiment-setup
+- **Fase 4**: generate-odd, readme-generation
+
+#### Equipe de Brainstorming (5 agentes) - Opcional
+- Facilitador - Coordenação de sessões
+- Pesquisador - Revisão de literatura
+- Crítico - Análise crítica
+- Visionário - Ideação criativa
+- Sintetizador - Consolidação de documentos
+
+#### Workflows de Brainstorming (5 workflows)
+- ideation-session, literature-review, problem-definition
+- hypothesis-generation, model-scoping
+
+#### Equipe de Documentação (5 agentes) - Opcional
+- Editor Científico - Escrita acadêmica
+- Documentador Técnico - Manuais técnicos
+- Analista de Dados - Protocolos de análise
+- Revisor - Controle de qualidade
+- Comunicador - Adaptação para públicos
+
+#### Workflows de Documentação (5 workflows)
+- academic-paper, technical-manual, data-collection-guide
+- analysis-protocol, documentation-review
+
+#### Biblioteca de Modelos
+- Sistema de biblioteca com registry YAML
+- 6 templates prontos:
+  - Predator-Prey (Python + NetLogo)
+  - SIR Epidemic (Python + NetLogo)
+  - Schelling Segregation (Python + NetLogo)
+- Comandos: `*list-models`, `*use-template`, `*browse-library`
+- Framework para contribuições da comunidade
+
+#### Documentação
+- Guia Getting Started
+- Guia de Conceitos ABM
+- Cartão de Referência Rápida
+- Sistema de help integrado
+
+#### Infraestrutura
+- CLI para instalação via npx
+- Sistema de seleção de equipes
+- 331 testes automatizados
+- Validação de YAML e integridade
+
+### Estatísticas
+
+| Componente | Quantidade |
+|------------|------------|
+| Agentes | 18 |
+| Workflows | 27 |
+| Templates | 6 |
+| Testes | 331 |
+| Arquivos | 235 |
+
+---
+
+## Versões Futuras
+
+### [0.2.0] - Planejado
+- [ ] Mais templates de modelos
+- [ ] Suporte a Repast Simphony
+- [ ] Integração com Git
+- [ ] Dashboard de progresso visual
+
+### [0.3.0] - Planejado
+- [ ] Biblioteca comunitária online
+- [ ] Validação automática de ODD
+- [ ] Export para LaTeX
+- [ ] Internacionalização (i18n)
+
+---
+
+[0.1.0]: https://github.com/abm-ks/abm-ks/releases/tag/v0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,294 @@
+# Contribuindo para o ABM-KS
+
+Obrigado por considerar contribuir com o ABM-KS! 🎉
+
+Este documento fornece diretrizes para contribuições ao projeto.
+
+## 📋 Índice
+
+- [Código de Conduta](#código-de-conduta)
+- [Como Posso Contribuir?](#como-posso-contribuir)
+- [Reportando Bugs](#reportando-bugs)
+- [Sugerindo Melhorias](#sugerindo-melhorias)
+- [Contribuindo com Código](#contribuindo-com-código)
+- [Adicionando Templates](#adicionando-templates)
+- [Guia de Estilo](#guia-de-estilo)
+- [Processo de Review](#processo-de-review)
+
+---
+
+## Código de Conduta
+
+Este projeto adota um código de conduta para garantir um ambiente acolhedor para todos. Ao participar, você concorda em manter um ambiente respeitoso e inclusivo.
+
+### Nossos Padrões
+
+✅ **Comportamentos esperados:**
+- Usar linguagem acolhedora e inclusiva
+- Respeitar diferentes pontos de vista
+- Aceitar críticas construtivas
+- Focar no que é melhor para a comunidade
+
+❌ **Comportamentos inaceitáveis:**
+- Linguagem ou imagens ofensivas
+- Assédio de qualquer tipo
+- Ataques pessoais ou políticos
+- Publicar informações privadas de outros
+
+---
+
+## Como Posso Contribuir?
+
+### 🐛 Reportando Bugs
+
+Antes de reportar um bug:
+1. Verifique se já não foi reportado
+2. Teste com a versão mais recente
+3. Colete informações relevantes
+
+**Inclua no seu report:**
+- Versão do ABM-KS
+- Sistema operacional
+- Passos para reproduzir
+- Comportamento esperado vs atual
+- Screenshots/logs se aplicável
+
+### 💡 Sugerindo Melhorias
+
+Sugestões são bem-vindas! Abra uma issue descrevendo:
+- O problema que a melhoria resolve
+- Como você imagina a solução
+- Alternativas consideradas
+- Contexto adicional
+
+### 📝 Melhorando Documentação
+
+Documentação é crucial! Você pode:
+- Corrigir erros de digitação
+- Esclarecer seções confusas
+- Adicionar exemplos
+- Traduzir para outros idiomas
+
+---
+
+## Contribuindo com Código
+
+### Setup do Ambiente
+
+```bash
+# Clone seu fork
+git clone https://github.com/seu-usuario/abm-ks.git
+cd abm-ks
+
+# Instale dependências
+npm install
+
+# Execute testes
+node tests/run-all-tests.cjs
+```
+
+### Fluxo de Trabalho
+
+1. **Fork** o repositório
+2. **Clone** seu fork localmente
+3. **Crie uma branch** para sua feature
+   ```bash
+   git checkout -b feature/minha-feature
+   ```
+4. **Faça commits** com mensagens claras
+5. **Execute testes** antes de submeter
+6. **Abra um Pull Request**
+
+### Estrutura de Commits
+
+Use mensagens de commit claras e descritivas:
+
+```
+tipo(escopo): descrição curta
+
+Descrição mais detalhada se necessário.
+
+Fixes #123
+```
+
+**Tipos de commit:**
+- `feat`: Nova feature
+- `fix`: Correção de bug
+- `docs`: Documentação
+- `style`: Formatação
+- `refactor`: Refatoração
+- `test`: Testes
+- `chore`: Manutenção
+
+### Executando Testes
+
+```bash
+# Todos os testes
+node tests/run-all-tests.cjs
+
+# Testes específicos
+node src/test-modules.js           # Estrutura
+node tests/validation/yaml-validator.cjs  # YAML
+node tests/integration/integration-tests.cjs  # Integração
+node tests/e2e/flow-tests.cjs      # E2E
+```
+
+**Importante:** Todos os testes devem passar antes do PR ser aceito.
+
+---
+
+## Adicionando Templates
+
+Templates de modelos são muito bem-vindos! 
+
+### Requisitos
+
+1. Modelo deve ser funcional e testado
+2. Código bem documentado
+3. README explicativo
+4. Seguir a estrutura padrão
+
+### Estrutura do Template
+
+```
+templates/models/{plataforma}/{nome-do-modelo}/
+├── model-info.yaml      # Metadados do modelo
+├── README.md            # Documentação
+└── src/                 # Código fonte
+    ├── model.py         # (Python)
+    └── model.nlogo      # (NetLogo)
+```
+
+### model-info.yaml
+
+```yaml
+model:
+  id: nome-do-modelo
+  name: "Nome Exibição"
+  version: 1.0.0
+  description: "Descrição breve"
+  
+  metadata:
+    author: "Seu Nome"
+    domain: ecology|epidemiology|economics|social|other
+    complexity: beginner|intermediate|advanced
+    
+  technical:
+    platform: python|netlogo|cpp
+    requirements:
+      - mesa>=2.0.0
+      
+  tags:
+    - tag1
+    - tag2
+```
+
+### Processo de Submissão
+
+1. Crie o modelo seguindo a estrutura
+2. Adicione ao registry em `library/model-registry.yaml`
+3. Execute `node src/test-modules.js` para validar
+4. Abra um PR com a categoria `template`
+
+Veja também: [library/CONTRIBUTING.md](src/modules/abm/library/CONTRIBUTING.md)
+
+---
+
+## Guia de Estilo
+
+### YAML
+
+```yaml
+# Use 2 espaços para indentação
+# Strings com caracteres especiais entre aspas
+# Listas com hífen e espaço
+
+workflow:
+  id: meu-workflow
+  name: "Meu Workflow"
+  description: >
+    Descrição multilinha usando
+    folded scalar.
+    
+  steps:
+    - id: step-1
+      name: "Primeiro Passo"
+```
+
+### Markdown
+
+- Use headers hierárquicos (#, ##, ###)
+- Inclua índice para docs longos
+- Use tabelas para informações estruturadas
+- Adicione exemplos de código com syntax highlighting
+
+### JavaScript
+
+```javascript
+// Use const/let, nunca var
+// Funções com nomes descritivos
+// Comente código complexo
+// Siga o estilo existente no projeto
+
+const colors = {
+  green: '\x1b[32m',
+  reset: '\x1b[0m'
+};
+
+function validateSchema(filePath, schemaType) {
+  // Implementação...
+}
+```
+
+---
+
+## Processo de Review
+
+### O que esperamos
+
+1. **Código limpo** - Legível e bem estruturado
+2. **Testes passando** - Todos os 331+ testes
+3. **Documentação** - Atualizada conforme mudanças
+4. **Commits claros** - Histórico compreensível
+
+### Timeline
+
+- PRs são revisados em até 7 dias
+- Feedback será dado via comentários
+- Iterações podem ser necessárias
+- Merge após aprovação
+
+### Labels
+
+- `bug` - Correção de bug
+- `enhancement` - Nova feature
+- `documentation` - Docs
+- `template` - Novo template
+- `good first issue` - Bom para iniciantes
+
+---
+
+## Reconhecimento
+
+Todos os contribuidores serão reconhecidos no projeto:
+- Lista de Contributors no README
+- Changelog com créditos
+- Releases com agradecimentos
+
+---
+
+## Dúvidas?
+
+- Abra uma issue com label `question`
+- Participe das discussões no GitHub
+- Entre em contato via email
+
+**Obrigado por contribuir!** 🙏
+
+---
+
+<div align="center">
+
+[↑ Voltar ao topo](#contribuindo-para-o-abm-ks)
+
+</div>

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ABM-KS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.