alambiq 0.1.0__tar.gz

alambiq-0.1.0/.dockerignore

@@ -0,0 +1,43 @@
+# Allowlist: never send private runs, models, credentials or Git history.
+**
+!pyproject.toml
+!uv.lock
+!README.md
+!LICENSE
+!src/
+!src/**
+!environments/
+!environments/docker/
+!environments/docker/Dockerfile
+!environments/docker/Dockerfile.openmm
+!environments/docker/Dockerfile.models
+!environments/docker/Dockerfile.boltz
+!environments/docker/Dockerfile.complex
+!environments/docker/Dockerfile.mmseqs
+!environments/docker/Dockerfile.p2rank
+!environments/docker/Dockerfile.reaction-free-energy
+!environments/reaction-free-energy/
+!environments/reaction-free-energy/environment.yaml
+!environments/docker/Dockerfile.qmmm
+!environments/qmmm/
+!environments/qmmm/environment.yaml
+!environments/docker/Dockerfile.openfe
+!environments/binding-free-energy/
+!environments/binding-free-energy/environment.yaml
+!environments/binding-free-energy/locks/
+!environments/binding-free-energy/locks/linux-aarch64.cuda13.explicit.txt
+!environments/install_openff_sources.py
+!environments/openff-sources.json
+!environments/p2rank/
+!environments/p2rank/environment.yaml
+!environments/openff-complex-preparation/
+!environments/openff-complex-preparation/environment.yaml
+!environments/boltz2/
+!environments/boltz2/requirements.txt
+!environments/boltz2/requirements.torch-cu130.txt
+!environments/protein-representations/
+!environments/protein-representations/environment.yaml
+!environments/openmm/
+!environments/openmm/requirements.cuda13.txt
+**/__pycache__/**
+**/*.pyc

alambiq-0.1.0/.gitattributes

@@ -0,0 +1,5 @@
+# Byte-pinned external inputs: preserve line endings and review via source hashes.
+tests/fixtures/**/*.cif -text -diff
+tests/fixtures/**/*.json -text -diff
+tests/fixtures/**/*.fasta -text
+tests/fixtures/**/*.gb -text

