groupoid 0.1.0.dev1__tar.gz

groupoid-0.1.0.dev1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,36 @@
+---
+name: Bug Report
+about: Report a bug in GROUPOID
+title: "[BUG] "
+labels: bug
+assignees: ''
+---
+
+## Description
+
+A clear description of the bug.
+
+## Steps to Reproduce
+
+1. ...
+2. ...
+3. ...
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened.
+
+## Environment
+
+- OS:
+- Python version:
+- GROUPOID version:
+- Relevant dependencies:
+
+## Additional Context
+
+Any additional information, stack traces, or screenshots.

groupoid-0.1.0.dev1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature Request
+about: Suggest a new feature for GROUPOID
+title: "[FEATURE] "
+labels: enhancement
+assignees: ''
+---
+
+## Summary
+
+A concise description of the feature.
+
+## Motivation
+
+Why is this feature needed? What problem does it solve?
+
+## Proposed Solution
+
+How should this feature work?
+
+## Alternatives Considered
+
+What other approaches did you consider?
+
+## Additional Context
+
+Any additional information or references.

groupoid-0.1.0.dev1/.github/ISSUE_TEMPLATE/mathematical_correction.md

@@ -0,0 +1,27 @@
+---
+name: Mathematical Correction
+about: Report a mathematical error or suggest a correction
+title: "[MATH] "
+labels: mathematical
+assignees: ''
+---
+
+## Location
+
+Which module, function, or documentation page contains the error?
+
+## Description of Error
+
+Describe the mathematical error precisely.
+
+## Correct Statement
+
+Provide the correct mathematical statement with proof or reference.
+
+## References
+
+Cite relevant papers, textbooks, or other sources.
+
+## Impact
+
+How does this error affect the correctness of computations?

groupoid-0.1.0.dev1/.github/dependabot.yml

@@ -0,0 +1,29 @@
+# Dependabot configuration.
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+#
+# Opens reviewable update PRs (never auto-merged) so security and version bumps
+# are surfaced proactively, rather than relying on a manual read of the CI
+# dependency-audit output. Complements the CI dependency-vulnerability scan.
+version: 2
+updates:
+  # Python dependencies declared in pyproject.toml.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      # Batch low-risk minor/patch bumps into a single PR to limit noise; majors
+      # (which can ship breaking changes) stay as individual, separately
+      # reviewable PRs.
+      python-minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+
+  # GitHub Actions used in the workflows (keeps action versions current).
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

groupoid-0.1.0.dev1/.github/workflows/ci.yml

@@ -0,0 +1,150 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          # Install the project so `mypy --strict` type-checks against the real
+          # numpy / pydantic stubs (NDArray dtype args, the BaseModel base class).
+          # Linting only against `ruff black mypy` left numpy/pydantic uninstalled,
+          # so --strict raised disallow_subclassing_any on the BaseModel subclass.
+          # Consistent with the test / security / docs jobs. CPU torch keeps it lean.
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e ".[dev]"
+      - name: Run ruff
+        run: ruff check .
+      - name: Run black check
+        run: black --check .
+      - name: Run mypy (strict)
+        run: mypy --strict groupoid/ --ignore-missing-imports
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e ".[dev]"
+      - name: Run tests with coverage gate
+        run: >-
+          pytest tests/ -v --tb=short -x
+          --cov=groupoid --cov-branch
+          --cov-report=term-missing --cov-fail-under=100
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          # Install the project's real runtime closure so pip-audit scans the
+          # packages GROUPOID actually depends on. The previous `safety` step
+          # installed only the tools and never the project, so it audited the
+          # wrong environment. CPU torch keeps the install lean.
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e .
+          pip install bandit pip-audit
+          # Pin setuptools LAST. torch requires setuptools<82 and pulls in a
+          # runner-bundled setuptools that can predate the PYSEC-2025-49 fix
+          # (78.1.1); upgrading before `pip install -e .` is simply undone by torch.
+          # The window >=78.1.1,<82 clears the advisory while staying
+          # dependency-consistent with torch (verified: pip check clean).
+          python -m pip install --upgrade "setuptools>=78.1.1,<82"
+      - name: Run bandit
+        run: bandit -r groupoid/ -c pyproject.toml
+      - name: Audit dependencies for known vulnerabilities (pip-audit)
+        # pip-audit (OSV-backed, maintained) replaces the deprecated `safety check`
+        # (deprecated in safety 3.x in favour of the account-gated `safety scan`).
+        # HARD gate: any advisory with a fix version fails the job. The single
+        # documented exception is CVE-2025-3000 (torch): no fixed release exists
+        # upstream, and OSV expresses the affected range (listed versions up to
+        # v2.6.0) as a Git/commit boundary pip-audit cannot version-resolve, so it
+        # conservatively flags the installed torch. Disclosed in SECURITY.md; the
+        # torch.load / JIT deserialization path is not exercised by GROUPOID. Revisit
+        # the ignore once upstream publishes a fixed release.
+        run: pip-audit --ignore-vuln CVE-2025-3000
+
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install pre-commit
+        run: pip install pre-commit
+      - name: Run pre-commit
+        run: pre-commit run --all-files
+
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e ".[dev]"
+      # Benchmarks run for information only. There is no regression gate:
+      # timing baselines recorded on one machine are not comparable to a
+      # different CI runner, so gating CI against such a baseline would be a
+      # meaningless pass/fail. The benchmark JSON is uploaded as an artifact
+      # for inspection. A real cross-run regression gate can be added later
+      # (e.g. github-action-benchmark with continuous baselines), at which
+      # point a committed, machine-tagged baseline becomes meaningful.
+      - name: Run benchmarks (informational only, not a gate)
+        run: |
+          pytest benchmarks/ -v --benchmark-json=benchmark_results.json || true
+      - name: Upload benchmark results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: benchmark_results.json
+          if-no-files-found: ignore
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e ".[docs]"
+      - name: Build docs
+        run: mkdocs build --strict

