seqforge 2026.7.1__tar.gz

seqforge-2026.7.1/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+# THE mechanism. Most of seqforge's non-negotiable rules are enforced by tests (the parse/count line,
+# the KB round-trip over every spec, the rung-0-2 separability guard, the read/byte budget), and
+# nothing else runs them automatically: pre-commit deliberately carries only the fast hooks, so a red
+# commit can exist on a branch. This is where it is caught -- and on a machine that is not yours.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: lint + typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: prefix-dev/setup-pixi@v0.10.0
+        with:
+          environments: default
+          locked: true
+      - name: ruff (lint)
+        run: pixi run -e default lint
+      - name: ruff format check
+        run: pixi run -e default fmt-check
+      - name: mypy --strict
+        run: pixi run -e default typecheck
+
+  # markdownlint is a Node tool, so it runs on its own runner rather than through pixi. It lints the
+  # human-facing docs (the site pages, the KB assay READMEs that render into them, and the top-level
+  # README) per `.markdownlint-cli2.yaml`; running with no file args makes cli2 read the globs/ignores
+  # from that config. Pinned so a new rule cannot turn CI red without a deliberate bump.
+  markdown:
+    name: markdownlint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: markdownlint (docs + README)
+        run: npx --yes markdownlint-cli2@0.23.1
+
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: prefix-dev/setup-pixi@v0.10.0
+        with:
+          environments: test
+          locked: true
+      - name: pytest
+        run: pixi run -e test test
+
+  build:
+    name: build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: prefix-dev/setup-pixi@v0.10.0
+        with:
+          environments: default
+          locked: true
+      - name: build
+        run: pixi run -e default build

seqforge-2026.7.1/.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Docs
+
+# Builds the MkDocs site and publishes it to the `gh-pages` branch on every push to main.
+# Mirrors liulab-runtime's mechanism (a gh-pages branch), not liulab-genome's (a Pages artifact):
+# the two siblings differ, and CLAUDE.md's own wording says gh-pages.
+#
+# Setup (one-off, by a maintainer):
+#   1. Let this workflow run once so it creates the `gh-pages` branch.
+#   2. Settings -> Pages -> Source: "Deploy from a branch".
+#   3. Branch: `gh-pages`, folder: `/ (root)`. Save.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: gh-pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Build & deploy to gh-pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: prefix-dev/setup-pixi@v0.10.0
+        with:
+          environments: docs
+          locked: true
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - name: mkdocs gh-deploy
+        run: pixi run -e docs mkdocs gh-deploy --force --strict

seqforge-2026.7.1/.github/workflows/release.yml