alambiq-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,126 @@
+name: Installed package validation
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+env:
+  PREFECT_SERVER_ANALYTICS_ENABLED: "false"
+  PREFECT_HOME: .alambiq/ci/prefect
+  ALAMBIQ_PREFECT_HOME: .alambiq/ci/prefect
+  PREFECT_SERVER_EPHEMERAL_STARTUP_TIMEOUT_SECONDS: "120"
+  PYTHONDONTWRITEBYTECODE: "1"
+  OMP_NUM_THREADS: "2"
+  OPENBLAS_NUM_THREADS: "2"
+  MKL_NUM_THREADS: "2"
+  NUMBA_NUM_THREADS: "2"
+
+jobs:
+  wheel:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - run: python -m pip install uv==0.9.10 ruff==0.15.2
+      - run: uv lock --check
+      - run: ruff check src tests tools
+      - run: uv build --wheel --sdist --out-dir .alambiq/ci/wheel
+      - run: python tools/check_distribution.py
+      - run: python tools/check_getting_started.py
+      - run: uv export --frozen --all-extras --no-emit-project --no-hashes --output-file .alambiq/ci/wheel/dependencies.txt
+      - uses: actions/upload-artifact@v4
+        with:
+          name: installed-wheel
+          path: .alambiq/ci/wheel/
+          if-no-files-found: error
+          include-hidden-files: true
+
+  installed:
+    needs: wheel
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14]
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - uses: actions/download-artifact@v4
+        with:
+          name: installed-wheel
+          path: .alambiq/ci/wheel
+      - name: Install the wheel with every pip-installable extra
+        shell: bash
+        run: |
+          for wheel in .alambiq/ci/wheel/*.whl; do
+            python -m pip install --constraint .alambiq/ci/wheel/dependencies.txt "$wheel[chemistry,routes,thermodynamics,quantitative,dossier,construct,coding-design,trajectory,openmm,protein-repair,embedding-analysis]" pytest
+          done
+          python -m pip check
+      - name: The wheel names its capabilities
+        run: alambiq capability list
+      - name: The example campaign validates and runs
+        run: |
+          alambiq validate examples/kinetics-from-measurements/campaign.yaml
+          alambiq run examples/kinetics-from-measurements/campaign.yaml --run-dir .alambiq/ci/runs/kinetics
+      - name: Licences of the installed dependencies
+        run: python tools/scan_licenses.py
+      - name: Headless browser for the report checks
+        run: |
+          python -m pip install playwright==1.62.0
+          python -m playwright install --with-deps chromium
+      - name: Tests against the installed wheel
+        shell: bash
+        run: |
+          for wheel in .alambiq/ci/wheel/*.whl; do
+            python -I tools/check_installed_package.py --wheel "$wheel" --require-extras --receipt .alambiq/ci/installed-${{ matrix.os }}-${{ matrix.python-version }}.json
+          done
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: evidence-${{ matrix.os }}-${{ matrix.python-version }}
+          path: .alambiq/ci/*.json
+          include-hidden-files: true
+
+  docker:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build the core image with the extras the examples need
+        run: |
+          docker build -f environments/docker/Dockerfile \
+            --build-arg 'ALAMBIQ_EXTRAS=quantitative dossier trajectory chemistry routes thermodynamics construct coding-design embedding-analysis' \
+            -t alambiq:ci-core .
+      - name: The image lists its capabilities
+        run: docker run --rm alambiq:ci-core capability list
+      - name: An example runs read-only with no network
+        run: |
+          mkdir -p .alambiq/docker-results
+          docker run --rm --network none --read-only \
+            --tmpfs /tmp:rw,nosuid,nodev,mode=1777,size=1g \
+            --user "$(id -u):$(id -g)" \
+            -v "$PWD:/work:ro" -v "$PWD/.alambiq/docker-results:/results" \
+            alambiq:ci-core run examples/kinetics-from-measurements/campaign.yaml \
+            --run-dir /results/kinetics --report /results/kinetics.html
+          test -s .alambiq/docker-results/kinetics.html
+      - name: The engine layers that need no download build
+        run: |
+          for layer in mmseqs p2rank; do
+            docker build -f environments/docker/Dockerfile.$layer \
+              --build-arg BASE_IMAGE=alambiq:ci-core -t alambiq:ci-$layer .
+          done
+          docker run --rm alambiq:ci-mmseqs env check mmseqs
+          docker run --rm alambiq:ci-p2rank env check p2rank

alambiq-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: Index to publish to
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - run: python -m pip install uv==0.9.10 build twine
+      - run: uv lock --check
+      - run: python tools/check_distribution.py
+      - run: python -m build --outdir dist
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: ${{ github.event_name == 'workflow_dispatch' && inputs.target || 'pypi' }}
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - name: Publish to TestPyPI
+        if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+      - name: Publish to PyPI
+        if: github.event_name == 'release' || inputs.target == 'pypi'
+        uses: pypa/gh-action-pypi-publish@release/v1

alambiq-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+.DS_Store
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+build/
+dist/
+.alambiq/
+
+# Heavy scientific resources and generated results never belong in Git.
+/resources/
+runs/
+/artifacts/
+*.sif
+*.img
+*.ckpt
+*.pt
+*.pth

alambiq-0.1.0/AGENTS.md

@@ -0,0 +1,175 @@
+# Alambiq agent instructions
+
+Alambiq is open-source software for biotechnology R&D, organized as capabilities.
+
+## Sources of truth
+
+- `docs/concepts.md` defines the terms capability, campaign, step, binding, request,
+  result, run, run record, reuse, engine environment and resource; `docs/methods/` explains how to
+  choose and read the capabilities of each method area.
+- A capability is declared in code: `alambiq capability show ID` prints its request
+  fields, result, method and limits from that declaration. Do not restate the request fields, result or limits
+  of a capability in another file, such as a manifest, a schema or an agent skill file.
+  Methods pages explain the choice and interpretation of capabilities and link to
+  `alambiq capability show`.
+- Document implemented behavior and measured limits; do not add development forecasts
+  or release promises.
+
+## Required discipline
+
+- Organize reusable code by scientific capability, never by application sector or
+  release number. Implement scientific computation in functions that do not depend on
+  the capability registry, the run context or Prefect, so that tests call them
+  directly. The capability function reads the request, calls such a function and builds
+  the result.
+- A campaign written in YAML and one written in Python are built into the same
+  `Campaign` model and run by the same code.
+- The researcher plans the research. Alambiq runs the requests that the researcher
+  writes and does not generate requests; do not add an autonomous scientific planner.
+- Prefect is the sole workflow runtime, and no parallel executor is added. Code for
+  requests, resource identities and result presentation does not import Prefect;
+  `src/alambiq/core/execution.py` is the module that does.
+- Engines run in their own pinned environments. An engine receives a JSON request file
+  and writes a JSON result file; engine modules import only the standard library and
+  their own engine.
+- Preserve domain-specific types; do not introduce one type for every biological
+  entity.
+- Add a dependency or an abstraction only for a need stated in the change description.
+  Remove superseded code. Shared viewers and exports are part of the report file and
+  must not require an externally hosted service.
+- A Alambiq installation runs on one machine. Do not add scheduler management or
+  distributed execution unless a need for it is stated.
+- Report results and source identities. A diagnostic names what is wrong (the field,
+  column, unit, file, step or variable). The researcher interprets results and makes
+  research decisions. A scientifically implausible value is a finding in the result,
+  never a validation error.
+- Keep resource files, engine environments and generated artifacts outside Git.
+- Select scientific software and model weights whose licenses permit commercial use
+  without fees, individually negotiated agreements, or academic-only or
+  noncommercial-only restrictions. Prefer MIT, BSD and Apache-2.0; the pattern `ALLOWED` in
+  `tools/scan_licenses.py` defines the other accepted licenses. Check the license of the
+  code, the model weights and the data separately, at the version in use: the license of a
+  Python package that calls a model is separate from the license of the model. Avoid GPL scientific
+  executables in the recipes under `environments/`. Preserve third-party
+  notices.
+- Obtain explicit approval from the repository owner before downloading a resource,
+  calling a paid service, running an expensive computation, contacting an external
+  party, publishing or pushing.
+- When a test fails, find the cause and fix it. Do not weaken the test to make it pass.
+- Test each change in the behavior of a method against a known answer, and test the
+  failure cases that apply. Preserve attribution, the identity of inputs and outputs
+  (content digests), units, source type and applicable licensing information.
+- In documentation, help text, reports and comments, state implemented behavior, input
+  requirements, assumptions and observations directly, in affirmative sentences and not
+  as negations of what is absent.
+
+## Writing
+
+Repository text is reference documentation, written like a technical manual or the methods
+section of a paper. `tests/core/test_writing.py` enforces the mechanical rules.
+
+- **Voice.** Impersonal and in the present tense. Procedures use the imperative
+  (`Install the core.`). No second or first person, no contractions, no rhetorical
+  questions, no exclamation marks.
+- **Headings.** Sentence-case noun phrases naming the subject: "Run records", not "What a
+  run keeps". Bare imperatives only in step-by-step guides and recipes ("Install", "Build").
+  A heading never asks a question or promises a result.
+- **Definitions.** A term is defined once, by what it is and what distinguishes it, and used
+  the same way afterwards. Example: "A capability is a function with a declared request
+  type, a declared result type and documented limits. It is identified by `prefix.action`."
+- **Vocabulary.** "Alambiq" names the software. The terms are capability, campaign, step,
+  binding, request, result, run, run record, reuse, engine environment and resource. Do not use "workbench",
+  "platform", "tool" or "workflow" for the software or its parts (OpenMM's platforms and
+  Prefect's workflows keep their own names).
+- **Stable text.** Prose does not state counts of the repository's own contents (capabilities,
+  examples, pages, tests, extras) or other details that a listing command or a test already
+  gives; the command is the source. Numbers that belong to the method (limits, defaults,
+  ranges, results) and dated evidence (a verification receipt) stay.
+- **Precision.** Quantify or state the condition instead of "a few", "usually", "roughly",
+  "often". State a limit as a condition: "The interval assumes independent residuals."
+  Every number has its unit. Counts are digits ("3 replicas").
+- **Scope.** Text states what the software does and the conditions under which a result
+  holds, as positive conditions: "The interval assumes independent residuals", "Applies to
+  single substitutions of a natural enzyme", "Requires a structure without ligands". It does
+  not list what the software does not do, claim, establish or replace ("does not establish",
+  "makes no claim", "is not a substitute for", "not cleared"). A negative sentence stays only
+  where a reader would otherwise use a result where it does not hold and no positive
+  condition says so; it is one sentence, at the place where the result is used. License text
+  states the terms that apply.
+- **Plain prose.** No evaluative adjectives or adverbs ("simply", "carefully", "robust"),
+  no metaphors ("lands", "keeps", "carries"), no sentence about the page itself, no
+  asides set off with dashes. Qualities are shown by tests, never claimed in text.
+- **Spelling.** American ("analyze", "license", "modeled", "behavior", "center").
+- **Release labels.** Text describes what exists. It contains no release names, forecasts
+  or promises.
+
+## Validation
+
+Run these commands before proposing a change, in a Python environment where the project
+is installed (or with `PYTHONPATH=src` set). The last command writes its run to a new
+temporary directory.
+
+```bash
+python -m pytest tests/core
+ruff check src tests tools
+python -m alambiq validate examples/kinetics-from-measurements/campaign.yaml
+python -m alambiq run examples/kinetics-from-measurements/campaign.yaml
+```
+
+`tests/core` is the whole suite. A test that needs an engine environment declares it and
+is skipped when `ALAMBIQ_ENV_<NAME>` (for example `ALAMBIQ_ENV_OPENMM`) does not point
+at that environment's Python; the skip message names the missing prerequisite.
+
+Besides the method tests, `tests/core` contains these checks of the whole repository:
+
+- `test_examples.py`: every example runs from its `campaign.yaml`, and the test asserts
+  the values the example was built to return.
+- `test_report_lint.py`: every report parses, loads nothing from the network, shows no
+  Python or NumPy representation, `NaN`, `inf` or `None` in its text, and in each numeric
+  column the header states the unit, or states that the column is a count, an index, a
+  rank or a fraction. The outline of each report (sections, headings, notes, table
+  headers and collapsed sections) matches the snapshot in `tests/snapshots/reports/`;
+  `ALAMBIQ_UPDATE_SNAPSHOTS=1` rewrites the snapshots.
+- `test_first_mistakes.py`: each input mistake that a first-time user makes (listed in
+  the test) produces a message that names the field, column, unit, file, step or variable
+  at fault, a nonzero exit status and no traceback.
+- `test_determinism.py`: the steps that draw random numbers or start from random points
+  (candidate selection, codon recoding, fits to progress curves) return identical outputs
+  when an example runs twice in new run directories, and a different seed changes a
+  random selection.
+- `test_runtime_budgets.py`: no step of an engine-free example exceeds its time budget,
+  which is about 10 times the time measured on a laptop, with a minimum of 5 s.
+- `test_documentation.py`: every relative link resolves, every capability appears on a
+  methods page that the methods index lists, every path and `alambiq` subcommand named
+  in a shell block exists, and every example has a README with the same sections and
+  appears in the index of examples.
+- `test_writing.py`: the mechanical rules above.
+- `test_licenses.py`: every resource specification states a license from the accepted set
+  and the size and SHA-256 digest of each file, the third-party notices name every
+  resource and the bundled viewer, and no installed dependency has a license that
+  `tools/scan_licenses.py` classifies as refused or unknown.
+- `test_core_imports.py`: all capabilities register and are listed when the optional
+  packages (NumPy, SciPy, RDKit and others) cannot be imported.
+- `test_conformance.py`: every capability states its limits, describes each request field
+  and its result, has a test that exercises each request field, except the justified
+  exemptions listed in the test, and has a function that renders its result in the report.
+
+When a change breaks one of these checks, find the cause; do not relax the check. Check a
+known answer in every method test: an analytic result, a quantity recomputed
+independently from the written files, or a transformation whose answer is fixed (for
+example, the difference between a structure and itself is zero).
+
+Checks outside the suite:
+
+- `python tools/check_distribution.py` builds the wheel and the source distribution,
+  inspects their contents and installs the wheel into a new environment.
+- `python tools/scan_licenses.py` lists each installed dependency whose license is not
+  classed as allowed; `--all` lists every dependency.
+- `python tools/check_getting_started.py` runs the commands of `docs/getting-started.md`
+  in a copy of the repository made for the check.
+- `python -I tools/check_installed_package.py --wheel PATH --receipt FILE` runs the tests
+  against an installed wheel and records the module origins and the skipped tests.
+
+Build local wheels from a fresh checkout or clear `build/` first: a wheel built from a
+`build/` directory that still holds a module removed from the source tree contains that
+module.

alambiq-0.1.0/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+## 0.1.0
+
+Alambiq is organized around capabilities that have declared request and result types.
+
+### Capabilities and runs
+
+- Capabilities in families (characterize, investigate, engineer, measure,
+  operate). Each capability is a function with a declared request type, a declared result
+  type and documented limits, and has tests in `tests/core`. `alambiq capability list`
+  prints the capabilities; `alambiq capability show ID` prints the request, result,
+  method and limits of one capability.
+- A campaign is a list of steps; each step has `params` and `bind` (see
+  [Concepts](docs/concepts.md)). Prefect executes the campaign. Results are stored in a
+  content-addressed artifact store. A step is reused when its key is unchanged
+  (see [Reuse](docs/concepts.md#reuse)).
+- Docker images for the engine environments (MMseqs2, P2Rank, ThermoMPNN, pymbar, QM/MM,
+  OpenMM CUDA, OpenFF, ESM, Boltz-2, OpenFE). An engine environment is built from a plain
+  Python image and copied onto the core image, so a change to the core does not rebuild
+  it. `Dockerfile.tests` adds the test runner (pytest) to any image, so that the repository
+  tests, mounted at run time, run against the engines of that image. The images were built
+  for linux/arm64 on a Linux ARM64 host with an NVIDIA GB10 GPU on 2026-10-25. The
+  environment check of each image and the examples named in the receipt were run there, and
+  the engine tests were run there with 20 QM/MM engine tests skipped
+  (`environments/docker/verification.linux-arm64-spark-20261025.json`). The
+  Apple GPU environment of Boltz-2 is available only as a native environment.
+- Engines run in engine environments (separate Python environments with pinned packages,
+  named by `ALAMBIQ_ENV_<NAME>`) and are started by a runner that imports only the Python
+  standard library. Models and databases are pinned resources: each is installed before
+  a run and verified before use.
+- Every run writes a run record (`run.json`); a copy of every run, including the latest, is
+  stored under `history/` in the run directory. `alambiq history RUN_DIR` lists the runs, and
+  `alambiq replay RUN_DIR STEP --out DIR` writes one step of a recorded run as a
+  campaign that runs it again.
+
+### Reports
+
+- One HTML file per run, with no external references. Charts are inline SVG that records
+  the plotted x and y values. An offline structure viewer (3Dmol.js, BSD-3-Clause) is
+  added when a structure is shown. Alignments are shown as aligned rows in blocks. When the run
+  directory holds at least 2 recorded runs of the campaign, the report ends with a table of
+  those runs.
+
+### Methods
+
+- `assay.fit` fits Arrhenius, first-order decay and pH-profile models in addition to the
+  linear and Michaelis-Menten models, with derived quantities and their uncertainty.
+- `operation.define` converts measured kinetics into an operating definition (see
+  [Operation file formats](docs/operation-formats.md)), with temperature and pH
+  dependence, a stated operating state (`state`: temperature and pH) and, for a reversible
+  pair, the Haldane relation to the equilibrium constant. `operation.propagate`
+  propagates the uncertainty of a fitted Michaelis-Menten rate to the predicted
+  concentrations.
+- `protein.score_substitutions` scores substitutions with ESM C by masked marginals.
+  `variant.propose` ranks them by the language-model score, the predicted change in folding
+  free energy or the mean of both percentile ranks, with filters that include the presence
+  of the mutant residue in homologs. A benchmark on 4
+  measured datasets (3 of single substitutions of natural enzymes and 1 of an engineered
+  lineage) is in [the methods page](docs/methods/variant-proposal.md). The Spearman
+  correlation between the language-model score and the measurements is +0.37 for the
+  thermostability of Bacillus subtilis Lipase A, +0.58 for the activity of human
+  glucokinase, +0.37 for the abundance of human glucokinase and -0.42 (95 % interval -0.73
+  to -0.01) for an amine transaminase lineage.
+- `candidate.select` has 7 strategies, among them `highest-predicted-diverse`, which
+  weights predicted response against diversity, and `pareto`, which takes non-dominated
+  fronts over 2 to 5 fitted objectives.
+
+### Examples and documentation
+
+- Runnable examples with asserted headline values, methods pages and an installation
+  guide.