calkit-python 0.45.3__tar.gz → 0.46.0__tar.gz

{calkit_python-0.45.3 → calkit_python-0.46.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: calkit-python
-Version: 0.45.3
+Version: 0.46.0
 Summary: Reproducibility simplified.
 Project-URL: Homepage, https://calkit.org
 Project-URL: Issues, https://github.com/calkit/calkit/issues
@@ -40,15 +40,17 @@ Requires-Dist: pillow
 Requires-Dist: psutil>=7.0.0
 Requires-Dist: pydantic-settings
 Requires-Dist: pydantic[email]
+Requires-Dist: pygtrie<2.6.0
 Requires-Dist: pyjwt
 Requires-Dist: python-dotenv>=1
 Requires-Dist: pywin32; platform_system == 'Windows'
 Requires-Dist: requests
+Requires-Dist: rich
 Requires-Dist: sqlitedict>=2.1.0
 Requires-Dist: texsoup>=0.3.3
 Requires-Dist: toml>=0.10.2
 Requires-Dist: tqdm>=4.67.1
-Requires-Dist: typer==0.25.1
+Requires-Dist: typer==0.27.2
 Requires-Dist: uvicorn
 Provides-Extra: data
 Requires-Dist: pandas>=2.2.3; extra == 'data'

{calkit_python-0.45.3 → calkit_python-0.46.0}/actions/run/README.md

@@ -43,6 +43,10 @@ on:
 permissions:
   contents: write
   id-token: write
+  # Lets Docker environments configured with a registry push the images they
+  # build to the GitHub Container Registry, so later runs pull instead of
+  # rebuilding
+  packages: write
 
 # Make sure we only ever run one per branch so we don't have issues pushing
 # after running the pipeline

{calkit_python-0.45.3 → calkit_python-0.46.0}/actions/run/action.yml

@@ -26,6 +26,14 @@ inputs:
     description: Arguments passed to calkit run command.
     required: false
     default: ""
+  login_ghcr:
+    description: >-
+      Whether to log in to the GitHub Container Registry, so that Docker
+      environments configured to use it can push images they build and pull
+      them back instead of rebuilding. Requires the workflow to grant the
+      "packages: write" permission.
+    required: false
+    default: "true"
 outputs: {}
 runs:
   using: composite
@@ -260,6 +268,17 @@ runs:
       if: ${{ steps.detect.outputs.needs_docker == 'true' }}
       uses: docker/setup-buildx-action@v3
 
+    # Logging in lets an environment with `registry: ghcr.io` push what it
+    # builds here, so that later runs and everyone's laptops pull the image
+    # instead of rebuilding it. Harmless when no environment uses a registry.
+    - name: Log in to the GitHub Container Registry
+      if: ${{ steps.detect.outputs.needs_docker == 'true' && inputs.login_ghcr == 'true' }}
+      uses: docker/login-action@v3
+      with:
+        registry: ghcr.io
+        username: ${{ github.actor }}
+        password: ${{ github.token }}
+
     - name: Report unsupported environment kinds
       if: ${{ steps.detect.outputs.unsupported_kinds != '' }}
       shell: bash

{calkit_python-0.45.3/calkit/resources/github-actions → calkit_python-0.46.0/actions/run}/example.yml

@@ -10,6 +10,10 @@ on:
 permissions:
   contents: write
   id-token: write
+  # Lets Docker environments configured with a registry push the images they
+  # build to the GitHub Container Registry, so later runs pull instead of
+  # rebuilding
+  packages: write
 
 # Make sure we only ever run one per branch so we don't have issues pushing
 # after running the pipeline

calkit_python-0.46.0/agent-plugin/skills/build-paper-pipeline/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: build-paper-pipeline
+description: Build the pipeline stages a manuscript's TODO comments ask for,
+  working backwards from the writing to the analysis behind it, and keep the
+  project's questions and answers matching the paper. Use when the user
+  invokes `/calkit:build-paper-pipeline`, leaves TODO comments in a manuscript
+  for an agent to address, or asks to work backwards from the writing to the
+  project behind it. Only for TODOs in a manuscript, and only in a Calkit
+  project: not TODO comments in source code, not GitHub issues, not a task
+  list in someone's notes.
+---
+
+# Build the pipeline the paper asks for
+
+The writing is the human's job. Deciding what the paper claims, and whether
+a claim is worth making, is what nobody else can do for them. Everything
+under a claim -- the stage that computes the number, the figure that shows
+it, the question it answers -- is scaffolding, and scaffolding is what this
+skill builds.
+
+The user writes a sentence with a hole in it and marks the hole:
+
+```latex
+% TODO: report the mean speedup over the baseline, and plot the
+% distribution across cases
+Our method is faster than the baseline by \todo{}.
+```
+
+You fill the hole by building the project behind it, not by writing a
+number into the sentence.
+
+## The rule that makes this safe
+
+**Never type a computed value into the manuscript.** A number you typed is
+a number nobody can check, and it goes stale the moment a stage reruns. The
+number reaches the page through the pipeline: a stage computes it and
+writes it to a results file, a `json-to-latex` stage turns that file into
+LaTeX commands, and the manuscript says `\result[Speedup]`. The same
+applies to figures (`\ckfigure{...}` over a pipeline output) and to the
+answers in `calkit.yaml` (`{name}` placeholders over `value` evidence).
+
+If you find yourself about to write `2.4x` into a `.tex` file, stop: that
+is the hole, not the fix. The `check-reproducibility` skill covers finding
+and fixing a typed literal that is already in a manuscript; this one is
+about not putting one there.
+
+See the `conventions` skill for `calkit.yaml` structure and stage kinds,
+`add-pipeline-stage` for adding one stage, and `create-pipeline` for
+building a pipeline from scratch.
+
+## Procedure
+
+1. **Read the manuscript and collect the TODOs.** Look for `% TODO`,
+   `\todo{}`, `\TODO`, and prose that asserts something with no number or
+   figure behind it. Quote each one back to the user with what you think it
+   is asking for, grouped into: needs a computation, needs a figure, needs
+   data the project does not have, and needs a decision only they can make.
+   Do not start building until they have confirmed the list --- a
+   misunderstood TODO costs a whole stage.
+
+2. **Say what is missing before you build.** For each TODO, name the inputs
+   it needs. If the project already has them, say which stage produces
+   them. If it does not, that TODO is blocked, and the honest answer is to
+   say so rather than to invent data. Blocked TODOs come in two kinds:
+
+   - **Data nobody has collected yet.** This is a manual step, not a
+     missing script. Add a `procedure` stage (see below) and tell the user
+     the pipeline now knows the step is outstanding.
+   - **Data that exists somewhere else.** Ask where. Declare it with
+     `imported_from` so the provenance chain reaches back past the project.
+
+3. **Build a stage per computation.** One stage, one question. Prefer a
+   script over a notebook, since a script diffs cleanly and reruns
+   headlessly. Write the results to a JSON file under `results/` with keys
+   named the way the paper will refer to them.
+
+4. **Inject, don't copy.** Add a `json-to-latex` stage over the results
+   file and reference the values from the manuscript with the generated
+   command. Replace the TODO with the sentence the user wrote, now with
+   `\result[...]` where the hole was.
+
+5. **Make the question match the paper.** A claim in the paper is an answer
+   to a question. Add or update the entry under `questions` in
+   `calkit.yaml`: the `question` as the paper poses it, the `answer` as the
+   paper states it with `{name}` placeholders where numbers go, and
+   `evidence` naming the results file and key, the figure, and the
+   publication section that carries the argument. Run
+   `calkit check questions` and fix what it reports.
+
+6. **Run the pipeline, then check your own work.** Run `calkit run`, then
+   `calkit check repro`, which reads the manuscript back and reports any
+   number in it that is not traceable to a pipeline output. A finding there
+   is a hole you closed by typing rather than by building, so go back to
+   step 3 for it. Show the user the rendered sentences
+   (`calkit list questions`) and the built document. Never commit a derived
+   output yourself, and never edit a results file by hand.
+
+## Data a person has to collect
+
+Some TODOs cannot be closed by any amount of code, because the measurement
+has not been made. Do not leave that as a comment in the manuscript, where
+nothing tracks it. Declare the procedure and make it a stage, so the
+pipeline knows the step is outstanding and everything downstream waits on
+it:
+
+```yaml
+procedures:
+  measure-rig:
+    title: Measure the rig
+    description: Read the temperature off the display at each setting.
+    steps:
+      - summary: Turn on the machine
+        wait_after_s: 5
+      - summary: Record the temperature
+        inputs:
+          temperature:
+            units: C
+            dtype: float
+
+pipeline:
+  stages:
+    collect-data:
+      kind: procedure
+      procedure_name: measure-rig
+    plot-data:
+      kind: python-script
+      environment: py
+      script_path: scripts/plot-data.py
+      inputs:
+        - from_stage_outputs: collect-data
+      outputs:
+        - figures/temperature.png
+```
+
+`calkit run` walks the person through the steps and logs each one to
+`.calkit/procedure-runs/measure-rig/`, which the next stage reads like any
+other input. Write the procedure's steps in the words someone at the bench
+would need, not in the words a program would; you are writing for a person
+holding a thermometer.
+
+## What to hand back
+
+Say what you built, what you did not, and why:
+
+- the stages you added and what each computes;
+- the values and figures now injected, and where they land in the text;
+- the questions you added or changed, and what `calkit check questions`
+  says;
+- **every TODO you could not close**, with what is missing. This is the
+  most useful part of the report. A TODO left open because the data does
+  not exist is a finding; a TODO closed with a plausible-looking number is
+  a fabrication.

calkit_python-0.46.0/agent-plugin/skills/check-questions/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: check-questions
+description: Review a Calkit project's questions and answers against their
+  evidence. Use when the user invokes `/calkit:check-questions`, asks whether
+  the project's answers are still true, or after a pipeline run changes
+  results that answers cite.
+---
+
+# Check questions against evidence
+
+An answer in `calkit.yaml` is a claim about the evidence as it was when the
+answer was last edited. The pipeline keeps the evidence current; nothing
+keeps the prose current. Calkit's deterministic check catches evidence
+changing underneath an answer. This skill covers what a check cannot:
+whether the sentence still follows from the evidence.
+
+## Division of labor
+
+Deterministic, done by `calkit check questions` — never re-derive by hand:
+
+- every evidence path exists;
+- every `value` key resolves in its file, and every `{name}` placeholder in
+  the prose resolves and formats;
+- every publication `label` still exists in the LaTeX source;
+- no evidence has changed (Git history for Git-tracked outputs, `dvc.lock`
+  for DVC-tracked ones) since the commit that last edited the question;
+- each evidence path is produced by a pipeline stage, or declared with
+  `imported_from` or `created_by`. This one is advisory: it is reported as
+  `unattributed` and does not fail the check.
+
+Judgment, done here — the check reads paths and hashes, and cannot read a
+sentence:
+
+- **does the evidence actually support the answer**, which is the reason
+  this skill exists;
+- does the answer still follow from the evidence, given what changed;
+- are numbers retyped into the prose that should be `{name}` placeholders;
+- is the answer concise, and does it point at the publication section that
+  carries the argument rather than repeating it.
+
+## Does the evidence support the answer?
+
+A question can pass every deterministic check and still be wrong: the
+paths resolve, the numbers render, nothing has changed since — and the
+sentence claims something the evidence does not show. That is the failure
+this skill is for, and it is not visible to the CLI. For each answer you
+review, read the evidence yourself and ask, in this order:
+
+1. **Does the evidence say what the answer says it says?** Open each entry:
+   the value at its key, the figure, the table, the publication section.
+   An answer of "the closure cuts error by {improvement:.1f}x" needs the
+   value behind `improvement` to be that ratio, not the two errors it was
+   computed from, and not a ratio over a different pair of cases.
+2. **Does it support the claim's strength?** "Reduces error" needs a
+   difference; "reduces error by 40%" needs the number; "reduces error
+   across the range" needs evidence across the range, not at one point.
+   Weaken the sentence to what is there, or add the evidence that would
+   carry it.
+3. **Does it cover the claim's scope?** A claim about all cases cited
+   against one case, a claim about the method cited against one dataset,
+   a general statement resting on the best run: the evidence is real and
+   the sentence reaches past it. Name the gap.
+4. **Would the claim survive the evidence changing?** If a cited value
+   moved 10%, would the sentence still be true? If yes, the number is
+   decoration and the claim is vaguer than it looks. If a change of any
+   size would leave it standing, the evidence is not what the answer rests
+   on, and something is missing from `evidence`.
+5. **Is anything load-bearing missing?** A claim resting on a comparison
+   needs both sides. A claim about significance needs the test, not the
+   means. If the reasoning runs through an artifact the entry does not
+   name, add it or say the answer cannot be checked as written.
+6. **Is the causal language earned?** "Because", "leads to", "explains"
+   need more than co-movement. If the evidence is a correlation, the
+   answer should say so.
+
+Report what you found, quoting the value or naming the figure. Where the
+evidence does not support the sentence, propose the sentence it does
+support and let the user decide; never edit the answer to match the
+evidence without showing them both.
+
+## Procedure
+
+1. Run `calkit check questions --json` and read the report. Questions with
+   status `stale` or `error` need attention; `ok` ones pass the
+   deterministic check, which says nothing about whether their evidence
+   supports them, so review those too whenever the user asked for a full
+   review or the answer is one the paper leans on.
+2. For each **stale** question, the report names the evidence that changed
+   and the commit the answer dates from. Read the rendered answer
+   (`calkit list questions`) against the current evidence, and if it helps,
+   the old evidence (`git show <commit>:<path>`). Decide:
+   - **The claim still holds**: say so, and edit the question to record
+     that you read it again. Any edit counts: the check anchors on the
+     commit where the question last changed. Adding or refining `notes` is
+     usually the honest edit to make, since it is where you say what you
+     checked.
+   - **The claim no longer holds**: draft a corrected answer, show the user
+     the old and new text side by side with the values that changed, and
+     only after they agree, edit `calkit.yaml`.
+   - **The evidence changed because a stage is not reproducible** (same
+     inputs, different output): that is a pipeline defect, not an answer
+     defect. Report it as such and do not rewrite the answer to match noise.
+3. For each **unattributed** evidence entry, ask where the file came
+   from. If a stage should produce it, that is a pipeline gap worth
+   reporting. If it was imported or made by hand, declare it under
+   `figures`, `datasets`, or `publications` with `imported_from` or
+   `created_by` so the project says so.
+4. For each **error**, fix the reference: a missing path means the pipeline
+   has not been run or pulled; a bad key or placeholder means a results
+   file was restructured; a missing label means the publication was
+   reorganized. Do not delete evidence to make an error go away.
+5. For every question you touched, move any number in the prose that the
+   evidence carries into a `{name:...}` placeholder on a `value` entry, so
+   it is read from the results file rather than retyped.
+
+6. Run the evidence-supports-the-answer review above on every question in
+   scope, `ok` ones included. A question the CLI passed is where an
+   unsupported claim survives, because nothing else looks at it.
+
+Never edit a stale question just to clear the check. It is the act of
+reading the answer against the evidence that the edit is meant to record,
+and an edit made without doing that is a false statement about the
+project, not a tidy-up.
+
+## Writing answers
+
+- One claim per question, two to four sentences. Say what was found and
+  what it means; leave the reasoning to the publication.
+- Numbers come from `value` evidence via placeholders, formatted to the
+  precision the claim needs: `{ratio:.1f}x`, `{error:.0%}`.
+- Point at the publication with a `publication` evidence entry carrying
+  `section` (for the reader) and `label` (for the check), instead of an
+  `explanation` that restates the argument.
+- Each evidence entry should be one the answer actually depends on.
+  Evidence that would not change the answer if it changed is decoration.
+- An open question has no `answer`; `notes` says why it is open and what
+  would settle it.
+
+## Reporting
+
+Relay a short table: question index, status, what changed, what you did or
+propose. Quote values, not adjectives. If the pipeline is stale
+(`calkit status`), say so first, since the evidence may be about to change
+again.

calkit_python-0.46.0/agent-plugin/skills/check-reproducibility/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: check-reproducibility
+description: Check whether a project is fully traceable, and fix what isn't,
+  including numbers typed into a manuscript that no pipeline output accounts
+  for. Use when the user invokes `/calkit:check-reproducibility`, asks whether
+  a project is reproducible, or asks where a number in a paper came from.
+---
+
+# Check and fix reproducibility
+
+`calkit check repro` reports what a static reading of the project can
+establish: whether there is a pipeline, whether stages run in declared
+environments, whether artifacts have provenance, and whether any number in
+a manuscript is one nobody can trace.
+
+## Division of labor
+
+Deterministic, done by `calkit check repro --json` --- never re-derive by
+hand:
+
+- whether the project is a Git and DVC repo with a remote and a pipeline;
+- which stages run outside a declared environment;
+- which artifacts have no `stage`, `imported_from`, or `created_by`;
+- which scripts no stage refers to;
+- which numbers in the manuscript duplicate a value the pipeline already
+  computes (`retyped_values`), and which result-like numbers have nothing
+  recorded behind them at all (`unattributed_numbers`).
+
+Judgment, done here:
+
+- whether a flagged number is really a result, or a constant, a tolerance,
+  a version, or a figure width the check couldn't rule out;
+- which stage should compute a value that has no stage behind it;
+- whether an artifact with no provenance was made here or brought in.
+
+## Procedure
+
+1. Run `calkit check repro --json` and read the report. The plain output
+   is a summary, each countable line naming the `-c` that opens it;
+   `--json` carries every finding. The command exits non-zero only for
+   `retyped_values`, a value the project's own pipeline computes and the
+   document typed anyway; everything else is advice and leaves the exit
+   code alone. Read the findings, not the exit code.
+
+2. **Pipeline and environment findings** come first: a value can't be made
+   traceable until there is a pipeline to make it. See the
+   `create-pipeline` and `add-pipeline-stage` skills.
+
+3. **Every `retyped_values` finding is worth fixing.** Each is a number
+   the pipeline already computes, typed into the document: right today and
+   wrong the next time that stage runs. The finding names the results file
+   and key, so the fix is mechanical.
+
+4. **`unattributed_numbers` is a list to read, not a list to fix.** Most
+   numbers in a paper are not results. A quantity quoted from a reference
+   (`cited` is true when the sentence carries a citation), a threshold the
+   author chose, a tolerance, a count -- none of them have anything to be
+   traced to, and turning them into structured values would be work for no
+   gain. What the list is good for is spotting the one that _is_ a result
+   and never got templated in. Say which ones you're leaving and why; never
+   rewrite a sentence to make a check pass, and never invent a stage to
+   compute a number somebody else measured.
+
+   For a number that is this project's result, it must reach the page
+   through the pipeline rather than through the author's fingers:
+
+   ```yaml
+   pipeline:
+     stages:
+       compute-drag:
+         kind: python-script
+         environment: py
+         script_path: scripts/compute-drag.py
+         outputs: [results/drag.json]
+       drag-to-latex:
+         kind: json-to-latex
+         command_name: result
+         inputs: [results/drag.json]
+         outputs:
+           - path: paper/generated-drag.tex
+             storage: git
+   ```
+
+   The script writes `{"DragCoefficient": 0.42}`. The document inputs the
+   generated file and refers to the value by key:
+
+   ```latex
+   \input{generated-drag}
+   ...
+   The drag coefficient is \result[DragCoefficient].
+   ```
+
+   `json-to-latex` generates one _keyed_ command per file, named by
+   `command_name` (or the output file's stem), so the reference is
+   `\result[DragCoefficient]` --- not a separate macro per key. Never write
+   a raw `stages:` block with `cmd: calkit latex from-json`; the stage kind
+   is what keeps `calkit.yaml` the single source of truth.
+
+5. **Run the pipeline** (`calkit run`) and check again. Do not run the
+   script yourself and paste the number in: that is the failure this whole
+   check exists to catch.
+
+6. **Report what you left.** A number you decided was not a result is a
+   judgment the user should see, not one to bury.
+
+## Related
+
+- `build-paper-pipeline` builds the stages a manuscript's TODO comments
+  ask for, so the value is injected from the start rather than typed and
+  caught here.
+- `check-questions` covers whether the project's answers still follow from
+  their evidence, which is the same idea one level up.

{calkit_python-0.45.3 → calkit_python-0.46.0}/agent-plugin/skills/conventions/SKILL.md

@@ -74,7 +74,12 @@ Example environment definitions:
 
 ```yaml
 environments:
-  main:
+  py:
+    kind: uv
+    path: pyproject.toml
+    python: "3.13"
+
+  py2:
     kind: uv-venv
     path: requirements.txt
     python: "3.13"
@@ -112,81 +117,9 @@ Stages live under `pipeline.stages` in `calkit.yaml`. Every stage requires
 
 ### Stage kinds and their required fields
 
-**`python-script`**: Run a Python script
-
-```yaml
-kind: python-script
-script_path: scripts/run.py
-args: ["--flag", "value"] # optional
-```
-
-**`jupyter-notebook`**: Execute a Jupyter notebook
-
-```yaml
-kind: jupyter-notebook
-notebook_path: notebooks/analysis.ipynb
-html_storage: git # optional, default: dvc
-executed_ipynb_storage: git # optional, default: dvc
-parameters: { key: value } # optional, papermill parameters
-```
-
-**`shell-command`**: Run an arbitrary shell command
-
-```yaml
-kind: shell-command
-command: "python -m mymodule --arg val"
-shell: bash # optional, default: bash
-```
-
-**`shell-script`**: Run a shell script file
-
-```yaml
-kind: shell-script
-script_path: scripts/run.sh
-```
-
-**`latex`**: Compile a LaTeX document to PDF
-
-```yaml
-kind: latex
-target_path: paper/paper.tex
-pdf_storage: git # optional, default: dvc
-```
-
-**`r-script`**: Run an R script
-
-```yaml
-kind: r-script
-script_path: scripts/analysis.R
-```
-
-**`julia-script`** / **`julia-command`**: Run Julia code
-
-```yaml
-kind: julia-script
-script_path: scripts/run.jl
-```
-
-**`matlab-script`** / **`matlab-command`**: Run MATLAB code
-
-```yaml
-kind: matlab-script
-script_path: scripts/run.m
-```
-
-**`docker-command`**: Run a command inside a Docker container
-
-```yaml
-kind: docker-command
-command: "docker run --rm myimage mycommand"
-```
-
-**`command`**: Generic command (for tools that don't fit other kinds)
-
-```yaml
-kind: command
-command: "mytool --input data/raw.csv --output data/out.csv"
-```
+See the `calkit.yaml` schema for details.
+The most common stage kinds are `python-script`, `shell-script`, `shell-command`,
+`jupyter-notebook`.
 
 ### Outputs: Git vs. DVC storage
 
@@ -308,3 +241,13 @@ calkit xr scripts/run.py --dry-run    # see what would happen without running
 - `dvc.yaml`: generated by Calkit—don't edit manually
 - `.calkit/`: Calkit's internal directory—commit its contents unless they
   are large generated files
+
+## Provenance
+
+Calkit's data model emphasizes provenance.
+Any derived artifact (produced by a script, notebook, etc.) should be
+produced by the pipeline so we can know if it's up-to-date w.r.t. its
+inputs and process definition.
+Imported artifacts should have attribution.
+Primary artifacts should have attestation, including AI-generated content,
+though the human is considered the author and AI is noted with a `with_ai` field.