@@ -0,0 +1,123 @@
+name: Release
+
+# Publish seqforge to PyPI. The wheel + sdist are built ONCE, then the same artifacts are uploaded via
+# PyPI Trusted Publishing (OIDC) — no long-lived API token is stored in the repo.
+#
+# How a release happens:
+#   1. Bump `version` in pyproject.toml and add the matching CHANGELOG.md entry (CalVer YYYY.M.PATCH).
+#   2. Tag it `v<version>` (e.g. v2026.7.0) and create a GitHub Release from that tag.
+#   3. Publishing the Release fires this workflow -> build -> publish to PyPI.
+# `workflow_dispatch` is the manual door: pick `testpypi` to dry-run the upload to TestPyPI, or `pypi`
+# to publish without cutting a GitHub Release.
+#
+# ONE-TIME SETUP by a maintainer (Trusted Publishing needs no secrets, but does need registration):
+#   - PyPI:      https://pypi.org/manage/account/publishing/  -> add a "pending publisher":
+#                  project `seqforge`, owner `liuhlab`, repo `seqforge`,
+#                  workflow `release.yml`, environment `pypi`.
+#   - TestPyPI:  https://test.pypi.org/manage/account/publishing/  -> same, environment `testpypi`.
+#   - Settings -> Environments: create `pypi` and `testpypi` (optionally add required reviewers on
+#     `pypi` so a human approves every real publish).
+# The `environment:` on each publish job must match the name registered above, or PyPI rejects the
+# OIDC token.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Index to publish to"
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+# Least privilege by default; the publish jobs opt into `id-token: write` for OIDC themselves.
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      # A plain Python is enough: `python -m build` runs hatchling in an isolated build env and does
+      # NOT install seqforge's runtime dependencies — so this job never has to reach the lab git
+      # packages, and the build stays fast and self-contained.
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build twine
+
+      # On a Release, the git tag is the source of truth for the version a human intended to ship.
+      # Refuse to build if it disagrees with pyproject's `version` — that mismatch is how you publish
+      # 2026.7.0 under a `v2026.7.1` tag and never notice. `v` prefix optional. Skipped on manual runs.
+      - name: Check tag matches pyproject version
+        if: github.event_name == 'release'
+        run: |
+          pkg_version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          tag="${GITHUB_REF_NAME#v}"
+          echo "pyproject version: $pkg_version"
+          echo "release tag:       $GITHUB_REF_NAME (normalized: $tag)"
+          if [ "$pkg_version" != "$tag" ]; then
+            echo "::error::Release tag '$GITHUB_REF_NAME' does not match pyproject version '$pkg_version'. Bump pyproject.toml or retag."
+            exit 1
+          fi
+
+      - name: Build
+        run: python -m build
+
+      # `twine check` validates the rendered metadata (long-description, classifiers) the way PyPI
+      # will, and — because we stripped the git deps from [project].dependencies — this is also where a
+      # regressed `git+https` direct reference would surface before the upload step.
+      - name: Check distributions
+        run: twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-testpypi:
+    name: publish to TestPyPI
+    # Manual dry-run only. Real releases go straight to PyPI via publish-pypi.
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write   # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: publish to PyPI
+    # A published GitHub Release, or a manual run that explicitly targets pypi.
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

seqforge-2026.7.1/.gitignore

@@ -0,0 +1,27 @@
+# pixi
+.pixi/
+*.egg-info/
+# python
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+build/
+dist/
+# seqforge working state (resumable, content-addressed — never committed).
+#
+# ANCHORED, and it has to be. An unanchored `seqforge/` matches a directory of that name at ANY
+# depth, which in this repo is `src/seqforge/` — git would ignore our own source tree, silently.
+# The leading slash pins it to the repo root, which is where a `-C .` run puts it.
+/seqforge/
+.seqforge/
+# docs build
+site/
+# editor / OS
+.DS_Store
+.vscode/settings.local.json
+
+# Slurm job logs (lab convention: `mkdir -p sbatch` in the submit dir)
+sbatch/

seqforge-2026.7.1/.markdownlint-cli2.yaml

