pyqmd-mlx 0.7.0__tar.gz

pyqmd_mlx-0.7.0/.Justfile

@@ -0,0 +1,50 @@
+set shell := ["bash", "-uc"]
+
+# Just runs the first target if no arguments are provided, so we set this to list all targets for safety.
+_default:
+    @just --list
+
+# Install/upgrade dev dependencies and activate pre-commit hooks.
+[group('development')]
+develop:
+    uv sync --dev
+    uv tool install pre-commit
+    pre-commit install
+
+[group('quality')]
+test *args:
+    uv run pytest {{args}} -v
+
+[group('quality')]
+test-fast:
+    uv run pytest -v -m "not slow"
+
+[group('quality')]
+test-slow:
+    uv run pytest -v -m slow
+
+[group('quality')]
+test-parity *args:
+    uv run pytest parity/ {{args}}
+
+# Performance comparison against a Node qmd checkout at ../qmd (override with e.g. `just bench-scifact --qmd-repo-root /path/to/qmd`).
+# Uses the built-in SciFact profile by default (override with `--dataset-config path/to/profile.yaml`,
+# same as `test-parity`) -- its corpus lives in data/scifact/, gitignored and not shipped with the repo;
+# generate it first with `uv run scripts/prepare_scifact_corpus.py`.
+[group('quality')]
+bench-scifact *args:
+    uv run python -m parity.benchmark --qmd-repo-root ../qmd {{args}}
+
+[group('quality')]
+lint:
+    uv run ruff check .
+    uv run ruff format --check .
+
+# Install pyqmd as a real `pyqmd` command on PATH, editable (source changes apply without reinstalling).
+[group('install')]
+install:
+    uv tool install --editable .
+
+[group('install')]
+uninstall:
+    uv tool uninstall pyqmd-mlx

pyqmd_mlx-0.7.0/.commitlintrc.mjs

@@ -0,0 +1,47 @@
+export default {
+  extends: ["@commitlint/config-conventional"],
+  rules: {
+    // 0 = off, 1 = warn, 2 = error  |  "always" / "never"
+    "scope-enum": [
+      2,
+      "always",
+      [
+        "store", // src/pyqmd_mlx/store/ -- schema, Store class, search/query
+        "cli", // src/pyqmd_mlx/cli/ -- Typer commands, output formatting
+        "mcp", // src/pyqmd_mlx/mcp/ -- MCP server (stdio/HTTP)
+        "llm", // src/pyqmd_mlx/llm/ -- MLX embed/rerank/query-expansion layer
+        "bench", // src/pyqmd_mlx/bench/ and the bench command
+        "skills", // src/pyqmd_mlx/skills/ and the skill/skills commands
+        "parity", // parity/ -- Node-vs-pyqmd golden-snapshot suite
+        "scripts", // scripts/ -- dev utility scripts
+        "config", // pyproject.toml, .pre-commit-config.yaml, Justfile, .gitignore
+        "docs", // README/CLAUDE.md/COMMAND_STATUS.md and any docs/ that aren't specs
+        "specs", // docs/specs/ -- published design/spec docs
+        "tests", // test-only changes
+      ],
+    ],
+    "scope-empty": [0, "never"], // off - some commits legitimately have no scope
+    "type-enum": [
+      2,
+      "always",
+      [
+        // conventional commits standard types
+        "feat",
+        "fix",
+        "docs",
+        "style",
+        "refactor",
+        "perf",
+        "test",
+        "build",
+        "ci",
+        "chore",
+        "revert",
+        // escape hatch — never bumps version, never appears in changelog
+        "doh",
+        // changes a reviewer asked for on an open PR — like doh, never released or logged
+        "review",
+      ],
+    ],
+  },
+};

pyqmd_mlx-0.7.0/.github/workflows/build.yml

