nirspy 0.0.1__tar.gz

nirspy-0.0.1/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,65 @@
+name: Bug report
+description: Report a defect in NIRSPY
+title: "[bug] "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Please fill in the
+        details below so we can reproduce it.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Clear description of the unexpected behaviour.
+      placeholder: When I run `nirspy run pipeline.yml ...` the output ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      description: Minimal pipeline.yml and dataset (or sample data ref).
+      render: shell
+    validations:
+      required: true
+
+  - type: input
+    id: nirspy-version
+    attributes:
+      label: NIRSPY version / commit
+      placeholder: "0.0.1 or commit sha"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.11.5"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: "Ubuntu 22.04 / Windows 11 / macOS 14"
+    validations:
+      required: true
+
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Traceback / logs
+      render: python

nirspy-0.0.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/BrunoFurlanetto/nirspy/security/advisories/new
+    about: Please report security issues privately via GitHub Security Advisories.
+  - name: Question / discussion
+    url: https://github.com/BrunoFurlanetto/nirspy/discussions
+    about: Open-ended questions, design discussion, "how do I…?"

nirspy-0.0.1/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,49 @@
+name: Feature request
+description: Propose a new feature or enhancement
+title: "[feat] "
+labels: ["feature", "triage"]
+body:
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: What problem does this solve? Who benefits?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: High-level description of what should be added or changed.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you thought about and why this one wins.
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Affected layer
+      multiple: true
+      options:
+        - domain
+        - engine
+        - blocks
+        - io
+        - gui
+        - cli
+        - docs
+        - ci
+    validations:
+      required: true
+
+  - type: textarea
+    id: references
+    attributes:
+      label: References
+      description: Papers, Best Practices fNIRS sections, MNE-NIRS issues, etc.

nirspy-0.0.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+<!-- Thank you for contributing to NIRSPY. -->
+
+## Summary
+
+<!-- What does this PR change and why? -->
+
+## Type of change
+
+- [ ] feat — new feature
+- [ ] fix — bug fix
+- [ ] refactor — no behaviour change
+- [ ] test — tests only
+- [ ] docs — documentation only
+- [ ] chore — tooling / dependencies / CI
+
+## Linked issues / tasks
+
+<!-- Closes #123, refs T-00X -->
+
+## Checklist
+
+- [ ] `ruff check .` passes
+- [ ] `mypy src/nirspy` passes
+- [ ] `pytest` passes locally
+- [ ] Tests added or updated for behavioural changes
+- [ ] Public API changes documented in CHANGELOG.md
+- [ ] Architecture rule (`domain → engine → gui`) respected
+- [ ] No new GPL dependency introduced (project is BSD-3)
+
+## Reproducibility note
+
+<!-- If this PR changes pipeline behaviour, confirm: same SNIRF + same
+pipeline.yml produces the same numerical output. -->

nirspy-0.0.1/.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    groups:
+      python-deps:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 3
+    labels:
+      - "dependencies"
+      - "ci"

nirspy-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+          cache-dependency-path: "pyproject.toml"
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install project
+        run: uv pip install --system -e ".[dev]" pytest-cov
+
+      - name: Ruff
+        run: ruff check .
+
+      - name: Mypy
+        run: mypy src/nirspy
+
+      - name: Pytest
+        run: pytest --cov=nirspy --cov-report=xml --cov-report=term
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: warn
+
+  publish:
+    name: Publish to PyPI
+    needs: lint-and-test
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/nirspy/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish to PyPI (Trusted Publisher / OIDC)
+        uses: pypa/gh-action-pypi-publish@release/v1

nirspy-0.0.1/.gitignore