@@ -0,0 +1,39 @@
+# markdownlint for the human-facing docs (and the published README).
+#
+# The whole default rule set runs (`default: true`) — this is markdownlint applied in general, not a
+# hand-picked subset. The one tuning is line length: prose here is hand-wrapped at 100 (the same width
+# ruff enforces for Python), so MD013 is set to 100 rather than its default 80, and exempted inside
+# code blocks and tables where wrapping would break meaning. Long bare URLs are exempt automatically.
+#
+# Scope is deliberate: the docs site, the KB assay READMEs that render into it, and the top-level
+# README — the prose a person reads. It does NOT lint the agent-facing files (CLAUDE.md, AGENTS.md,
+# docs/design.md), whose format serves a different reader.
+#
+# Runs in CI (.github/workflows/ci.yml, the `markdown` job) and locally as a pre-commit hook.
+
+config:
+  default: true
+  # Line length is NOT gated, matching the codebase's own policy: ruff sets line-length 100 but
+  # ignores E501 (see CLAUDE.md), so Python lines may run over and prose follows the same rule —
+  # hand-wrapped near 100, never failed for a trailing word or an unbreakable URL. Every other
+  # markdownlint rule (headings, lists, fenced-code language, table style, inline-HTML, …) stays on.
+  MD013: false
+
+globs:
+  - "docs/**/*.md"
+  - "src/seqforge/kb/specs/**/README.md"
+  - "README.md"
+
+ignores:
+  # Agent-facing internal design doc — excluded from the site, and not written to docs-page rules.
+  - "docs/design.md"
+  # The KB assay pages are one-line snippet-include wrappers (they pull in the canonical README next
+  # to each spec.yaml); there is no prose of their own to lint. The README they include IS linted,
+  # directly, via the specs glob above.
+  - "docs/kb/10x-3p-gex-v2.md"
+  - "docs/kb/10x-3p-gex-v3.md"
+  - "docs/kb/bd-rhapsody-wta.md"
+  - "docs/kb/splitseq.md"
+  - "docs/kb/bulk-rnaseq-pe.md"
+  # The v3.1 README is a symlink to the v3 README — linting the target once is enough.
+  - "src/seqforge/kb/specs/10x-3p-gex-v3.1/README.md"

seqforge-2026.7.1/.pre-commit-config.yaml

@@ -0,0 +1,56 @@
+# Pre-commit hooks for seqforge.
+#
+# Install once per clone:  pixi run -- pre-commit install
+# Run on all files:        pixi run -- pre-commit run --all-files
+#
+# Ruff is installed by pre-commit in its own ephemeral env (pinned below); mypy runs through pixi so
+# it sees the project's resolved env — the same shape liulab-genome uses.
+#
+# WHY pytest is NOT here: most of this repo's rules are enforced by tests, so the suite is the
+# mechanism — but a mechanism that runs on every commit taxes every commit, including the ones that
+# touch only prose. The suite runs in CI (`.github/workflows/ci.yml`) on push and PR; run it locally
+# with `pixi run check` when you have changed behaviour. The tradeoff is explicit: a broken commit can
+# now land on a branch and is caught at push instead of at commit.
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=500]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.16
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.10.0.1
+    hooks:
+      - id: shellcheck
+
+  # markdownlint over the human-facing docs. A fast hook, so it belongs here. pass_filenames: false
+  # makes it lint the scope declared in `.markdownlint-cli2.yaml` (globs + ignores) rather than only
+  # the changed files, so local and CI (the `markdown` job) check exactly the same set.
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.23.1
+    hooks:
+      - id: markdownlint-cli2
+        pass_filenames: false
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy --strict (via pixi)
+        entry: pixi run --no-progress typecheck
+        language: system
+        types: [python]
+        pass_filenames: false
+        require_serial: true

seqforge-2026.7.1/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/.pixi/envs/default/bin/python",
+  "python.terminal.activateEnvironment": false,
+  "python.analysis.extraPaths": ["${workspaceFolder}/src"],
+  "python.testing.pytestEnabled": true,
+  "python.testing.pytestArgs": ["tests"],
+  "search.exclude": {
+    "**/.pixi": true
+  },
+  "files.watcherExclude": {
+    "**/.pixi/**": true
+  },
+  "python-envs.defaultEnvManager": "ms-python.python:system"
+}

seqforge-2026.7.1/AGENTS.md

@@ -0,0 +1,9 @@
+# AGENTS.md
+
+This repository's agent guidance lives in [`CLAUDE.md`](CLAUDE.md) — read it in full. It is
+tool-agnostic (the only Claude Code-specific parts are the hook names `PreToolUse` / `PostToolUse` /
+`Stop`; the rules R1–R15 and conventions apply to any coding agent).
+
+Kept as a single canonical document on purpose: do **not** generate this file by find-replacing
+"Claude"→"Codex" across `CLAUDE.md` — that corrupts real paths like `.seqforge/` and would misstate
+the rules. Point here instead.