kaos-ml-core 0.1.0a1__tar.gz

kaos_ml_core-0.1.0a1/.github/CODEOWNERS

@@ -0,0 +1,16 @@
+# Default owner for everything in this repo
+* @mjbommar
+
+# Critical paths get explicit ownership for clarity
+/.github/        @mjbommar
+/pyproject.toml  @mjbommar
+/Cargo.toml      @mjbommar
+/Cargo.lock      @mjbommar
+/LICENSE         @mjbommar
+/NOTICE          @mjbommar
+/CHANGELOG.md    @mjbommar
+/SECURITY.md     @mjbommar
+/deny.toml       @mjbommar
+
+# Rust core / bindings — version-coupled with the Python wheel
+/rust/           @mjbommar

kaos_ml_core-0.1.0a1/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,59 @@
+name: Bug report
+description: Report a defect in kaos-ml-core
+title: "[bug] "
+labels: ["type:bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report. Please fill out the sections below.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug. Include any error messages or stack traces.
+      placeholder: When I call X with Y, Z happens instead of W.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How to reproduce
+      description: Minimal code or commands that reproduce the bug.
+      render: python
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: kaos-ml-core version
+      description: Output of `python -c "import kaos_ml_core; print(kaos_ml_core.__version__)"`
+      placeholder: e.g. 0.1.0a1
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: Output of `python --version`
+      placeholder: e.g. 3.13.1
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system + architecture
+      placeholder: e.g. Ubuntu 24.04 x86_64, macOS 14 arm64, Windows 11 x86_64
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Additional context
+      description: Anything else that might help. For Rust-side issues, include the wheel platform tag (e.g. `manylinux_2_28_x86_64`).

kaos_ml_core-0.1.0a1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/273v/kaos-ml-core/security/advisories/new
+    about: Report a security issue privately via GitHub Security Advisories. Do not file a public issue.

kaos_ml_core-0.1.0a1/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,26 @@
+name: Feature request
+description: Suggest a new capability or improvement for kaos-ml-core
+title: "[feat] "
+labels: ["type:feat", "needs-triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the use case, not the implementation.
+      placeholder: I'm trying to do X and the current API forces me to Y.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Optional. If you already have an API or implementation in mind, sketch it here.
+      render: python
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What workarounds did you try, and why aren't they enough?

kaos_ml_core-0.1.0a1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+## Summary
+
+<!-- One-paragraph description of what this PR does and why it's needed. -->
+
+## Type of change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation only
+
+## Checklist
+
+- [ ] Commits are signed off (`git commit -s`) — DCO required
+- [ ] Tests added/updated for any behavior change
+- [ ] **Rust** — `cargo fmt --check`, `cargo clippy --no-default-features --all-targets -- -D warnings`, `cargo test --no-default-features --lib`
+- [ ] **Python** — `uv run ruff format --check python/kaos_ml_core tests`, `uv run ruff check python/kaos_ml_core tests`, `uv run ty check python/kaos_ml_core tests`, `uv run pytest -m "not live and not network and not slow" tests/`
+- [ ] **Build** — `uv run maturin develop --release` succeeds
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` if user-visible
+
+## Related issues
+
+<!-- "Closes #123" or "Refs #123" -->

kaos_ml_core-0.1.0a1/.github/dependabot.yml

@@ -0,0 +1,56 @@
+version: 2
+updates:
+  # ────────────── GitHub Actions ──────────────
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+      day: monday
+      time: "06:00"
+      timezone: Etc/UTC
+    groups:
+      actions:
+        patterns: ["*"]
+    labels: ["type:deps", "ci"]
+    commit-message:
+      prefix: "ci(deps)"
+
+  # ────────────── Python (uv-managed via pyproject.toml) ──────────────
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: monthly
+      day: monday
+      time: "06:00"
+      timezone: Etc/UTC
+    groups:
+      python:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+      python-major:
+        patterns: ["*"]
+        update-types: ["major"]
+    open-pull-requests-limit: 5
+    labels: ["type:deps"]
+    commit-message:
+      prefix: "deps"
+
+  # ────────────── Rust (cargo) ──────────────
+  - package-ecosystem: cargo
+    directory: /
+    schedule:
+      interval: monthly
+      day: monday
+      time: "06:00"
+      timezone: Etc/UTC
+    groups:
+      rust:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+      rust-major:
+        patterns: ["*"]
+        update-types: ["major"]
+    open-pull-requests-limit: 5
+    labels: ["type:deps", "rust"]
+    commit-message:
+      prefix: "deps(rust)"

kaos_ml_core-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,270 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  # ────────────── lint (Python + Rust) ──────────────
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Cargo fmt
+        run: cargo fmt --check
+
+      - name: Cargo clippy (no PyO3 features)
+        run: cargo clippy --no-default-features --all-targets -- -D warnings
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python 3.13
+        run: uv python install 3.13
+
+      - name: Install dependencies (transformers + mcp extras for ty resolution)
+        # ty static-analyzes the pipeline.py / tools.py imports of
+        # kaos_nlp_transformers.models and kaos_mcp; install both extras
+        # so the symbols resolve. The runtime tests don't need this — the
+        # imports are gated by try/except — but the type checker is strict.
+        run: uv sync --group dev --extra transformers --extra mcp --python 3.13
+
+      - name: Ruff format check
+        run: uv run ruff format --check python/kaos_ml_core tests
+
+      - name: Ruff lint
+        run: uv run ruff check python/kaos_ml_core tests
+
+      - name: Type check (ty)
+        run: uv run ty check python/kaos_ml_core tests
+
+  # ────────────── pre-commit ──────────────
+  pre-commit:
+    name: Pre-commit hooks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python 3.13
+        run: uv python install 3.13
+
+      - name: Install dependencies (transformers + mcp for ty resolution)
+        run: uv sync --group dev --extra transformers --extra mcp --python 3.13
+
+      - name: Run pre-commit
+        run: uvx pre-commit run --all-files --show-diff-on-failure
+
+  # ────────────── Rust unit tests (pure Rust core) ──────────────
+  rust-test:
+    name: Rust tests (no PyO3)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cargo test (--no-default-features)
+        run: cargo test --no-default-features --lib
+
+  # ────────────── Python tests (Python × maturin develop) ──────────────
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.13"
+            experimental: false
+          - python-version: "3.14"
+            experimental: false
+          - python-version: "3.14t"
+            experimental: true
+          - python-version: "3.15"
+            experimental: true
+    continue-on-error: ${{ matrix.experimental }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install --preview ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group dev --python ${{ matrix.python-version }}
+
+      - name: Build PyO3 extension (maturin develop --release)
+        run: uv run maturin develop --release
+
+      - name: Run tests with coverage
+        run: |
+          uv run pytest \
+            -m "not live and not network and not slow" \
+            --cov=kaos_ml_core \
+            --cov-branch \
+            --cov-report=term-missing \
+            --cov-report=xml:coverage.xml \
+            tests/
+
+      - name: Upload coverage report
+        if: always() && !matrix.experimental
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: coverage.xml
+          retention-days: 14
+
+  # ────────────── min-deps ──────────────
+  min-deps:
+    name: Test against minimum dependencies
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python 3.13
+        run: uv python install 3.13
+
+      - name: Install with lowest-direct resolution
+        run: uv sync --group dev --resolution=lowest-direct --python 3.13
+
+      - name: Build PyO3 extension
+        run: uv run maturin develop --release
+
+      - name: Run tests
+        run: |
+          uv run pytest \
+            -m "not live and not network and not slow" \
+            --no-cov \
+            -q \
+            tests/
+
+  # ────────────── build + wheel smoke test ──────────────
+  build:
+    name: Build distribution + smoke test
+    runs-on: ubuntu-latest
+    needs: [lint, test, rust-test]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python 3.13
+        run: uv python install 3.13
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Verify metadata (twine check)
+        run: uvx --from twine twine check --strict dist/*
+
+      - name: Smoke-test the built wheel in a clean venv
+        run: |
+          uv venv --python 3.13 /tmp/smoke
+          # Install with [mcp] so register_ml_tools is reachable; the
+          # actual ML-pipeline smoke (embed + train + predict) lives in
+          # the integration tests, not in this fast-CI smoke.
+          uv pip install --python /tmp/smoke/bin/python "dist/kaos_ml_core-0.1.0a1-cp313-abi3-linux_x86_64.whl[mcp]"
+          /tmp/smoke/bin/python -c "
+          import kaos_ml_core
+          from kaos_ml_core import (
+              Corpus, KaosMLCoreSettings, Metrics, Pipeline, PipelineError,
+              SplitResult, ThresholdResult, aggregate_predictions, evaluate,
+              stratified_split, tune_threshold, wilson_score_interval,
+          )
+          assert kaos_ml_core.__version__, 'version missing from wheel'
+          assert len(kaos_ml_core.__all__) >= 22, f'unexpected public surface: {kaos_ml_core.__all__}'
+
+          # Hard-rule enforcement primitives are reachable.
+          lo, hi = wilson_score_interval(80, 100, confidence=0.95)
+          assert 0.7 < lo < 0.72 and 0.86 < hi < 0.87
+
+          # Four granularity levels supported.
+          from kaos_content.model.blocks import Heading, Paragraph
+          from kaos_content.model.document import ContentDocument
+          from kaos_content.model.inlines import Text
+          from kaos_content.model.metadata import DocumentMetadata, SourceRef
+          doc = ContentDocument(
+              metadata=DocumentMetadata(source=SourceRef(uri='smoke://1')),
+              body=(
+                  Heading(depth=1, children=(Text(value='Indemnification'),)),
+                  Paragraph(children=(Text(value='The Seller indemnifies Buyer.'),)),
+                  Paragraph(children=(Text(value='Cap is 10 percent.'),)),
+              ),
+          )
+          assert len(Corpus.from_documents([doc], level='paragraph')) == 2
+          assert len(Corpus.from_documents([doc], level='section')) == 1
+          assert len(Corpus.from_documents([doc], level='document')) == 1
+
+          # MCP tool surface registers 11 tools.
+          from kaos_core import KaosRuntime
+          from kaos_ml_core.tools import register_ml_tools
+          rt = KaosRuntime()
+          assert register_ml_tools(rt) == 11
+
+          # Settings + Rust extension reachable.
+          assert KaosMLCoreSettings().default_threshold == 0.5
+          from kaos_ml_core._rust import version as rust_version_fn
+          assert rust_version_fn() == kaos_ml_core.rust_version
+          print(f'kaos-ml-core {kaos_ml_core.__version__}: smoke OK ({len(kaos_ml_core.__all__)} symbols, 11 MCP tools)')
+          "
+          # Exercise the CLI entrypoint.
+          /tmp/smoke/bin/kaos-ml info --json
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist-${{ github.sha }}
+          path: dist/
+          retention-days: 7

kaos_ml_core-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,241 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  # Manual fallback so a failed publish (e.g. transient PyPI 5xx) can be
+  # retried without re-tagging.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # ────────────── Pre-publish QA + sdist ──────────────
+  # One job that gates everything else: verifies version sync, runs the
+  # full QA gauntlet, builds + verifies the sdist (the format-agnostic
+  # source artifact). Wheel-matrix jobs depend on this; if the source
+  # tree is broken we never compile 8 wheels for nothing.
+  sdist:
+    name: Build sdist + pre-publish QA
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python 3.13
+        run: uv python install 3.13
+
+      - name: Install dependencies (transformers + mcp for ty resolution)
+        run: uv sync --group dev --extra transformers --extra mcp --python 3.13
+
+      - name: Verify Cargo.toml version matches tag
+        id: version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          # Cargo SemVer "0.1.0-alpha.1" maps to PEP 440 "0.1.0a1".
+          CARGO_VERSION=$(awk -F\" '/^version = "/{print $2; exit}' Cargo.toml)
+          # Normalize Cargo SemVer "X.Y.Z-alpha.N" -> PEP 440 "X.Y.ZaN" etc.
+          PEP440_VERSION=$(echo "$CARGO_VERSION" \
+            | sed -E 's/-alpha\.([0-9]+)$/a\1/' \
+            | sed -E 's/-beta\.([0-9]+)$/b\1/' \
+            | sed -E 's/-rc\.([0-9]+)$/rc\1/')
+          TAG=${GITHUB_REF_NAME#v}
+          if [ "$PEP440_VERSION" != "$TAG" ]; then
+            echo "::error::Tag '$TAG' does not match Cargo.toml-derived PEP 440 version '$PEP440_VERSION' (Cargo SemVer '$CARGO_VERSION')"
+            exit 1
+          fi
+          echo "version=$PEP440_VERSION" >> "$GITHUB_OUTPUT"
+          echo "kaos-ml-core release: tag=$TAG, cargo=$CARGO_VERSION, pep440=$PEP440_VERSION"
+
+      - name: Pre-publish QA — Rust
+        run: |
+          cargo fmt --check
+          cargo clippy --no-default-features --all-targets -- -D warnings
+          cargo test --no-default-features --lib
+
+      - name: Pre-publish QA — Python (build extension first)
+        run: |
+          uv run maturin develop --release
+          uv run ruff format --check python/kaos_ml_core tests
+          uv run ruff check python/kaos_ml_core tests
+          uv run ty check python/kaos_ml_core tests
+          uv run pytest -m "not live and not network and not slow" --no-cov tests/
+
+      - name: Build sdist
+        run: uv run maturin sdist --out dist
+
+      - name: Verify sdist metadata
+        run: uvx --from twine twine check --strict dist/*.tar.gz
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          retention-days: 30
+
+  # ────────────── Wheel matrix ──────────────
+  # 8 wheels per release, per D017 (docs/oss/30-rust-packaging/wheel-matrix.md):
+  #   - Linux x86_64 manylinux + musllinux
+  #   - Linux aarch64 manylinux + musllinux
+  #   - macOS arm64
+  #   - Windows x86_64
+  #   - Windows arm64
+  # macOS x86_64 deliberately skipped (Apple ended Intel sales in 2023).
+  wheels:
+    name: ${{ matrix.target }} ${{ matrix.linux-tag && '(' || '' }}${{ matrix.linux-tag }}${{ matrix.linux-tag && ')' || '' }}
+    needs: sdist
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+            linux-tag: manylinux_2_28
+            manylinux: "2_28"
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-musl
+            linux-tag: musllinux_1_2
+            manylinux: musllinux_1_2
+          - os: ubuntu-24.04-arm
+            target: aarch64-unknown-linux-gnu
+            linux-tag: manylinux_2_28
+            manylinux: "2_28"
+          - os: ubuntu-24.04-arm
+            target: aarch64-unknown-linux-musl
+            linux-tag: musllinux_1_2
+            manylinux: musllinux_1_2
+          - os: macos-14
+            target: aarch64-apple-darwin
+            linux-tag: ""
+            manylinux: ""
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+            linux-tag: ""
+            manylinux: ""
+          - os: windows-11-arm
+            target: aarch64-pc-windows-msvc
+            linux-tag: ""
+            manylinux: ""
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Python (host)
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Build wheel via PyO3/maturin-action
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          # Empty for macOS/Windows; "2_28" or "musllinux_1_2" for Linux.
+          manylinux: ${{ matrix.manylinux }}
+          args: --release --strip --out dist
+          # Don't restore from cache — release builds must be reproducible
+          # from a clean state (per docs/oss/30-rust-packaging/wheel-matrix.md).
+          rust-toolchain: stable
+          sccache: "true"
+
+      - name: Upload wheel
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.target }}-${{ matrix.linux-tag || matrix.os }}
+          path: dist/*.whl
+          retention-days: 30
+
+  # ────────────── Publish to PyPI via OIDC ──────────────
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [sdist, wheels]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kaos-ml-core
+    permissions:
+      id-token: write  # OIDC for Trusted Publishing
+    steps:
+      - name: Download sdist
+        uses: actions/download-artifact@v8
+        with:
+          name: sdist
+          path: dist/
+
+      - name: Download all wheels
+        uses: actions/download-artifact@v8
+        with:
+          pattern: wheels-*
+          path: dist/
+          merge-multiple: true
+
+      - name: Show artifact set
+        run: ls -la dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+          skip-existing: false
+
+  # ────────────── GitHub Release ──────────────
+  github-release:
+    name: Create GitHub Release
+    needs: [sdist, wheels]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Download sdist
+        uses: actions/download-artifact@v8
+        with:
+          name: sdist
+          path: dist/
+
+      - name: Download all wheels
+        uses: actions/download-artifact@v8
+        with:
+          pattern: wheels-*
+          path: dist/
+          merge-multiple: true
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          PRERELEASE_FLAG=""
+          if [[ "$VERSION" == *a* || "$VERSION" == *b* || "$VERSION" == *rc* ]]; then
+            PRERELEASE_FLAG="--prerelease"
+          fi
+          gh release create "$GITHUB_REF_NAME" \
+            --title "kaos-ml-core $VERSION" \
+            --notes-from-tag \
+            $PRERELEASE_FLAG \
+            dist/*