@@ -0,0 +1,70 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Type checkers
+.mypy_cache/
+.ruff_cache/
+.pyre/
+
+# Cache
+.cache/
+diskcache/
+
+# Docs build
+site/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Env
+.env
+.env.local
+.env.agents
+
+# Project-specific
+*.snirf.cache
+examples/data/*.snirf
+!examples/data/.gitkeep

nirspy-0.0.1/.python-version

@@ -0,0 +1 @@
+3.12.2

nirspy-0.0.1/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+Todas as mudanças relevantes do projeto serão documentadas aqui.
+
+Formato baseado em [Keep a Changelog](https://keepachangelog.com/),
+versionamento por [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-21
+
+### Added
+- Camada `domain/`: `Pipeline`, `Block` Protocol, `DataType`, `BlockSpec`, `BlockResult`, `Context`, `CacheProtocol`, exceções (`NirspyError`, `ValidationError`, `ExecutionError`).
+- Camada `engine/`: `MNEAdapter` com `load_snirf`, `raw_to_od`, `beer_lambert`, `bandpass_filter`, `scalp_coupling_index`, `prune_channels`, `block_average`. `DiskCacheAdapter` com `JSONDisk` (sem pickle, S-01).
+- Blocos: `LoadSnirf`, `OpticalDensity`, `BeerLambert`, `BandpassFilter`, `ScalpCouplingIndex`, `PruneChannels`, `BlockAverage`, `ManualChannelExclude`.
+- IO: `yaml_serializer.dump_pipeline`/`load_pipeline`, conversor `.nirs ↔ .snirf` (`io/converters.py`), conversor Oxysoft `.txt → .snirf` (`io/oxysoft_txt.py`).
+- CLI: `nirspy run pipeline.yml --input X --output Y`, `nirspy serve`, `nirspy --version`.
+- GUI: Dash app factory, layout de três painéis, builder de pipeline (catalog + reorder + remove + toggle), param editor enriquecido (labels, tooltips, ranges, Optional checkbox, multiselect de canais), visualização de execução (raw, probe, QC heatmap, HRF μM), tab Convert (`.nirs↔.snirf` + Oxysoft `.txt→.snirf`).
+- **T-012 — Janelas temporais por condição em `BlockAverage`**: novo dataclass `ConditionWindow`, parâmetro `per_condition_windows`, método `MNEAdapter.create_epochs_per_condition`, editor GUI auto-populado a partir do SNIRF, YAML round-trip retrocompatível.
+- Segurança Etapa 5A: validação de path SNIRF (S-02), sample-count guard (S-001), bloqueio de h5py external links (S-002), `O_EXCL` em escrita (S-003), opção `strip_pii` em conversores (I-001), serialização JSON em cache (S-01).
+- Templates de issue/PR, política de segurança, dependabot, cache pip e cobertura no CI.
+
+### Changed
+- CI: removido `pytest-dash` das dev deps (unmaintained, incompatível com selenium ≥4.10).
+- CI: `mypy` agora bloqueia merge (era `continue-on-error`).
+- `JSONDisk.store/fetch` delegam ao `Disk` base — corrige overwrite e persistência entre instâncias.
+- `BlockAverageBlock.run`: keys desconhecidas em `per_condition_windows` viram `UserWarning` (em vez de raise) — pipeline robusta a troca de SNIRF com conjunto de condições diferente.
+
+### Removed
+- `pytest-dash` das dev dependencies.

nirspy-0.0.1/CLAUDE.md

@@ -0,0 +1,179 @@
+# CLAUDE.md — nirspy
+
+> Configurações do projeto para o time de agentes.
+> Complementa e sobrescreve o CLAUDE.md global quando necessário.
+
+---
+
+## Projeto
+
+**Nome:** nirspy
+**Descrição:** GUI fNIRS-first em Python — builder modular de pipeline sobre MNE-NIRS, distribuída como open source (BSD-3).
+**Stack:** Python 3.10+ · Dash · Plotly · MNE-NIRS · uv · hatchling · pytest · ruff · mypy
+**Repositório:** https://github.com/BrunoFurlanetto/nirspy.git
+**Ambiente local:** `nirspy serve` → `http://127.0.0.1:8050`
+
+---
+
+## Vault (Obsidian)
+
+**Path do projeto:** `Dev projects/nirspy`
+**Memory:** `Dev projects/nirspy/Memory.md`
+**Session Log:** `Dev projects/nirspy/session-log.md`
+**Planejamentos:** `Dev projects/nirspy/features/`
+**Visão e arquitetura:** `Dev projects/nirspy/visao-do-produto.md`, `Dev projects/nirspy/arquitetura.md`, `Dev projects/nirspy/roadmap.md`
+
+### Abertura de sessão
+
+Ler em paralelo antes de qualquer task:
+
+```
+mcp_obsidian: view  →  Dev projects/nirspy/Memory.md
+mcp_obsidian: view  →  Dev projects/nirspy/session-log.md
+mcp_obsidian: view  →  Dev projects/_memory.md      (ADRs globais)
+```
+
+Se a task envolve uma feature, ler também:
+```
+mcp_obsidian: view  →  Dev projects/nirspy/features/<nome-da-feature>.md
+```
+
+Sempre consultar `Dev projects/nirspy/arquitetura.md` antes de criar arquivos novos — a regra das três camadas (`domain` → `engine` → `gui`) é estrita.
+
+### Fechamento de sessão
+
+Seguir protocolo condicional do CLAUDE.md global. Quando registrar:
+
+```
+mcp_obsidian: str_replace  →  Dev projects/nirspy/session-log.md
+```
+
+ADR novo (decisão de design): adicionar **antes** de fechar log:
+```
+mcp_obsidian: str_replace  →  Dev projects/nirspy/Memory.md
+```
+
+---
+
+## Branches protegidas
+
+Nunca commitar diretamente nem criar branches a partir de:
+- `main`
+
+Orchestrator sempre confirma branch base com Lead antes de criar nova branch.
+
+### Convenção de branches
+```
+feature/T-xxx-nome-curto
+fix/T-xxx-descricao
+chore/T-xxx-descricao
+```
+
+---
+
+## Como rodar
+
+```bash
+# setup
+uv venv
+uv pip install -e ".[dev]"
+
+# dev server
+nirspy serve
+
+# testes
+pytest
+
+# lint + types
+ruff check .
+mypy src/nirspy
+```
+
+---
+
+## Ownership dos agentes
+
+Arquitetura em três camadas (`domain` → `engine` → `gui`) determina ownership.
+
+| Agente | Pode criar/editar | Somente leitura |
+|--------|-------------------|-----------------|
+| `dev` | `src/nirspy/gui/`, `src/nirspy/cli/`, `src/nirspy/blocks/` (lógica não-engine), `src/nirspy/io/`, `examples/`, `docs/` | `domain/`, `engine/` (precisa contrato dba) |
+| `dba` | `src/nirspy/domain/`, `src/nirspy/engine/`, `src/nirspy/blocks/` (camada de execução MNE), `examples/pipelines/*.yml` (schema de pipeline) | `gui/`, `cli/` |
+| `qa` | `tests/` | todo o código de produção |
+| `security` | `docs/security/` (criar se necessário) | todo o codebase |
+| `reviewer` | — | todo o codebase |
+
+> Note: neste projeto `dba` cobre **camada de dados/domínio + adapter MNE-NIRS**, não banco relacional. Ele detém o contrato `Pipeline`/`Block`/`DataType` (ADR-005) e o adapter `engine/mne_adapter.py`. Qualquer mudança em estrutura de domínio passa por contrato dele antes do dev tocar na GUI.
+
+---
+
+## Convenções
+
+### Commits
+
+```
+tipo(escopo): mensagem imperativa curta
+
+Agente: <Nome> (<role>)
+Task: T-xxx
+```
+
+Tipos válidos: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `style`
+
+Escopos sugeridos: `domain`, `engine`, `blocks`, `gui`, `io`, `cli`, `ci`, `docs`.
+
+### Estilo Python
+- `ruff` configurado em `pyproject.toml` (E, F, I, B, UP, SIM)
+- `mypy --strict` no pacote `nirspy`
+- Linha máx 100 caracteres
+- Type hints obrigatórios em código novo (camada `domain` em particular)
+
+### Regra de ouro arquitetural (ADR-005)
+- `domain/` **não importa** Dash, Plotly, MNE, MNE-NIRS — apenas stdlib + tipagem
+- `engine/` importa `domain` + MNE/MNE-NIRS — nunca Dash
+- `gui/` pode importar tudo do projeto
+- Antes de criar arquivo novo, identificar a camada e respeitar a direção dos imports
+
+### Pipelines como contrato
+- Pipelines salvas em YAML são **API pública** do projeto
+- Mudança breaking no schema de pipeline requer ADR e bump de minor (v0.x → v0.x+1)
+- Round-trip YAML → Pipeline → YAML deve ser idêntico (golden tests em `tests/io/`)
+
+### Open source
+Toda decisão técnica deve considerar:
+- Reprodutibilidade (mesma pipeline + mesmo SNIRF = mesmo resultado em qualquer máquina)
+- Compatibilidade com Best Practices fNIRS (Yücel et al., 2021)
+- Acessibilidade para usuários que não programam
+- Manutenibilidade por dev solo
+
+### Dependências
+- Não adicionar dependência sem justificativa em PR
+- Preferir biblioteca já presente no ecossistema MNE/scipy
+- Nunca acoplar a algo GPL — projeto é BSD-3
+
+---
+
+## Stack-específico
+
+### Estrutura de pastas (src layout)
+```
+src/nirspy/
+├── domain/      # camada 1 — pura
+├── engine/      # camada 2 — adapter MNE-NIRS
+├── blocks/      # blocos concretos (load, OD, mBLL, motion, QC, analysis, export)
+├── io/          # serializadores YAML/JSON de pipelines
+├── gui/         # Dash app (components/, pages/, callbacks/)
+└── cli/         # entry point `nirspy`
+```
+
+### Testes
+- `tests/domain/` — unit puro, <100ms
+- `tests/engine/` — integração com fixtures MNE
+- `tests/blocks/` — integração por bloco
+- `tests/io/` — round-trip golden files
+- `tests/gui/` — smoke tests via `pytest-dash`
+
+Dataset de referência: MNE-NIRS sample dataset (BSD-3, redistribuível).
+
+### CI
+GitHub Actions em `.github/workflows/ci.yml` — matrix Python 3.10/3.11/3.12, ruff + mypy + pytest.

nirspy-0.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Code of Conduct
+
+This project adopts the **[Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)**
+as its code of conduct.
+
+Full text: https://www.contributor-covenant.org/version/2/1/code_of_conduct/
+
+Official translations: https://www.contributor-covenant.org/translations/
+
+## Enforcement
+
+Conduct that violates the code may be reported to the maintainer:
+
+- Email: bruno.furlanetto@hotmail.com
+
+Reports are handled confidentially. Expected response within 7 days.

nirspy-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,114 @@
+# Contributing to NIRSPY
+
+Thanks for your interest in contributing. This document describes the minimal
+flow for running the project, opening issues, and submitting pull requests.
+
+## Local setup
+
+Prerequisites: Python 3.10+. [`uv`](https://docs.astral.sh/uv/) is supported
+but not required.
+
+```bash
+git clone https://github.com/BrunoFurlanetto/nirspy.git
+cd nirspy
+python -m venv .venv
+# Linux/macOS
+source .venv/bin/activate
+# Windows PowerShell
+.venv\Scripts\Activate.ps1
+
+pip install -e ".[dev]"
+```
+
+### Run tests, lint, types
+
+```bash
+pytest
+ruff check .
+mypy src/nirspy
+```
+
+### Run the app
+
+```bash
+nirspy serve
+# open http://127.0.0.1:8050
+```
+
+## Issues
+
+Before opening an issue:
+
+1. Check that a similar issue is not already open or closed.
+2. For bugs: describe reproduction steps, expected vs observed behaviour,
+   Python version, and `nirspy` version.
+3. For features: review the [roadmap](docs/roadmap.md) — it may already be
+   planned. Otherwise describe the problem before the solution.
+
+Use the [issue templates](.github/ISSUE_TEMPLATE/) — blank issues are
+disabled.
+
+## Branches
+
+Always branched off `main`:
+
+```
+feature/T-xxx-short-name
+fix/T-xxx-description
+chore/T-xxx-description
+docs/T-xxx-description
+```
+
+`main` is protected — no direct commits. All changes go through a PR.
+
+## Commits
+
+Short Conventional Commits style:
+
+```
+type(scope): short imperative subject
+
+Optional body explaining the why.
+```
+
+Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `style`.
+Suggested scopes: `domain`, `engine`, `blocks`, `gui`, `io`, `cli`, `ci`, `docs`.
+
+## Pull requests
+
+1. Branch from `main`.
+2. Lint, types and tests pass locally.
+3. Open a PR against `main` with a clear description: what changes, why, and
+   how to test.
+4. CI must pass (ruff + mypy + pytest matrix on Python 3.10/3.11/3.12).
+5. Wait for review. Squash-merge is the default.
+
+## Architecture
+
+Before creating new files, read [`docs/architecture.md`](docs/architecture.md).
+The golden rule:
+
+- `domain/` must not import Dash, Plotly, or MNE.
+- `engine/` may import `domain` + MNE/MNE-NIRS, but not Dash.
+- `gui/` may import everything from the project.
+
+PRs that violate this rule will be rejected.
+
+## Tests
+
+- `tests/domain/` — pure unit tests, <100 ms.
+- `tests/engine/` and `tests/blocks/` — integration with fixtures.
+- `tests/io/` — round-trip golden files.
+- `tests/gui/` — smoke tests via Dash test client.
+
+Minimum coverage target for `domain/`: 80%.
+
+## Code of conduct
+
+By participating in this project you agree to follow the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+Contributions are accepted under the project's
+[BSD-3-Clause license](LICENSE).