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

calkit/agent_skills/check-questions/SKILL.md

@@ -135,7 +135,9 @@ 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
@@ -152,17 +154,15 @@ project, not a tidy-up.
     if p < 0.05: "The closure cuts error by {improvement:.1f}x."
     else: "The closure does not measurably reduce error."
   evidence:
-    - kind: value
+    - kind: result
       path: results/closure.json
-      key: p-value
-      name: p
-    - kind: value
-      path: results/closure.json
-      key: improvement
+      values:
+        p: p-value
+        improvement: improvement
   ```
 
-  Conditions name `value` evidence, so those names must be valid Python
-  identifiers; give the entry a `name` otherwise. Every branch must be a
+  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

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:

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,6 +1885,15 @@ 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 | dict[str, str] | None = Field(
@@ -1866,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
@@ -2074,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