pyfolds 1.0.2

MPJRD Neural Computation Framework

PyFolds

PyFolds é uma biblioteca de alta performance para computação bioinspirada sobre PyTorch, com foco em computação dendrítica não linear, rastreabilidade de estados e integração científica.

---

1. Visão Geral

O framework abstrai a computação dendrítica em um pipeline modular para acelerar pesquisa e engenharia aplicada em modelos MPJRD.

Por que usar o PyFolds?

• Modularidade extensível: componentes com mecanismos de plasticidade e dinâmica de curto prazo.
• Eficiência nativa: integração com o ecossistema PyTorch (CPU/GPU).
• Transparência científica: separação explícita de sinapse, dendrito e soma para auditoria de estados.

2. Instalação

pip install pyfolds

Documentation

• Instale dependências de documentação:

pip install -r requirements-docs.txt

• Gere o site localmente com Sphinx:

sphinx-build -b html docs docs/_build/html

• Entrada principal da documentação: docs/index.md.
• Portal HUB já existente: docs/development/HUB_CONTROLE.md (use como base, sem recriação do zero).
• Publicação (quando disponível no CI/GitHub Pages): consultar workflow de docs do repositório.

3. Quickstart

import torch
from pyfolds import MPJRDConfig, MPJRDNeuron

config = MPJRDConfig(n_dendrites=4, n_synapses_per_dendrite=8)
model = MPJRDNeuron(config)

x = torch.randn(32, 4, 8)  # (batch, dendritos, sinapses)
output = model(x)
print(output["spikes"])

4. Benchmarks de serialização

python scripts/run_benchmarks.py --output docs/assets/benchmarks_results.json
python scripts/generate_benchmarks_doc.py --input docs/assets/benchmarks_results.json --output docs/assets/BENCHMARKS.md

Interpretação rápida:

• Throughput (MiB/s): quanto maior, melhor.
• Razão de compressão vs none: valores menores que 1.0 indicam melhor compressão.
• O workflow .github/workflows/benchmarks.yml executa periodicamente para atualização de artefatos.

5. Portal de documentação

5.1 Uso público

• 📑 Índice de Documentação
• 🧪 Lógica Científica
• 🏗️ Arquitetura
• 📦 Especificação FOLD
• 🔌 Referência de API
• 📈 Relatório de Benchmarks

5.2 Desenvolvimento e governança (interno)

• 🧭 Índice Técnico
• 🛠️ Hub de Controle
• 🧾 Registro de ADRs
• 🛡️ Plano Mestre de Governança

6. Governança e qualidade (IEEE/ISO)

O processo documental e técnico segue princípios de padronização e rastreabilidade, alinhados a:

• ISO/IEC 12207 (ciclo de vida de software),
• IEEE 828 (configuração e controle de mudanças),
• IEEE 730 (garantia de qualidade).

Referências relevantes no repositório:

• QUALITY_ASSURANCE.md
• RISK_REGISTER.md
• adr/INDEX.md
• analise_bugs.md
• revisao_fold_mind.md
• tarefas_pendentes.md
• solucoes_fold_mind.py
• VISUAL_FINAL.txt

7. Validação local

python scripts/run_benchmarks.py
python scripts/generate_benchmarks_doc.py --input docs/assets/benchmarks_results.json --output docs/assets/BENCHMARKS.md

8. Workflow v6 (CRIAR → ANALISAR → EXECUTAR → FINALIZAR)

Fluxo operacional canônico para governança e execução de issues:

1. CRIAR
   • Criar relatório em docs/development/prompts/relatorios/ISSUE-XXX-slug.md.
   • Criar log em docs/development/prompts/logs/ISSUE-XXX-slug-LOG.md.
2. ANALISAR
   • Validar escopo, riscos, critérios de aceite e artefatos afetados.
3. EXECUTAR
   • Implementar mudanças e manter rastreabilidade em docs/development/execution_queue.csv.
4. FINALIZAR
   • Sincronizar HUB, rodar validações e abrir PR com evidências.

Comandos mínimos:

python -m compileall src/
python tools/validate_docs_links.py
python tools/sync_hub.py --check
PYTHONPATH=src pytest tests/ -v

9. Links importantes (desenvolvimento)

• 📁 Portal de Prompts Operacionais
• 🧾 Relatórios canônicos
• 🗂️ Logs canônicos
• 🛠️ HUB de Controle
• 📌 Fila de Execução