groupoid-0.1.0.dev1/.github/workflows/docs-deploy.yml

@@ -0,0 +1,44 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e ".[docs]"
+      - name: Build docs
+        run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

groupoid-0.1.0.dev1/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+*.so
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+htmlcov/
+.coverage
+site/
+.env
+*.log
+benchmark_results.json
+data/
+.venv/
+.venv-*/
+venv/

groupoid-0.1.0.dev1/.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+
+  - repo: https://github.com/psf/black
+    rev: 24.2.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.8.0
+    hooks:
+      - id: mypy
+        # Scope to the package, matching the CI lint job (`mypy groupoid/`). The
+        # tests are not type-annotated to the package's standard, and numpy-stub
+        # inference on test helpers (e.g. matmul of rotation matrices) is noisy.
+        files: ^groupoid/
+        # Pin numpy to the project's supported range so the hook type-checks
+        # against the same stubs as runtime/CI. Unbounded numpy>=1.24 resolves to
+        # numpy 2.x, whose stubs type e.g. np.linalg.inv as floating[Any] and
+        # disagree with the project's numpy<2.0 (pinned for geomstats).
+        additional_dependencies: ["pydantic>=2.0", "numpy>=1.24,<2.0"]
+        args: [--ignore-missing-imports]
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.7.7
+    hooks:
+      - id: bandit
+        args: [-c, pyproject.toml]
+        additional_dependencies: ["bandit[toml]"]

groupoid-0.1.0.dev1/.zenodo.json

@@ -0,0 +1,39 @@
+{
+  "upload_type": "software",
+  "title": "GROUPOID: Groupoid-based aggregation for federated learning on Riemannian manifolds",
+  "version": "0.1.0.dev1",
+  "description": "<p>Pre-alpha research prototype exploring groupoid-based aggregation for federated learning on Riemannian manifolds. Implements transport groupoid morphisms, first cohomology (H^1) for consistency detection, the cellular sheaf Laplacian for spectral analysis, parallel transport (Schild's and pole ladders), and Karcher mean aggregation via geomstats.</p><p><strong>Erratum / supersession notice:</strong> this version (v0.1.0.dev1) corrects mathematical bugs present in the earlier v0.1.0.dev0 snapshot (version DOI 10.5281/zenodo.20563975): the sheaf (connection) Laplacian is now a verified positive-semidefinite operator with a transport-consistent kernel; persistence diagrams retain the homology-dimension label so H0 and H1 are no longer conflated; and H^1 cohomology raises on incomplete cocycles instead of forming partial holonomy. The v0.1.0.dev0 version DOI must not be cited for results. Cite the concept DOI (10.5281/zenodo.20563974), which always resolves to the latest corrected version, or this version or later.</p>",
+  "creators": [
+    {
+      "name": "Maniches, Santiago",
+      "affiliation": "TOPOLOGICA LLC",
+      "orcid": "0009-0005-6480-1987"
+    }
+  ],
+  "license": "Apache-2.0",
+  "keywords": [
+    "federated learning",
+    "Riemannian geometry",
+    "groupoid",
+    "sheaf theory",
+    "cohomology",
+    "topological data analysis"
+  ],
+  "related_identifiers": [
+    {
+      "identifier": "10.5281/zenodo.20563974",
+      "relation": "isVersionOf",
+      "scheme": "doi"
+    },
+    {
+      "identifier": "10.5281/zenodo.20563975",
+      "relation": "isNewVersionOf",
+      "scheme": "doi"
+    },
+    {
+      "identifier": "https://github.com/smaniches/GROUPOID",
+      "relation": "isSupplementTo",
+      "scheme": "url"
+    }
+  ]
+}

