calkit-python 0.47.5__py3-none-any.whl → 0.47.7__py3-none-any.whl

calkit/agent_skills/build-paper-pipeline/SKILL.md

@@ -84,8 +84,11 @@ building a pipeline from scratch.
    `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.
+   publication section that carries the argument. The results file must be
+   one a stage from step 3 writes, never one written by hand. Where the
+   claim hinges on a threshold, write a conditional answer; the
+   `check-questions` skill covers both. 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

calkit/agent_skills/check-questions/SKILL.md

@@ -21,12 +21,17 @@ 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 clause of a conditional answer parses, names only evidence, and
+  renders, including the clauses the current values don't select;
 - 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.
+- each `value` entry reads a file a pipeline stage produces, or one
+  declared with `imported_from`; anything else is an error, since a number
+  nothing computes is a magic number;
+- each other 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:
@@ -35,6 +40,8 @@ sentence:
   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;
+- does a claim resting on a threshold use a conditional answer, with a
+  threshold chosen before the value was known;
 - is the answer concise, and does it point at the publication section that
   carries the argument rather than repeating it.
 
@@ -104,7 +111,8 @@ evidence without showing them both.
    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.
+   `created_by` so the project says so. A `value` entry with no stage is
+   reported as an error rather than `unattributed`: give it a stage.
 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
@@ -127,7 +135,39 @@ project, not a tidy-up.
 - 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%}`.
+  precision the claim needs: `{ratio:.1f}x`, `{error:.0%}`. When several
+  come from one file, e.g., the outputs of one calculation, name them
+  together in one `result` entry's `values`, a map of name to key.
+- A `value` entry must read a file a pipeline stage writes. A placeholder
+  over a results file written by hand, including one you write, is a
+  retyped number with extra steps, and the check fails it. If no stage
+  produces the number, add one (`/calkit:add-pipeline-stage`) instead of
+  writing the file. Never declare a file `imported_from` or `created_by`
+  to clear that error unless it really came from there, and never edit a
+  results file to change what an answer says.
+- When the claim itself depends on a value, not just the number in it,
+  e.g., significant or not, which method wins, write a conditional answer
+  so the wording follows the evidence on a rerun:
+
+  ```yaml
+  answer:
+    if p < 0.05: "The closure cuts error by {improvement:.1f}x."
+    else: "The closure does not measurably reduce error."
+  evidence:
+    - kind: result
+      path: results/closure.json
+      values:
+        p: p-value
+        improvement: improvement
+  ```
+
+  Conditions use the names of values, so those names must be valid Python
+  identifiers. Every branch must be a
+  claim the evidence would support if it held. The threshold is part of
+  the claim: take it from the field's convention or the user, never pick
+  it to make the current branch hold, and don't use branches to hedge a
+  claim that should simply be weakened.
+
 - 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.

calkit/cli/latex.py

