kymora 0.7.0__tar.gz

kymora-0.7.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owners for everything in this repository.
+* @Aamodx6

kymora-0.7.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,50 @@
+name: Bug report
+description: Something produces wrong values, crashes, or fails to install
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. For a wrong-value report, the most useful thing
+        you can include is what you expected and how you computed it — a
+        numpy/scipy expression turns the report straight into a test case.
+  - type: input
+    id: version
+    attributes:
+      label: kymora version
+      description: "`python -c \"import kymora; print(kymora.__version__)\"`"
+      placeholder: "0.5.0"
+    validations:
+      required: true
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: OS, Python version, install method, architecture
+      placeholder: |
+        Windows 11, Python 3.14.6, pip install kymora, x86_64
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: Actual behaviour, error message / stack trace
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+      description: Expected values and how you computed them (numpy/scipy expression is ideal)
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Smallest runnable snippet that shows the problem
+      render: python
+    validations:
+      required: true

kymora-0.7.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+links:
+  - name: Security report (private)
+    url: https://github.com/Aamodx6/Kymora/security/advisories/new
+    about: Vulnerability reports — never file these as public issues
+  - name: Documentation
+    url: https://aamodx6.github.io/Kymora/
+    about: Install, quickstart, API reference

kymora-0.7.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,44 @@
+name: Feature proposal
+description: Propose a change before writing code (required for new features)
+title: "[Proposal]: "
+labels: ["proposal"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The 33-feature catalog is **closed on purpose** — the low-redundancy set
+        *is* the product differentiation. PRs that add a feature without an
+        accepted proposal may be closed on scope grounds regardless of quality
+        (see CONTRIBUTING.md → "Adding a feature"). Refactors, docs, and
+        platform fixes do not need a proposal — open a regular issue or PR.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do that the library cannot express today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: What should be added/changed, and the public API shape if any
+    validations:
+      required: true
+  - type: textarea
+    id: redundancy
+    attributes:
+      label: Redundancy assessment
+      description: >
+        For feature proposals: how does this differ from the existing 33
+        (correlation with the closest existing feature, or why it measures
+        something none of them do)?
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checklist
+      options:
+        - label: I searched existing issues for duplicates
+          required: true
+        - label: I read CONTRIBUTING.md (architecture rules, feature policy)
+          required: true

kymora-0.7.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## What & why
+
+<!-- Explain *why*, not just what — the diff shows the what. -->
+
+## Checklist
+
+- [ ] One logical change per PR (a feature and a refactor is two PRs)
+- [ ] New behaviour has a test that fails without the change
+- [ ] `pytest tests/ -q` passes (after rebuilding: `maturin develop --release`)
+- [ ] `cargo test --no-default-features`, `cargo fmt --all -- --check`,
+      `cargo clippy --no-default-features --all-targets -- -D warnings` pass
+- [ ] `python tools/validation_report.py` passes (feature behaviour unchanged)
+- [ ] Version impact noted below per the CONTRIBUTING versioning table
+      (feature order/length is public API)
+
+## Version impact
+
+<!-- patch / minor / major / none — see CONTRIBUTING.md → Versioning policy -->

kymora-0.7.0/.github/actions/setup-venv/action.yml

@@ -0,0 +1,25 @@
+name: 'Set up virtualenv'
+description: 'Create .venv, put its bin dir on PATH, export VIRTUAL_ENV (maturin requires a venv)'
+
+runs:
+  using: composite
+  steps:
+    - name: Create a virtualenv (maturin requires one)
+      shell: bash
+      run: |
+        python -m venv .venv
+        # Native tools (maturin) cannot read the MSYS-style path bash reports
+        # on Windows, so emit a Windows path there via `pwd -W`.
+        if [ -d .venv/bin ]; then
+          root="$PWD"; bin="$root/.venv/bin"
+        else
+          root="$(pwd -W)"; bin="$root/.venv/Scripts"
+        fi
+        echo "$bin" >> "$GITHUB_PATH"
+        echo "VIRTUAL_ENV=$root/.venv" >> "$GITHUB_ENV"
+    - name: Confirm the venv is the active interpreter
+      shell: bash
+      run: |
+        # A wrong path here would silently install into the runner's Python and
+        # test a different build than the one maturin produced.
+        python -c "import sys; assert sys.prefix.replace(chr(92), '/').endswith('/.venv'), sys.prefix"

kymora-0.7.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+
+  - package-ecosystem: cargo
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      cargo:
+        patterns: ["*"]
+
+  # pip/PyPI is intentionally absent: dependencies live in pyproject.toml
+  # behind the maturin backend; Renovate/dependabot pip support for that
+  # layout is limited and the runtime dep set is numpy-only.

kymora-0.7.0/.github/workflows/benchmark.yml

@@ -0,0 +1,47 @@
+name: Benchmark
+
+# Manual / weekly, never gating. Publishes numbers a stranger can reproduce on a
+# known runner instead of one laptop.
+on:
+  workflow_dispatch:
+    inputs:
+      n_series:
+        description: "Number of series"
+        default: "1000"
+      n_steps:
+        description: "Steps per series"
+        default: "500"
+  schedule:
+    - cron: "37 4 * * 1"
+
+jobs:
+  bench:
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: ./.github/actions/setup-venv
+      - run: |
+          python -m pip install --upgrade pip maturin
+          python -m pip install -e ".[bench]"
+          maturin develop --release
+      - name: Record runner spec
+        run: |
+          echo "cores: $(nproc)" | tee -a "$GITHUB_STEP_SUMMARY"
+          python -c "import platform;print('python:', platform.python_version())" | tee -a "$GITHUB_STEP_SUMMARY"
+      - run: |
+          python benchmarks/bench_libraries.py \
+            --n-series ${{ github.event.inputs.n_series || '1000' }} \
+            --n-steps ${{ github.event.inputs.n_steps || '500' }} \
+            --json benchmarks/results/latest.json \
+            --markdown benchmarks/results/latest.md
+      - run: cat benchmarks/results/latest.md >> "$GITHUB_STEP_SUMMARY"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: benchmark-results
+          path: benchmarks/results/

kymora-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,115 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  rust:
+    name: rust (fmt, clippy, unit tests)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --all -- --check
+      # The pyo3 extension-module feature omits libpython at link time, which
+      # breaks `cargo test` binaries; test the pure-Rust core without it.
+      - run: cargo clippy --no-default-features --all-targets -- -D warnings
+      - run: cargo test --no-default-features
+
+  test:
+    name: py${{ matrix.python }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: ${{ matrix.os }}-${{ matrix.python }}
+      - uses: ./.github/actions/setup-venv
+      - name: Install package and test deps
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install maturin
+          python -m pip install -e ".[test]"
+      - name: Build extension in release mode
+        run: maturin develop --release
+      - name: Run tests
+        run: python -m pytest tests/ -q
+
+  validation-report:
+    name: reference-validation report
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: ./.github/actions/setup-venv
+      - run: |
+          python -m pip install --upgrade pip maturin
+          python -m pip install -e ".[test]"
+          maturin develop --release
+      - run: python tools/validation_report.py --out validation-report.md
+      - name: Publish report to the job summary
+        run: cat validation-report.md >> "$GITHUB_STEP_SUMMARY"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: validation-report
+          path: validation-report.md
+
+  typecheck:
+    name: mypy against the type stubs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: ./.github/actions/setup-venv
+      - run: |
+          python -m pip install --upgrade pip maturin mypy pandas-stubs
+          python -m pip install -e ".[pandas]"
+          maturin develop --release
+      - run: mypy python/kymora
+
+  snippets:
+    name: README + docs snippets execute
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: ./.github/actions/setup-venv
+      - run: |
+          python -m pip install --upgrade pip maturin scikit-learn
+          python -m pip install -e ".[test]"
+          maturin develop --release
+      - run: python tools/check_snippets.py

kymora-0.7.0/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths: ["docs/**", "mkdocs.yml", ".github/workflows/docs.yml", "README.md"]
+  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@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      # Docs need only mkdocs itself — the primary path used to install the
+      # project (maturin backend, no Rust here) with --no-deps, which could
+      # never bring mkdocs in; this installs exactly the pyproject docs floors.
+      - run: python -m pip install --upgrade pip && python -m pip install "mkdocs>=1.6" "mkdocs-material>=9.5"
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v5
+        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@v5

kymora-0.7.0/.github/workflows/release.yml

@@ -0,0 +1,156 @@
+name: Release
+
+# Wheels are built on every push to main (so a broken build surfaces before a
+# tag), and published to PyPI only when a GitHub Release is published.
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  linux:
+    name: wheel ${{ matrix.target }} (manylinux)
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          manylinux: "2014"
+          # aarch64 needs emulation/cross; x86_64 builds natively.
+          sccache: "true"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-linux-${{ matrix.target }}
+          path: dist
+
+  macos:
+    name: wheel ${{ matrix.target }} (macOS)
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          sccache: "true"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-macos-${{ matrix.target }}
+          path: dist
+
+  windows:
+    name: wheel x64 (Windows)
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          architecture: x64
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: x64
+          args: --release --out dist
+          sccache: "true"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-windows-x64
+          path: dist
+
+  sdist:
+    name: sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-sdist
+          path: dist
+
+  smoke-test:
+    name: install wheel and import (${{ matrix.os }}, py${{ matrix.python }})
+    needs: [linux, macos, windows]
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {os: ubuntu-latest, python: "3.13", artifact: wheels-linux-x86_64}
+          - {os: macos-latest, python: "3.13", artifact: wheels-macos-aarch64}
+          - {os: windows-latest, python: "3.13", artifact: wheels-windows-x64}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/download-artifact@v8
+        with:
+          name: ${{ matrix.artifact }}
+          path: dist
+      # Installs from the built wheel only — no Rust toolchain on this runner,
+      # so a missing/incompatible wheel fails here instead of at a user's pip.
+      - name: Install from wheel
+        shell: bash
+        run: |
+          # Dependencies come from PyPI; kymora itself must come from the
+          # freshly built wheel, so install it with --no-index --no-deps.
+          python -m pip install --upgrade pip
+          python -m pip install "numpy>=1.24"
+          python -m pip install --no-index --no-deps --find-links dist kymora
+      - name: Import and extract outside the source tree
+        shell: bash
+        run: |
+          cd "$(mktemp -d)"
+          python -c "
+          import numpy as np, kymora
+          X = np.random.default_rng(0).standard_normal((64, 128))
+          f = kymora.extract_features(X)
+          assert f.shape == (64, len(kymora.feature_names())), f.shape
+          assert np.isfinite(f).all()
+          print('ok', kymora.__version__, f.shape)
+          "
+
+  publish:
+    name: publish to PyPI
+    if: github.event_name == 'release' && github.event.action == 'published'
+    needs: [linux, macos, windows, sdist, smoke-test]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Trusted Publishing (OIDC) — no PyPI API token is stored in this repo.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: wheels-*
+          merge-multiple: true
+          path: dist
+      - run: ls -l dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

kymora-0.7.0/.gitignore

@@ -0,0 +1,16 @@
+/target
+/.venv
+__pycache__/
+*.pyd
+*.so
+dist/
+.pytest_cache/
+*.pdb
+.hypothesis/
+site/
+node_modules/
+landing/dist/
+.gstack/
+benchmarks/.venvs/
+benchmarks/datasets/cache/
+.DS_Store