groupoid-0.1.0.dev1/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to GROUPOID are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+(with PEP 440 identifiers for Python pre-releases).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.1.0.dev1] - 2026-06-16
+
+First tag cut on mathematically corrected code. The earlier `v0.1.0.dev0` tag and
+its Zenodo version DOI (`10.5281/zenodo.20563975`) predate the correctness fixes
+below and are **superseded**; that snapshot must not be cited for results. The
+concept DOI (`10.5281/zenodo.20563974`) resolves to this version.
+
+### Fixed
+- **Sheaf (connection) Laplacian** corrected to a positive-semidefinite operator
+  `L = delta^T delta` with a transport-consistent kernel, verified against an
+  independently constructed coboundary (#13, closes #8).
+- **Persistence diagrams** now retain the homology-dimension label, so H0 and H1
+  bars are no longer conflated; `track_divergence` compares H0 against H0 only,
+  verified against an independent scipy minimum-spanning-tree reconstruction
+  (#21, closes #10).
+- **Cohomology**: `compute_h1` raises `IncompleteCocycleError` naming the missing
+  edge instead of forming a meaningless partial holonomy, and disconnected-graph
+  transport is re-raised as an explicit domain error (#20).
+- Benchmark CI regression check soft-skips on a missing JSON baseline instead of
+  failing the job (#15).
+
+### Added
+- 100% line + branch test coverage of the `groupoid` package on Python 3.10-3.12,
+  enforced in CI via `--cov-branch --cov-fail-under=100` (#18).
+- Cold-clone reproducibility: a seeded determinism receipt and reproduction guide
+  (`REPRODUCE.md`), install cap, stub clarity, and a real CI gate (#16).
+- Aggregation tests covering forward-edge traversal, weighted mean, and the
+  inconsistency flag (#17).
+- Zenodo concept-DOI badge and `CITATION.cff` DOI metadata (#11).
+- A `Documentation` project URL and keywords aligned across `pyproject.toml`,
+  `codemeta.json`, and `CITATION.cff` (#19).
+- A consolidated `PROBLEMS.md` self-audit recording corrected bugs, known
+  limitations, and deferred work (#23).
+- A `CHANGELOG.md` linked from package metadata (#24).
+- A `.zenodo.json` so archival deposits carry curated metadata, a supersession
+  note for `v0.1.0.dev0`, and version-chain links to the concept and prior DOIs.
+- Dependabot configuration for weekly `pip` and `github-actions` updates (#25).
+
+### Changed
+- Numpy array annotations parameterized to `NDArray[np.float64]`, with
+  `mypy --strict` enforced as a hard, gating CI step (#26).
+
+### Security
+- Replaced the deprecated soft `safety check` with a hard, gating `pip-audit`
+  step; the fix-less torch advisory CVE-2025-3000 is documented and explicitly
+  ignored with its rationale in `SECURITY.md` (#22).
+
+## [0.1.0.dev0] - 2026-06-05
+
+Initial pre-alpha research prototype. Core implementation of groupoid-based
+aggregation for federated learning on Riemannian manifolds: the transport groupoid
+(morphism composition and inverse), the Karcher mean via geomstats, H^1
+cohomological consistency, the sheaf Laplacian, parallel transport (Schild's and
+pole ladders), and persistence-based divergence tracking. Ships machine-readable
+citation metadata (`CITATION.cff`, `codemeta.json` with ORCID). Pre-alpha: APIs
+may change and the central hypothesis is not yet validated (see `STATUS.md` and
+`LIMITATIONS.md`).
+
+Date shown is the tag commit (`v0.1.0.dev0` -> 2a02954). `CITATION.cff` records
+`date-released: 2026-05-25`, when the core implementation landed; the tag was
+later placed on the metadata commit.
+
+[Unreleased]: https://github.com/smaniches/GROUPOID/compare/v0.1.0.dev1...HEAD
+[0.1.0.dev1]: https://github.com/smaniches/GROUPOID/compare/v0.1.0.dev0...v0.1.0.dev1
+[0.1.0.dev0]: https://github.com/smaniches/GROUPOID/releases/tag/v0.1.0.dev0

groupoid-0.1.0.dev1/CITATION.cff

@@ -0,0 +1,35 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "GROUPOID: Groupoid-based aggregation for federated learning on Riemannian manifolds"
+version: 0.1.0.dev1
+date-released: 2026-06-16
+license: Apache-2.0
+repository-code: "https://github.com/smaniches/GROUPOID"
+doi: 10.5281/zenodo.20563974
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.20563974
+    description: "Concept DOI (all versions) — always resolves to the latest, mathematically corrected version. Cite this."
+  - type: doi
+    value: 10.5281/zenodo.20563975
+    description: "Version DOI (v0.1.0.dev0) — SUPERSEDED. This snapshot predates the sheaf-Laplacian PSD, persistence-dimension, and cohomology corrections; do not cite for results. Use v0.1.0.dev1 or later."
+authors:
+  - family-names: Maniches
+    given-names: Santiago
+    email: santiago.maniches@gmail.com
+    affiliation: TOPOLOGICA LLC
+    orcid: "https://orcid.org/0009-0005-6480-1987"
+keywords:
+  - federated learning
+  - Riemannian geometry
+  - groupoid
+  - sheaf theory
+  - cohomology
+  - topological data analysis
+abstract: >-
+  Research prototype exploring groupoid-based aggregation for federated
+  learning on Riemannian manifolds. Implements transport groupoid
+  morphisms, first cohomology (H^1) for consistency detection,
+  cellular sheaf Laplacian for spectral analysis, and Karcher mean
+  aggregation via geomstats.

groupoid-0.1.0.dev1/CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing to GROUPOID
+
+Thank you for your interest in contributing to GROUPOID. This document
+describes the development workflow and guidelines for contributions.
+
+## Development Setup
+
+1. Fork and clone the repository:
+
+```bash
+git clone https://github.com/<your-username>/GROUPOID.git
+cd GROUPOID
+```
+
+2. Install all dependencies:
+
+```bash
+pip install -e ".[all]"
+```
+
+3. Install pre-commit hooks:
+
+```bash
+pre-commit install
+```
+
+## Code Style
+
+All code is formatted and checked by the following tools (enforced via
+pre-commit hooks):
+
+- **ruff**: Linting and import sorting
+- **black**: Code formatting (line length 99)
+- **mypy**: Static type checking
+- **bandit**: Security analysis
+
+Run all checks manually:
+
+```bash
+pre-commit run --all-files
+```
+
+## Running Tests
+
+```bash
+# All tests
+pytest tests/ -v
+
+# Property-based tests only
+pytest tests/theory/ -v
+
+# Benchmarks
+pytest benchmarks/ -v --benchmark-only
+```
+
+## Mathematical Contributions
+
+Contributions involving mathematical claims (new algorithms, convergence
+proofs, complexity bounds) must include:
+
+- A proof or a citation to a peer-reviewed reference
+- Property-based tests (using Hypothesis) that verify the claimed invariants
+- Clear documentation of assumptions and limitations
+
+If you find a mathematical error in the existing code or documentation,
+please open an issue using the "Mathematical Correction" template.
+
+## Pull Request Process
+
+1. Create a feature branch from `main`.
+2. Make your changes, ensuring all pre-commit hooks pass.
+3. Add or update tests as appropriate.
+4. Update documentation if your changes affect the public API.
+5. Open a pull request against `main`.
+6. Ensure CI passes (lint, test, security, docs build).
+7. Address all review comments before merging.
+
+## Issue Templates
+
+When reporting bugs or requesting features, please use the appropriate
+issue template:
+
+- **Bug Report**: For reproducible bugs with steps, expected behavior,
+  and environment details.
+- **Feature Request**: For new functionality with motivation and
+  proposed approach.
+- **Mathematical Correction**: For errors in theorems, proofs, or
+  algorithms.
+
+## License
+
+By contributing to GROUPOID, you agree that your contributions will be
+licensed under the Apache License, Version 2.0.