calkit-python 0.47.4__py3-none-any.whl → 0.47.6__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
@@ -128,6 +136,38 @@ project, not a tidy-up.
   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%}`.
+- 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: value
+      path: results/closure.json
+      key: p-value
+      name: p
+    - kind: value
+      path: results/closure.json
+      key: improvement
+  ```
+
+  Conditions name `value` evidence, so those names must be valid Python
+  identifiers; give the entry a `name` otherwise. 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/list.py

@@ -243,7 +243,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 +260,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,
@@ -333,21 +335,44 @@ def list_environments(
 
 @list_app.command(name="templates")
 def list_templates(
+    kind: Annotated[
+        str | None,
+        typer.Option("--kind", "-k", help="Only show templates of one kind."),
+    ] = None,
     json_output: Annotated[
         bool, typer.Option("--json", help="Output result as JSON.")
     ] = False,
 ):
-    """List all available Calkit templates."""
-    names = [
-        f"{kind}/{name}"
-        for kind, tpl_dict in calkit.templates.TEMPLATES.items()
-        for name in tpl_dict
-    ]
+    """List all available Calkit templates, grouped by kind.
+
+    A template is named by its kind and name, except a project template,
+    which names a project on a hub and so is ``owner/project``.
+    """
+    try:
+        templates = calkit.templates.get_templates(kind=kind)
+    except ValueError as e:
+        raise_error(str(e))
+    groups: dict[str, list[dict]] = {}
+    for template in templates:
+        groups.setdefault(template.kind, []).append(
+            {
+                "name": template.ref,
+                "title": template.title,
+                "description": template.description,
+            }
+        )
     if json_output:
-        echo_json(names)
+        echo_json(groups)
         return
-    for name in names:
-        typer.echo(name)
+    for i, (group, entries) in enumerate(groups.items()):
+        if i:
+            typer.echo()
+        typer.echo(f"{group}:")
+        for entry in entries:
+            typer.echo(f"  {entry['name']}")
+            for key in ("title", "description"):
+                if entry[key]:
+                    typer.echo(f"    {entry[key]}")
 
 
 @list_app.command(name="installers")
@@ -368,17 +393,30 @@ def list_installers(
     groups: dict[int, list[str]] = {}
     for name, entry in calkit.install.INSTALLERS.items():
         groups.setdefault(id(entry), []).append(name)
+    # What Calkit has already installed here, so the listing doubles as a
+    # record of changes it made to this machine
+    installed = {
+        rec["app"]: rec["installed_at"]
+        for rec in calkit.install.read_install_log()
+    }
     result: list[dict] = []
     for names in groups.values():
         names.sort()
         entry = calkit.install.INSTALLERS[names[0]]
         scripts = {}
-        for platform in ("unix", "windows"):
+        for platform in ("unix", "mac", "linux", "windows"):
             ins = entry.get(platform)  # type: ignore[call-overload]
             if ins is not None:
                 scripts[platform] = ins["script"]
         result.append(
-            {"name": names[0], "aliases": names[1:], "scripts": scripts}
+            {
+                "name": names[0],
+                "aliases": names[1:],
+                "scripts": scripts,
+                "installed_by_calkit": next(
+                    (installed[n] for n in names if n in installed), None
+                ),
+            }
         )
     if json_output:
         echo_json(result)
@@ -388,6 +426,10 @@ def list_installers(
         header = installer["name"] + (
             f"  (aliases: {aliases})" if aliases else ""
         )
+        if installer["installed_by_calkit"]:
+            header += (
+                f"  [installed by Calkit {installer['installed_by_calkit']}]"
+            )
         typer.echo(header)
         for platform, script in installer["scripts"].items():
             typer.echo(f"  {platform}: {script}")

calkit/cli/main/core.py

@@ -2936,10 +2936,11 @@ def run(
         in_main_thread = threading.current_thread() is threading.main_thread()
         old_handler = None
         handler_set = False
-        with open(log_fpath, "a", encoding="utf-8") as log_f:
+        with open(log_fpath, "a", encoding="utf-8", errors="replace") as log_f:
             log_f.write(STAGE_OUTPUT_START + "\n")
             log_f.flush()
             try:
+                kwargs.setdefault("errors", "replace")
                 p = subprocess.Popen(exec_cmd, **kwargs)
                 if in_main_thread:
                     old_handler = signal.signal(signal.SIGINT, signal.SIG_IGN)

calkit/cli/new.py

@@ -434,17 +434,26 @@ def new_project(
         )
         if template_git_url is None:
             project = "/".join(template_name.split("/")[:2])
-            typer.echo(f"Fetching Git repo URL for {project} from the hub")
-            try:
-                template_git_url = calkit.hub.get(f"/projects/{project}")[
-                    "git_repo_url"
-                ]
-            except Exception as e:
-                raise_error(
-                    f"Could not fetch project {project} from the hub ({e}); "
-                    "for a repo not on the hub, pass its URL, e.g., "
-                    f"https://github.com/{template_name}"
-                )
+            # A template this package knows about carries its own repo URL,
+            # so the common case needs no hub: no request, no login, and it
+            # still works offline once the repo is reachable.
+            known = calkit.templates.find_project_template(project)
+            if known is not None:
+                if verbose:
+                    typer.echo(f"Using known template {project}")
+                template_git_url = known.git_repo_url
+            else:
+                typer.echo(f"Fetching Git repo URL for {project} from the hub")
+                try:
+                    template_git_url = calkit.hub.get(f"/projects/{project}")[
+                        "git_repo_url"
+                    ]
+                except Exception as e:
+                    raise_error(
+                        f"Could not fetch project {project} from the hub "
+                        f"({e}); for a repo not on the hub, pass its URL, "
+                        f"e.g., https://github.com/{template_name}"
+                    )
         if template_subdir is None:
             # Now clone it
             subprocess.run(["git", "clone", template_git_url, abs_path])

calkit/config.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 import os
 import platform
 import warnings
+from collections.abc import Iterator
+from contextlib import contextmanager
 from typing import Any, Literal
 from typing import get_args as get_type_args
 
@@ -26,7 +28,8 @@ def _probe_keyring() -> bool:
     """
     try:
         # Attempt to get a password (this will trigger backend initialization)
-        keyring.get_password("test_service", "test_user")
+        with _keyring_home():
+            keyring.get_password("test_service", "test_user")
         return True
     except keyring.errors.NoKeyringError:
         return False
@@ -142,6 +145,40 @@ def _get_project_hub() -> str | None:
     return hub
 
 
+# Where set_env_vars keeps the user's own home directory when a project's
+# env_vars change it, e.g., to /tmp for a tool a stage runs, so Calkit still
+# finds its config, credentials, and caches
+USER_HOME_ENV_VAR = "CALKIT_USER_HOME"
+
+
+def get_user_home() -> str:
+    """The home directory Calkit keeps its own files in."""
+    return os.environ.get(USER_HOME_ENV_VAR) or os.path.expanduser("~")
+
+
+@contextmanager
+def _keyring_home() -> Iterator[None]:
+    """Point HOME at the user's own home for a keyring call.
+
+    The macOS keychain finds the login keychain through HOME when it's
+    called, so a project that points HOME elsewhere would otherwise hide
+    every stored secret, including hub credentials.
+    """
+    user_home = os.environ.get(USER_HOME_ENV_VAR)
+    old_home = os.environ.get("HOME")
+    if user_home is None or user_home == old_home:
+        yield
+        return
+    os.environ["HOME"] = user_home
+    try:
+        yield
+    finally:
+        if old_home is None:
+            os.environ.pop("HOME", None)
+        else:
+            os.environ["HOME"] = old_home
+
+
 def _get_default_hub() -> str | None:
     """Read ``default_hub`` from the base (unsuffixed) config file.
 
@@ -150,7 +187,7 @@ def _get_default_hub() -> str | None:
     """
     import yaml
 
-    fpath = os.path.join(os.path.expanduser("~"), ".calkit", "config.yaml")
+    fpath = os.path.join(get_user_home(), ".calkit", "config.yaml")
     try:
         with open(fpath) as f:
             data = yaml.safe_load(f) or {}
@@ -275,7 +312,7 @@ def get_local_config_path() -> str:
 
 def get_config_yaml_fpath() -> str:
     return os.path.join(
-        os.path.expanduser("~"),
+        get_user_home(),
         ".calkit",
         f"config{get_env_suffix()}.yaml",
     )
@@ -291,11 +328,12 @@ def set_secret(key: str, value: str) -> None:
     """Sets a secret using keyring, handling byte conversion for Linux."""
     service_name = get_app_name()
     username = _keyring_username(key)
-    if platform.system() == "Linux":
-        value_bytes = value.encode("utf-8")
-        keyring.set_password(service_name, username, value_bytes)  # type: ignore
-    else:
-        keyring.set_password(service_name, username, value)
+    with _keyring_home():
+        if platform.system() == "Linux":
+            value_bytes = value.encode("utf-8")
+            keyring.set_password(service_name, username, value_bytes)  # type: ignore
+        else:
+            keyring.set_password(service_name, username, value)
     _secret_cache[(service_name, username)] = value
 
 
@@ -306,7 +344,8 @@ def get_secret(key: str) -> str | None:
     cache_key = (service_name, username)
     if cache_key in _secret_cache:
         return _secret_cache[cache_key]
-    password = keyring.get_password(service_name, username)
+    with _keyring_home():
+        password = keyring.get_password(service_name, username)
     if platform.system() == "Linux" and isinstance(password, bytes):
         password = password.decode("utf-8")
     _secret_cache[cache_key] = password
@@ -318,7 +357,8 @@ def delete_secret(key: str) -> None:
     service_name = get_app_name()
     username = _keyring_username(key)
     _secret_cache.pop((service_name, username), None)
-    keyring.delete_password(service_name, username)
+    with _keyring_home():
+        keyring.delete_password(service_name, username)
 
 
 class KeyringOptionalSecret(str):

calkit/core.py

@@ -945,7 +945,13 @@ def check_requirements(
                         described_as=described_as,
                     )
                 continue
-        raise ValueError(f"app '{dep_name}' not found on {described_as}")
+        # Some apps have no installer here but a known way in, e.g., a
+        # system package manager on Linux
+        hint = _install.get_unsupported_message(dep_name)
+        raise ValueError(
+            f"app '{dep_name}' not found on {described_as}"
+            + (f"; {hint}" if hint else "")
+        )
     for dep in buckets.get("_other", []):
         dep_name = dep["name"]
         dep_kind = dep["kind"]
@@ -1449,5 +1455,13 @@ def set_env_vars(ck_info: dict, cli: bool = True) -> None:
             raise_error(msg)
         else:
             raise ValueError(msg)
+    # A project that points the home directory elsewhere, e.g., at /tmp for
+    # a tool a stage runs, would otherwise hide the user's Calkit config,
+    # and with it their credentials, from every Calkit command it runs
+    import calkit.config
+
+    home = os.path.expanduser("~")
     for k, v in env_vars.items():
         os.environ[str(k)] = str(v)
+    if os.path.expanduser("~") != home:
+        os.environ.setdefault(calkit.config.USER_HOME_ENV_VAR, home)

calkit/environments.py

@@ -930,8 +930,10 @@ def write_system_env_lock(
 
 
 def get_cache_db(name="cache") -> SqliteDict:
+    from calkit.config import get_user_home
+
     env_check_cache_dir = os.path.join(
-        os.path.expanduser("~"), ".calkit", "env-checks"
+        get_user_home(), ".calkit", "env-checks"
     )
     os.makedirs(env_check_cache_dir, exist_ok=True)
     env_check_cache_path = os.path.join(env_check_cache_dir, f"{name}.sqlite")