@@ -137,6 +137,43 @@ def from_json(
             json2latex.dump(cmd_name, formatted, f)
 
 
+@latex_app.command(name="from-questions")
+def from_questions(
+    output_fpaths: Annotated[
+        list[str],
+        typer.Option("--output", "-o", help="Output LaTeX file path(s)."),
+    ],
+    command_name: Annotated[
+        str,
+        typer.Option("--command", help="Command name to use in LaTeX output."),
+    ] = "questions",
+) -> None:
+    """Write the project's questions and answers as a LaTeX command.
+
+    Each question's text, hypothesis, answer, and notes are rendered from
+    their evidence and exposed as, e.g., ``\\questions[staging.answer]``,
+    keyed by the question's ``name`` or its 1-based position.
+    """
+    import json2latex
+
+    import calkit.questions
+
+    for out_path in output_fpaths:
+        if not out_path.endswith(".tex"):
+            raise_error("Output file must be a .tex file")
+    ck_info = calkit.load_calkit_info()
+    try:
+        values = calkit.questions.latex_values(ck_info)
+    except ValueError as e:
+        raise_error(str(e))
+    for out_path in output_fpaths:
+        outdir = os.path.dirname(out_path)
+        if outdir:
+            os.makedirs(outdir, exist_ok=True)
+        with open(out_path, "w") as f:
+            json2latex.dump(command_name, values, f)
+
+
 def _tex_cmd(
     tex_cmd: list[str],
     environment: str | None,

calkit/cli/list.py

@@ -197,7 +197,10 @@ def _echo_question(n: int, question: str | dict) -> None:
     question = dict(question)
     text = question.pop("question", "")
     typer.echo(f"{n}. question: {text}")
+    # Rendering fills every field, so leave out the ones that aren't set
     for k, v in question.items():
+        if v is None:
+            continue
         if isinstance(v, dict):
             typer.echo(f"    {k}:")
             for k1, v1 in v.items():
@@ -206,11 +209,17 @@ def _echo_question(n: int, question: str | dict) -> None:
             typer.echo(f"    {k}:")
             for item in v:
                 if isinstance(item, dict):
+                    item = {
+                        k1: v1 for k1, v1 in item.items() if v1 is not None
+                    }
                     for n1, (k1, v1) in enumerate(item.items()):
-                        if n1 == 0:
-                            typer.echo(f"      - {k1}: {v1}")
+                        prefix = "      - " if n1 == 0 else "        "
+                        if isinstance(v1, dict):
+                            typer.echo(f"{prefix}{k1}:")
+                            for k2, v2 in v1.items():
+                                typer.echo(f"          {k2}: {v2}")
                         else:
-                            typer.echo(f"        {k1}: {v1}")
+                            typer.echo(f"{prefix}{k1}: {v1}")
                 else:
                     typer.echo(f"        - {item}")
         else:
@@ -243,7 +252,7 @@ def list_questions(
         render_question,
     )
 
-    def _texts(question: dict) -> list[str]:
+    def _texts(question: dict) -> list[str | dict]:
         evidence = question.get("evidence") or []
         return [question.get(f) or "" for f in TEMPLATED_FIELDS] + [
             ev.get("explanation") or ""
@@ -260,16 +269,18 @@ def list_questions(
         # let a fresh clone read as a project that types its braces. Any
         # placeholder left standing counts, whether it names evidence that
         # could not be read or names nothing at all: a brace meant to stay
-        # in the text is written '{{' and never reaches here.
+        # in the text is written '{{' and never reaches here. A conditional
+        # answer still in clauses is one whose conditions could not be read.
         unfilled = any(
-            placeholders(text)
+            isinstance(text, dict) or placeholders(text)
             for q in rendered
             if isinstance(q, dict)
             for text in _texts(q)
         )
         if unfilled:
             warn(
-                "Some placeholders could not be filled from the evidence. "
+                "Some placeholders or conditions could not be filled from "
+                "the evidence. "
                 "Run 'calkit check questions' to see why; 'calkit pull' if "
                 "the results files are not here yet.",
                 err=json_output,

calkit/cli/main/core.py

@@ -684,10 +684,16 @@ def get_status(
         typer.echo()
     if "dvc" in categories:
         print_sep("DVC")
+        from dvc.exceptions import NotDvcRepoError
+
         try:
             calkit.dvc.get_dvc_repo()
-        except Exception:
+        except NotDvcRepoError:
             typer.echo("This is not a DVC repository.\n")
+        except Exception as e:
+            typer.echo(
+                f"Failed to open DVC repo: {e.__class__.__name__}: {e}\n"
+            )
         else:
             zip_path_map = calkit.dvc.zip.get_zip_path_map()
             dvc_repo = calkit.dvc.get_dvc_repo()
@@ -2699,14 +2705,19 @@ def run(
             os.environ.pop("CALKIT_PIPELINE_RUNNING", None)
             raise_error(f"Pipeline compilation failed: {e}")
     # Initialize DVC repo if necessary
+    from dvc.exceptions import NotDvcRepoError
+
     try:
         calkit.dvc.get_dvc_repo()
-    except Exception:
+    except NotDvcRepoError:
         if not quiet:
             typer.echo("Initializing DVC repo")
         result = calkit.dvc.init()
         if result != 0:
             raise_error("Failed to initialize DVC repo")
+    except Exception as e:
+        # E.g., DVC's site cache dir isn't writable, which 'dvc init' can't fix
+        raise_error(f"Failed to open DVC repo: {e.__class__.__name__}: {e}")
     # Convert deps into target stage names
     # TODO: This could probably be merged back upstream into DVC
     if dvc_stages is None:

calkit/cli/sync.py

@@ -39,12 +39,16 @@ def sync_dvc(
     no_check_auth: Annotated[bool, typer.Option("--no-check-auth")] = False,
 ) -> None:
     """Sync the DVC repository by pulling and then pushing."""
+    from dvc.exceptions import NotDvcRepoError
+
     from calkit.cli.main.core import pull, push
 
     try:
         calkit.dvc.get_dvc_repo()
-    except Exception:
+    except NotDvcRepoError:
         raise_error("No DVC repository found. Run 'calkit init' first.")
+    except Exception as e:
+        raise_error(f"Failed to open DVC repo: {e.__class__.__name__}: {e}")
     if not calkit.dvc.get_remotes():
         raise_error(
             "No DVC remotes configured. Add a remote with "

calkit/models/core.py

@@ -1703,8 +1703,12 @@ class FigureEvidence(BaseModel):
 
 class ResultsEvidence(BaseModel):
     """Evidence in the form of a results file: a set of values, a table, a
-    map, whatever the pipeline wrote. For one value inside such a file, use
-    ``value`` evidence, which can be templated into the answer.
+    map, whatever the pipeline wrote.
+
+    ``values`` names related values within it, like the fields of a struct
+    or object,
+    so each can be templated into the answer as ``value`` evidence would be
+    without an entry per value.
     """
 
     kind: Literal["result"] = "result"
@@ -1716,6 +1720,14 @@ class ResultsEvidence(BaseModel):
             "results file."
         ),
     )
+    values: dict[str, str] | None = Field(
+        default=None,
+        description=(
+            "Values within the results file, mapping each name, under which "
+            "it can be templated into the question's text, to its key. Names "
+            "must be unique within the question."
+        ),
+    )
     explanation: str | None = None
     git_ref: str | None = Field(
         default=None,
@@ -1725,11 +1737,17 @@ class ResultsEvidence(BaseModel):
         ),
     )
 
+    @model_validator(mode="after")
+    def _key_or_values(self) -> ResultsEvidence:
+        if self.key is not None and self.values is not None:
+            raise ValueError("a result takes 'values' or 'key', not both")
+        return self
+
 
 _KEY_DESCRIPTION = (
-    "Key of the value within the results file. A key present at the top "
-    "level is used as-is; otherwise it is split on dots and walked into "
-    "nested objects, with integers indexing lists."
+    "Key of the value within the results file. It is split on dots and "
+    "walked into nested objects, taking the longest run of parts that names "
+    "a key at each level, with integers indexing lists."
 )
 
 
@@ -1817,6 +1835,34 @@ class PublicationEvidence(BaseModel):
     )
 
 
+class DocumentEvidence(BaseModel):
+    """Evidence in the form of a document cited by path, e.g., a Markdown
+    write-up, without declaring it as a publication.
+
+    The document must be built by a pipeline stage, usually a Markdown
+    stage, so its numbers are injected from the results and go stale with
+    them; one written by hand is an error, like a typed-in value.
+    """
+
+    kind: Literal["document"] = "document"
+    path: str
+    section: str | None = Field(
+        default=None,
+        description=(
+            "Section of the document where the evidence is presented, as a "
+            "reader would find it, e.g., '4.2' or 'Results'."
+        ),
+    )
+    explanation: str | None = None
+    git_ref: str | None = Field(
+        default=None,
+        description=(
+            "Git reference (branch, tag, or commit hash) pointing to the "
+            "version of the repository where the document can be found."
+        ),
+    )
+
+
 class Question(BaseModel):
     """A question the project hopes to answer.
 
@@ -1839,9 +1885,26 @@ class Question(BaseModel):
     new evidence is how to say it still holds.
     """
 
+    name: str | None = Field(
+        default=None,
+        description=(
+            "Name for the question, e.g., for quoting its answer in a "
+            "document through 'calkit latex from-questions'. Unlike its "
+            "position in the list, it survives questions being added or "
+            "reordered. Must be unique among the project's questions."
+        ),
+    )
     question: str
     hypothesis: str | None = None
-    answer: str | None = None
+    answer: str | dict[str, str] | None = Field(
+        default=None,
+        description=(
+            "The claim the evidence supports. A mapping keyed by 'if "
+            "<condition>', 'elif <condition>' and 'else' picks its wording "
+            "from the evidence, so an answer resting on a threshold states "
+            "the other outcome instead of going stale when a value moves."
+        ),
+    )
     notes: str | None = Field(
         default=None,
         description=(
@@ -1858,10 +1921,23 @@ class Question(BaseModel):
             | ValueEvidence
             | TableEvidence
             | PublicationEvidence
+            | DocumentEvidence
         ]
         | None
     ) = None
 
+    @field_validator("name")
+    @classmethod
+    def check_name_not_a_position(cls, v: str | None) -> str | None:
+        # A question is also addressable by its position, so an all-digit
+        # name would be ambiguous with some other question's number
+        if v is not None and v.isdigit():
+            raise ValueError(
+                f"Question name {v!r} can't be a number, since questions "
+                "are also addressed by position"
+            )
+        return v
+
 
 class ProjectInfo(BaseModel):
     """All of the project's information or metadata, written to the
@@ -2066,3 +2142,14 @@ class ProjectInfo(BaseModel):
         description="Overleaf sync configuration, keyed by the path of the "
         "synced directory.",
     )
+
+    @field_validator("questions")
+    @classmethod
+    def check_question_names_unique(
+        cls, v: list[str | Question]
+    ) -> list[str | Question]:
+        names = [q.name for q in v if isinstance(q, Question) and q.name]
+        dupes = sorted({n for n in names if names.count(n) > 1})
+        if dupes:
+            raise ValueError(f"Question names must be unique: {dupes}")
+        return v

calkit/models/pipeline.py

@@ -254,6 +254,7 @@ class Stage(BaseModel):
         "marimo-html-wasm",
         "markdown",
         "procedure",
+        "questions-to-latex",
     ] = Field(description="What kind of stage this is.")
     environment: str = Field(
         description="Name of the environment in which to run this stage."
@@ -1343,6 +1344,56 @@ class JsonToLatexStage(Stage):
         return outs
 
 
+class QuestionsToLatexStage(Stage):
+    """The project's questions and answers, rendered for a LaTeX document.
+
+    Its inputs are ``calkit.yaml`` and every file the questions cite as
+    evidence, added when the pipeline is compiled, so the output reruns
+    when an answer or a value it reads changes.
+    """
+
+    kind: Literal["questions-to-latex"] = "questions-to-latex"
+    environment: str = "_system"
+    command_name: str = Field(
+        default="questions",
+        description=(
+            "Name of the LaTeX command the document quotes questions "
+            "through, e.g., 'questions' for \\questions[staging.answer]."
+        ),
+    )
+    wdir: None = Field(
+        default=None,
+        description="Not supported; the stage reads the project's "
+        "calkit.yaml and evidence from the project root.",
+    )
+
+    @property
+    def dvc_cmd(self) -> str:
+        cmd = "calkit latex from-questions"
+        for out in self.outputs:
+            out_path = out if isinstance(out, str) else out.path
+            cmd += f" --output {shlex.quote(out_path)}"
+        return cmd + f" --command {shlex.quote(self.command_name)}"
+
+    @property
+    def dvc_outs(self) -> list[str | dict]:
+        """Stored with Git by default, like other generated LaTeX."""
+        outs: list[str | dict] = []
+        for out in self.outputs:
+            if isinstance(out, str):
+                outs.append({out: dict(cache=False, persist=False)})
+            elif isinstance(out, PathOutput):
+                outs.append(
+                    {
+                        out.path: dict(
+                            cache=out.storage == "dvc",
+                            persist=not out.delete_before_run,
+                        )
+                    }
+                )
+        return outs
+
+
 class MatlabScriptStage(Stage):
     kind: Literal["matlab-script"]
     script_path: RelativeChildPathString = Field(
@@ -2096,6 +2147,7 @@ class Pipeline(BaseModel):
                 | LatexStage
                 | QuartoStage
                 | JsonToLatexStage
+                | QuestionsToLatexStage
                 | MatlabScriptStage
                 | MatlabCommandStage
                 | ShellCommandStage

calkit/notebooks.py

@@ -96,6 +96,11 @@ def clean_notebook(nb: dict) -> dict:
         if cell.get("cell_type") == "code":
             cell["outputs"] = []
             cell["execution_count"] = None
+        # Cell IDs are editor residue, and nbstripout rewrites them to
+        # ordinals. Keeping them would make the cleaned copy depend on whether
+        # the source had been through a clean filter, which differs between a
+        # working tree and a fresh clone of the same commit.
+        cell.pop("id", None)
         # Clean metadata but keep tags
         if "tags" in cell.get("metadata", {}):
             cell["metadata"] = {"tags": cell["metadata"]["tags"]}

calkit/pipeline.py

@@ -1634,6 +1634,7 @@ def to_dvc(
     """
     import calkit.dvc.zip
     import calkit.markdown
+    import calkit.questions
     from calkit.environments import get_env_input_paths, get_env_lock_fpath
 
     if ck_info is None:
@@ -1645,6 +1646,8 @@ def to_dvc(
     # options and iteration need no knowledge of Markdown.
     markdown = calkit.markdown.expand_ck_info(ck_info, wdir=wdir)
     ck_info = markdown.ck_info
+    # Likewise give questions-to-latex stages the evidence they read
+    ck_info = calkit.questions.expand_questions_stages(ck_info)
     if write and markdown.environments:
         _write_markdown_environments(markdown, wdir=wdir)
     # Everything Markdown derives is rewritten on every compile, so it