@@ -0,0 +1,61 @@
+name: Build
+
+# Reusable: ci.yml runs it on every PR/push, release.yml on the new tag.
+# No credentials: release.yml's publish job only downloads this artifact.
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: Commit or tag to build
+        required: true
+        type: string
+      expected-version:
+        description: If set, the wheel's `pyqmd --version` must print exactly this
+        required: false
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    # Apple Silicon, the only platform pyqmd supports. GitHub's macOS
+    # runners have no Metal access: this proves install + CLI startup,
+    # never that the MLX models run (those are `just test-slow`, locally).
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.ref }}
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.12"
+      # Same reason as ci.yml's macOS test leg: the runner's preinstalled
+      # Python lacks sqlite3 loadable-extension support.
+      - name: Force managed Python
+        run: echo "UV_PYTHON_PREFERENCE=only-managed" >> "$GITHUB_ENV"
+      - run: uv build
+      - run: uvx twine check --strict dist/*
+      # Installs the wheel with the *latest* dependencies (no uv.lock), like
+      # a user's `uv tool install pyqmd-mlx` -- the one check that catches a
+      # new dependency release breaking pyqmd.
+      - name: Smoke-test the wheel
+        env:
+          EXPECTED_VERSION: ${{ inputs.expected-version }}
+        run: |
+          export UV_TOOL_DIR="$RUNNER_TEMP/uv-tools" UV_TOOL_BIN_DIR="$RUNNER_TEMP/uv-bin"
+          uv tool install dist/*.whl
+          "$UV_TOOL_BIN_DIR/pyqmd" --help > /dev/null
+          version=$("$UV_TOOL_BIN_DIR/pyqmd" --version)
+          echo "pyqmd --version: $version"
+          if [ -n "$EXPECTED_VERSION" ] && [ "$version" != "$EXPECTED_VERSION" ]; then
+            echo "::error::expected pyqmd --version $EXPECTED_VERSION, got $version"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error

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

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.12"
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  test:
+    needs: [lint]
+    strategy:
+      # Pinned, not floating: mlx ships manylinux_2_35+ wheels only, so
+      # ubuntu-24.04 (glibc 2.39) is the floor -- an older ubuntu image
+      # cannot even resolve uv.lock. macos-latest is ARM, covering the
+      # Apple Silicon import path.
+      matrix:
+        os: [ubuntu-24.04, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.12"
+      # macOS only: uv's discovery prefers the runner-preinstalled
+      # python-build-standalone (higher patch version wins), whose macOS
+      # builds lack sqlite3 loadable extension support -- every Store()
+      # construction then dies in load_sqlite_vec with AttributeError.
+      # only-managed forces the astral build setup-uv just installed
+      # (verified to have enable_load_extension). Ubuntu is untouched
+      # (green as-is). Done as a conditional step rather than job-level
+      # env so the ubuntu leg keeps default discovery byte-for-byte.
+      - name: Force managed Python on macOS
+        if: matrix.os == 'macos-latest'
+        run: echo "UV_PYTHON_PREFERENCE=only-managed" >> "$GITHUB_ENV"
+      - run: uv sync --dev
+      # No data/ or models/ on a fresh checkout (both gitignored): the
+      # scifact corpus (self-generatable but 33MB + slow) and the
+      # self-converted expansion weights (not fetchable anywhere) are
+      # absent, so requires_scifact_corpus / requires_expansion_weights
+      # tests skip with a clear reason (see tests/conftest.py).
+      - run: uv run pytest -m "not slow" -q
+
+  build:
+    uses: ./.github/workflows/build.yml
+    with:
+      ref: ${{ github.event.pull_request.head.sha || github.sha }}

pyqmd_mlx-0.7.0/.github/workflows/pr-title.yml

@@ -0,0 +1,24 @@
+name: PR title
+
+# A squash merge of a multi-commit PR takes the PR title as its commit
+# subject, and semantic-release reads that subject to decide the release.
+# The commit-msg hook never sees it, so lint it here.
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  pr-title:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: lts/*
+      - run: npm install --no-save --no-package-lock @commitlint/cli@21.2.3 @commitlint/config-conventional@21.2.3
+      - run: printf '%s\n' "$PR_TITLE" | npx --no-install commitlint --config .commitlintrc.mjs
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}

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

@@ -0,0 +1,87 @@
+name: Release
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches: [main]
+
+# Each job declares its own permissions.
+permissions: {}
+
+jobs:
+  release:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    concurrency: release
+    permissions:
+      contents: write
+    outputs:
+      released: ${{ steps.result.outputs.released }}
+      tag: ${{ steps.result.outputs.tag }}
+      version: ${{ steps.result.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+          token: ${{ secrets.RELEASE_PAT }}
+      - id: before
+        run: echo "head=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.12"
+      - run: uv tool install python-semantic-release==10.6.1
+      - run: semantic-release version --skip-build --no-commit --no-tag --no-changelog
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_PAT }}
+      - run: |
+          uv lock --upgrade-package pyqmd-mlx
+          git add uv.lock
+      - run: semantic-release version
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_PAT }}
+      # A release moves HEAD to PSR's release commit; no release leaves it.
+      - id: result
+        env:
+          BEFORE: ${{ steps.before.outputs.head }}
+        run: |
+          if [ "$(git rev-parse HEAD)" != "$BEFORE" ]; then
+            tag=$(git tag --points-at HEAD --list 'v*' | head -1)
+            {
+              echo "released=true"
+              echo "tag=$tag"
+              echo "version=${tag#v}"
+            } >> "$GITHUB_OUTPUT"
+          else
+            echo "released=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  build:
+    needs: release
+    if: ${{ needs.release.outputs.released == 'true' }}
+    permissions:
+      contents: read
+    uses: ./.github/workflows/build.yml
+    with:
+      # The tag, not main: another merge may land after `release` checked out.
+      ref: ${{ needs.release.outputs.tag }}
+      expected-version: ${{ needs.release.outputs.version }}
+
+  publish:
+    needs: [release, build]
+    runs-on: ubuntu-latest # the PyPA action is a Docker action
+    # PyPI's trusted publisher matches workflow release.yml + environment pypi,
+    # so only this job can get a PyPI token. No checkout, no repo code.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pyqmd-mlx/${{ needs.release.outputs.version }}/
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.14.2

pyqmd_mlx-0.7.0/.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# uv / venv
+.venv/
+
+# tooling caches
+.pytest_cache/
+.ruff_cache/
+
+# env / secrets
+.env
+
+# editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# generated data and models (large, re-fetchable)
+data/
+models/
+
+# A user's own dataset profile + private data for the parity suite --
+# never committed. .gitkeep above keeps the directory itself tracked.
+parity/datasets/local/*
+!parity/datasets/local/.gitkeep
+
+# A user's own captured Node baseline lands in parity/node_ref/<profile>/
+# regardless of where their profile YAML lives -- ignore every profile's
+# captured data there except the built-in scifact one (the project's own
+# tracked golden-reference data). Without this, README's "your data and
+# captured baseline never get committed" claim was false for anything
+# outside parity/datasets/local/ itself.
+parity/node_ref/*
+!parity/node_ref/scifact/
+
+# Scratch Node collection-registry/index-DB state the capture script
+# creates as isolation artifacts, not intended captured output --
+# baked-in absolute paths make these non-portable across machines.
+parity/node_ref/*/config/
+parity/node_ref/*/_capture*.sqlite*
+parity/node_ref/*/_structural_capture/
+parity/node_ref/*/_quality_capture/
+parity/node_ref/*/_mcp_capture/
+parity/node_ref/*/_flow_*_capture/
+
+# benchmark.py's generated report -- machine- and moment-dependent timing
+# numbers, not something to track in git.
+parity/BENCHMARK_RESULTS.md
+
+# isolated git worktrees (per using-git-worktrees skill)
+.worktrees/
+
+# Private specs, plans, notes, leak-check tooling and history archive --
+# see CLAUDE.md "Workflow". Public specs live in docs/specs/.
+docs/superpowers/

pyqmd_mlx-0.7.0/.pre-commit-config.yaml

@@ -0,0 +1,71 @@
+---
+# Run 'just develop' to install pre-commit and activate these hooks.
+default_install_hook_types: [pre-commit, commit-msg, pre-push]
+default_stages: [pre-commit]
+
+repos:
+  # --- General hygiene ---
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-merge-conflict
+      - id: check-added-large-files
+      - id: detect-private-key
+      - id: mixed-line-ending
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+
+  # --- Python lint/format ---
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.16
+    hooks:
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+        types_or: [python, pyi]
+      - id: ruff-format
+
+  # --- Commit message linting (Conventional Commits) ---
+  # Uses `npx --yes commitlint` directly (already available on PATH) rather than
+  # a pre-commit-managed hook repo. This mirrors the system/local hook pattern
+  # used for prettier below.
+  # Requires @commitlint/cli and @commitlint/config-conventional installed
+  # globally (npm i -g @commitlint/cli @commitlint/config-conventional) --
+  # language: system means pre-commit can't manage this dependency itself.
+  - repo: local
+    hooks:
+      - id: commitlint
+        name: commitlint
+        language: system
+        entry: npx --yes commitlint --edit --config .commitlintrc.mjs
+        stages: [commit-msg]
+        pass_filenames: false
+        always_run: true
+
+  # --- Prettier, for markdown/yaml/json only ---
+  # Uses whatever `prettier` is on PATH rather than a pre-commit-managed
+  # mirror repo.
+  - repo: local
+    hooks:
+      - id: prettier
+        name: prettier
+        language: system
+        entry: prettier --write --ignore-unknown
+        types_or: [markdown, yaml, json]
+        stages: [pre-commit]
+
+  # --- Block direct pushes to main (client-side backstop) ---
+  # Local safety net only -- bypassable with `git push --no-verify` and only
+  # active for whoever has run `just develop` in their own checkout. The
+  # actual enforcement point is GitHub branch protection on the upstream repo.
+  - repo: local
+    hooks:
+      - id: block-main-push
+        name: block direct pushes to main
+        language: system
+        entry: scripts/block-main-push.sh
+        pass_filenames: false
+        always_run: true
+        stages: [pre-push]

pyqmd_mlx-0.7.0/.python-version

@@ -0,0 +1 @@
+3.12

pyqmd_mlx-0.7.0/.semrel/.components/changelog_header.md.j2

@@ -0,0 +1,9 @@
+# CHANGELOG
+
+{%    if ctx.changelog_mode == "update"
+%}{#  # IMPORTANT: add insertion flag for next version update
+#}{{
+        insertion_flag ~ "\n"
+
+}}{%  endif
+%}

pyqmd_mlx-0.7.0/.semrel/.components/changelog_init.md.j2

@@ -0,0 +1,29 @@
+{#
+This changelog template initializes a full changelog for the project,
+it follows the following logic:
+  1. Header
+  2. Any Unreleased Details (uncommon)
+  3. all previous releases except the very first release
+  4. the first release
+
+#}{#
+   #    Header
+#}{%    include "changelog_header.md.j2"
+-%}{#
+   #    Any Unreleased Details (uncommon)
+#}{%    include "unreleased_changes.md.j2"
+-%}{#
+    #   Since this is initialization, we are generating all the previous
+    #   release notes per version. The very first release notes is specialized
+#}{%    if releases | length > 0
+%}{%      for release in releases
+%}{{        "\n"
+}}{%        if loop.last and ctx.mask_initial_release
+%}{%-         include "first_release.md.j2"
+-%}{%       else
+%}{%-         include "versioned_changes.md.j2"
+-%}{%       endif
+%}{{       "\n"
+}}{%      endfor
+%}{%    endif
+%}

pyqmd_mlx-0.7.0/.semrel/.components/changelog_update.md.j2

@@ -0,0 +1,71 @@
+{#
+This Update changelog template uses the following logic:
+
+  1. Read previous changelog file (ex. project_root/CHANGELOG.md)
+  2. Split on insertion flag (ex. <!-- version list -->)
+  3. Print top half of previous changelog
+  3. New Changes (unreleased commits & newly released)
+  4. Print bottom half of previous changelog
+
+  Note: if a previous file was not found, it does not write anything at the bottom
+        but render does NOT fail
+
+#}{%  set prev_changelog_contents = prev_changelog_file | read_file | safe
+%}{%  set changelog_parts = prev_changelog_contents.split(insertion_flag, maxsplit=1)
+%}{#
+#}{%  if changelog_parts | length < 2
+%}{#    # insertion flag was not found, check if the file was empty or did not exist
+#}{%    if prev_changelog_contents | length > 0
+%}{#      # File has content but no insertion flag, therefore, file will not be updated
+#}{{      changelog_parts[0]
+}}{%    else
+%}{#      # File was empty or did not exist, therefore, it will be created from scratch
+#}{%      include "changelog_init.md.j2"
+%}{%    endif
+%}{%  else
+%}{#
+   #    Previous Changelog Header
+   #      - Depending if there is header content, then it will separate the insertion flag
+   #        with a newline from header content, otherwise it will just print the insertion flag
+#}{%    set prev_changelog_top = changelog_parts[0] | trim
+%}{%    if prev_changelog_top | length > 0
+%}{{
+          "%s\n\n%s\n" | format(prev_changelog_top, insertion_flag | trim)
+
+}}{%    else
+%}{{
+          "%s\n" | format(insertion_flag | trim)
+
+}}{%    endif
+%}{#
+   #    Any Unreleased Details (uncommon)
+#}{%    include "unreleased_changes.md.j2"
+-%}{#
+#}{%    if releases | length > 0
+%}{#      # Latest Release Details
+#}{%      set release = releases[0]
+%}{#
+#}{%      if releases | length == 1 and ctx.mask_initial_release
+%}{#        # First Release detected
+#}{{        "\n"
+}}{%-       include "first_release.md.j2"
+-%}{{       "\n"
+}}{#
+#}{%      elif "# " ~ release.version.as_semver_tag() ~ " " not in changelog_parts[1]
+%}{#        # The release version is not already in the changelog so we add it
+#}{{        "\n"
+}}{%-       include "versioned_changes.md.j2"
+-%}{{       "\n"
+}}{#
+#}{%      endif
+%}{%    endif
+%}{#
+   #    Previous Changelog Footer
+   #      - skips printing footer if empty, which happens when the insertion_flag
+   #        was at the end of the file (ignoring whitespace)
+#}{%    set previous_changelog_bottom = changelog_parts[1] | trim
+%}{%    if previous_changelog_bottom | length > 0
+%}{{      "\n%s\n" | format(previous_changelog_bottom)
+}}{%    endif
+%}{%  endif
+%}