techtree 0.1.0__py3-none-any.whl

techtree/doctor/service.py

@@ -0,0 +1,326 @@
+"""Running the checks and deciding what to do about them. Spec section 13.2.
+
+The service owns three decisions the CLI must not make for itself: the order
+checks run in, which failures actually block, and which repairs are worth
+offering. Keeping them here is what lets the Doctor command be nine lines of
+plumbing with no opinion in it.
+
+Repairs are chosen by priority and capped at three. Some problems have a
+concrete argument vector that fixes them — a permissions change, an engine
+install. Others cannot be fixed by anything Techtree is allowed to run, and for
+those the action's argv is the re-check and the reason says what a person has
+to do first. That is deliberate: a next action is a promise that running the
+vector is safe and sensible, so it never carries a placeholder to be filled in
+or an installer piped out of the network.
+
+When nothing needs repair the caller is not left without a next step. The
+useful thing to do on a healthy host is to look at what there is to climb.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Final
+
+from techtree.doctor.checks import (
+    check_active_engine,
+    check_docker_cli,
+    check_docker_daemon,
+    check_hermes_cli,
+    check_hermes_plugin,
+    check_host_platform,
+    check_python_version,
+    check_techtree_home,
+    check_uv_cli,
+    detect_host_platform,
+)
+from techtree.doctor.execution_checks import execution_checks
+from techtree.engines.registry import EngineRegistry
+from techtree.models.base import NonEmptyString, ProtocolModel
+from techtree.models.campaign import CampaignSpec
+from techtree.models.cli import MAX_NEXT_ACTIONS, CheckStatus, DoctorCheck, NextAction
+from techtree.paths import TechtreePaths
+from techtree.settings import Settings
+from techtree.version import version_info
+
+__all__ = ["DoctorReport", "DoctorService"]
+
+#: Where uv's own installation instructions live. It goes in a reason, never in
+#: an argument vector: Techtree does not offer to pipe an installer into a
+#: shell on someone's behalf.
+UV_INSTALL_DOCUMENTATION: Final = (
+    "https://docs.astral.sh/uv/getting-started/installation/"
+)
+
+
+class DoctorReport(ProtocolModel):
+    """Everything one Doctor run found.
+
+    The two platform strings are separate on purpose. ``host_platform`` is
+    where Techtree runs; ``docker_platform`` is where an evaluated subject
+    would run, and is absent whenever the daemon could not say.
+    """
+
+    techtree_home: NonEmptyString
+    host_platform: NonEmptyString | None
+    docker_platform: NonEmptyString | None
+    versions: dict[str, NonEmptyString]
+    checks: list[DoctorCheck]
+
+
+class DoctorService:
+    """Runs environment checks and turns them into repairs."""
+
+    def __init__(self, paths: TechtreePaths, settings: Settings) -> None:
+        self._paths = paths
+        self._settings = settings
+
+    def run(
+        self,
+        *,
+        for_evaluation: bool = False,
+        campaign: CampaignSpec | None = None,
+    ) -> list[DoctorCheck]:
+        """Run checks in deterministic order.
+
+        ``for_evaluation`` adds the execution checks of spec section 6.18 and
+        makes them blocking. An ordinary Doctor is a question about the machine
+        and answers it with warnings; the evaluation Doctor is the gate in front
+        of a run that provisions containers and spends money on model calls, so
+        the same facts stop it rather than merely being noted.
+
+        A ``campaign`` narrows the question from "could anything run here" to
+        "could this run here", which is the only form in which the subject's
+        credential and image can be checked at all.
+        """
+        host_platform = detect_host_platform()
+        checks = [
+            check_python_version(),
+            check_host_platform(host_platform),
+            check_techtree_home(self._paths),
+            check_uv_cli(),
+            check_docker_cli(),
+            check_docker_daemon(),
+            check_hermes_cli(),
+            check_hermes_plugin(),
+            check_active_engine(self._paths, self._settings),
+        ]
+        if not for_evaluation:
+            return checks
+        registry = EngineRegistry(self._paths, self._settings)
+        checks.extend(execution_checks(engine_registry=registry, campaign=campaign))
+        return checks
+
+    def report(self, checks: list[DoctorCheck]) -> DoctorReport:
+        """Project the checks into the command's response payload."""
+        return DoctorReport(
+            techtree_home=str(self._paths.root),
+            host_platform=_metadata_string(checks, "host_platform", "host_platform"),
+            docker_platform=_metadata_string(
+                checks, "docker_daemon", "docker_platform"
+            ),
+            versions=version_info(),
+            checks=list(checks),
+        )
+
+    def blocking_failures(self, checks: list[DoctorCheck]) -> list[DoctorCheck]:
+        """Return blocking failures."""
+        return [check for check in checks if check.blocking]
+
+    def warnings(self, checks: list[DoctorCheck]) -> list[DoctorCheck]:
+        """Return warnings."""
+        return [
+            check
+            for check in checks
+            if check.status is CheckStatus.WARN
+            or (check.status is CheckStatus.FAIL and not check.blocking)
+        ]
+
+    def next_actions(self, checks: list[DoctorCheck]) -> list[NextAction]:
+        """Create no more than three repair actions."""
+        by_id = {check.id: check for check in checks}
+        actions: list[NextAction] = []
+        offered: set[str] = set()
+
+        for check_id, build in _REPAIRS:
+            check = by_id.get(check_id)
+            if check is None or check.status in (CheckStatus.PASS, CheckStatus.SKIP):
+                continue
+            action = build(self._paths)
+            # Two checks can share one repair — a missing Docker CLI and an
+            # unreachable daemon are both fixed by installing and starting it.
+            if action is None or action.id in offered:
+                continue
+            actions.append(action)
+            offered.add(action.id)
+            if len(actions) == MAX_NEXT_ACTIONS:
+                return actions
+
+        if actions:
+            return actions
+        # Nothing offered a repair. That means either the host is fine, or the
+        # only things wrong with it are things Techtree cannot fix — a Campaign
+        # that is not meant to be executed yet, for instance. Saying "this host
+        # is ready" in the second case would be a lie told cheerfully.
+        return [_browse_climbs(ready=not any(check.blocking for check in checks))]
+
+
+def _metadata_string(
+    checks: Iterable[DoctorCheck], check_id: str, key: str
+) -> str | None:
+    """Read one string out of a check's metadata, if the check reported it."""
+    for check in checks:
+        if check.id != check_id:
+            continue
+        value = check.metadata.get(key)
+        return value if isinstance(value, str) else None
+    return None
+
+
+def _fix_home_permissions(paths: TechtreePaths) -> NextAction:
+    return NextAction(
+        id="fix_techtree_home_permissions",
+        label="Make the Techtree home directory private and writable",
+        reason="Techtree stores drafts, runs, and engines there for one user only.",
+        cli=["chmod", "700", str(paths.root)],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=True,
+    )
+
+
+def _install_supported_python(_: TechtreePaths) -> NextAction:
+    return NextAction(
+        id="install_supported_python",
+        label="Install a supported Python and re-run Doctor",
+        reason="Techtree requires Python 3.12 or 3.13.",
+        cli=["uv", "python", "install", "3.12"],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=True,
+    )
+
+
+def _install_engine(_: TechtreePaths) -> NextAction:
+    return NextAction(
+        id="install_engine",
+        label="Install the managed evaluation engine",
+        reason="Preparing or starting a Climb needs an installed, active engine.",
+        cli=["techtree", "engine", "install"],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=False,
+    )
+
+
+def _recheck_after_installing_uv(_: TechtreePaths) -> NextAction:
+    return NextAction(
+        id="recheck_after_installing_uv",
+        label="Install uv, then re-run Doctor",
+        reason=(
+            "The managed evaluation engine is installed with uv. Installation "
+            f"instructions: {UV_INSTALL_DOCUMENTATION}"
+        ),
+        cli=["techtree", "doctor"],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=False,
+    )
+
+
+def _recheck_after_starting_docker(_: TechtreePaths) -> NextAction:
+    return NextAction(
+        id="recheck_after_starting_docker",
+        label="Start Docker, then re-run Doctor",
+        reason="An evaluated subject runs in a container on this host.",
+        cli=["techtree", "doctor"],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=False,
+    )
+
+
+def _unsupported_host(_: TechtreePaths) -> None:
+    """No repair exists for the wrong machine, so no action is offered."""
+    return None
+
+
+def _sign_in_to_prime(_: TechtreePaths) -> NextAction:
+    return NextAction(
+        id="sign_in_to_prime",
+        label="Sign in to Prime, then re-run this check",
+        reason=(
+            "The evaluated subject's model calls are paid for by a credential "
+            "a run reads for itself, which is why signing in to Prime works "
+            "and exporting the credential in a terminal does not. It is "
+            "separate from whatever your own agent is signed in with. After "
+            "signing in, run techtree doctor --for-evaluation again."
+        ),
+        cli=["prime", "login"],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=True,
+    )
+
+
+def _pull_subject_image(_: TechtreePaths) -> NextAction:
+    return NextAction(
+        id="pull_subject_image",
+        label="Pull the subject's container image, then re-run this check",
+        reason=(
+            "The evaluated subject runs in the image the Campaign pins. "
+            "Downloading it is a deliberate setup step, so Techtree reports it "
+            "rather than doing it during a check."
+        ),
+        cli=["techtree", "doctor", "--for-evaluation"],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=False,
+    )
+
+
+def _not_runnable_yet(_: TechtreePaths) -> None:
+    """A Campaign that is not meant to be executed has no repair."""
+    return None
+
+
+def _browse_climbs(*, ready: bool) -> NextAction:
+    return NextAction(
+        id="list_climbs",
+        label="Browse the available Climbs",
+        reason=(
+            "This host is ready."
+            if ready
+            else (
+                "Nothing left to fix automatically; each failed check says what "
+                "it needs."
+            )
+        ),
+        cli=["techtree", "climb", "list"],
+        hermes_tool=None,
+        hermes_args=None,
+        requires_user_confirmation=False,
+    )
+
+
+#: Check identifier to repair builder, most important first. A builder returns
+#: None when the problem is real and nothing runnable would fix it.
+type _Repair = Callable[[TechtreePaths], NextAction | None]
+
+_REPAIRS: Final[tuple[tuple[str, _Repair], ...]] = (
+    ("techtree_home", _fix_home_permissions),
+    ("python_version", _install_supported_python),
+    ("host_platform", _unsupported_host),
+    ("uv", _recheck_after_installing_uv),
+    ("active_engine", _install_engine),
+    ("docker_cli", _recheck_after_starting_docker),
+    ("docker_daemon", _recheck_after_starting_docker),
+    # Spec section 6.18. These only appear under --for-evaluation, and they sit
+    # last because a host that fails an ordinary check fails these too, and the
+    # ordinary repair is the one worth offering first.
+    ("execution_docker_platform", _recheck_after_starting_docker),
+    ("execution_engine_eval", _install_engine),
+    ("execution_model_credential", _sign_in_to_prime),
+    ("execution_subject_image", _pull_subject_image),
+    ("execution_live_campaign", _not_runnable_yet),
+)

techtree/drafts/__init__.py

@@ -0,0 +1,32 @@
+"""Immutable submission drafts and the one-time handover that starts one.
+
+Spec PR6 §6.7.
+
+A draft is the complete, reviewable statement of what a participant is about to
+run: the public graph it came from, the two experiment variants, the proof that
+those variants differ only where permitted, the snapshotted candidate skill,
+and the rights the participant is being asked to accept. Once written it is
+never edited. A change of mind is a new draft.
+
+Two modules divide the work:
+
+:mod:`techtree.drafts.source`
+    What a draft is prepared against: a Campaign, its DataPolicy, its
+    publisher validation receipt, and the public Climb that invited it when
+    there is one. A Skill replacement (spec section 7.19) is derived locally
+    and no Climb wraps it, so the Climb is the one part that may be absent.
+
+:mod:`techtree.drafts.store`
+    Placement, verification, and the start claim. Where each file lives under
+    ``drafts/draft_<id>/``, how the whole graph is re-verified offline without
+    consulting the catalog, and the exactly-once handover to a run.
+
+Preparing a draft is not accepting its data policy. Decisions document 0019
+section 2 puts the acceptance where a person can act on it: the draft is
+reviewed, the review is answered, and the run records that it was — nothing
+here may be read as consent.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

techtree/drafts/source.py

@@ -0,0 +1,146 @@
+"""What a draft is prepared against, with or without a public Climb.
+
+Every draft this build produced before WP7d came from a
+:class:`~techtree.models.climb.ResolvedClimb`: a public invitation wrapping a
+Campaign. Spec section 7.19 asks for one that does not. A Skill-replacement
+Campaign is derived locally from a run that already finished, and no Climb
+wraps it — :class:`~techtree.models.climb.CandidatePolicy` can only require
+``skill_insertion``, so a ``ResolvedClimb`` holding a replacement Campaign is
+unrepresentable rather than merely unusual.
+
+:class:`CampaignSource` is what the kernel carries instead. It holds the three
+objects a run's science actually needs — the Campaign, the DataPolicy it runs
+under, and the publisher's taskset validation receipt — and the public Climb
+beside them when there is one. Preparation, the draft store, the run's staged
+inputs, and the report stage all read it, so a local replacement travels the
+same path as a public submission rather than a parallel one.
+
+Two properties are deliberate.
+
+*The Climb's own edge checks stay in one place.* When a source comes from a
+Climb it comes through :meth:`CampaignSource.from_climb`, which takes an
+already-validated ``ResolvedClimb``; when it is read back from disk the Climb
+is reassembled into a ``ResolvedClimb`` first, so its validator runs on the
+bytes. Nothing here re-implements those checks, and a Climb-free source is not
+given a weaker version of them: it has no Climb to check.
+
+*A source is a container, not an authority.* The Campaign-to-DataPolicy and
+Campaign-to-receipt edges are verified where the bytes are — in
+:meth:`~techtree.drafts.store.DraftStore.verify_snapshot` and in
+:class:`~techtree.runs.artifacts.RunArtifactStore` — because those are the
+places that know which digest a *request* said to expect.
+
+:class:`StagedSkill` is the other half of the same generalization. An insertion
+stages one Skill, the candidate's. A replacement stages two, because the
+baseline variant carries the Skill being revised and the subject has to be
+given its files, not just its digest.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from techtree.canonical import digest_object
+from techtree.models.base import Digest
+from techtree.models.campaign import CampaignSpec, MutationKind, PublicContext
+from techtree.models.climb import ClimbManifest, ResolvedClimb
+from techtree.models.data_policy import DataPolicy
+from techtree.models.skill import SkillArtifact
+from techtree.models.validation import TasksetValidationReceipt
+
+__all__ = ["CampaignSource", "StagedSkill"]
+
+
+@dataclass(frozen=True)
+class StagedSkill:
+    """One Skill as a draft or a run owns it: the artifact and its bytes."""
+
+    artifact: SkillArtifact
+    archive: Path
+    files: Path
+
+
+@dataclass(frozen=True)
+class CampaignSource:
+    """The Campaign graph a draft is prepared against.
+
+    ``climb`` and ``climb_digest`` are present together or absent together: a
+    Climb-free source is a local Campaign, which spec section 7.19 derives for
+    a Skill replacement and which no public invitation wraps.
+    """
+
+    campaign: CampaignSpec
+    campaign_digest: Digest
+    data_policy: DataPolicy
+    data_policy_digest: Digest
+    publisher_validation: TasksetValidationReceipt
+    publisher_validation_digest: Digest
+    climb: ClimbManifest | None
+    climb_digest: Digest | None
+
+    def __post_init__(self) -> None:
+        """Reject a half-present Climb, which no reader could interpret."""
+        if (self.climb is None) != (self.climb_digest is None):
+            raise ValueError(
+                "a campaign source names a public Climb and the digest it was "
+                "loaded under together, or neither"
+            )
+
+    @classmethod
+    def from_climb(cls, resolved: ResolvedClimb) -> CampaignSource:
+        """Return the source one resolved public Climb describes."""
+        return cls(
+            campaign=resolved.campaign,
+            campaign_digest=resolved.campaign_digest,
+            data_policy=resolved.data_policy,
+            data_policy_digest=resolved.data_policy_digest,
+            publisher_validation=resolved.publisher_validation,
+            publisher_validation_digest=resolved.publisher_validation_digest,
+            climb=resolved.climb,
+            climb_digest=resolved.climb_digest,
+        )
+
+    @classmethod
+    def local(
+        cls,
+        *,
+        campaign: CampaignSpec,
+        data_policy: DataPolicy,
+        publisher_validation: TasksetValidationReceipt,
+    ) -> CampaignSource:
+        """Return a source for a locally derived Campaign that no Climb wraps."""
+        return cls(
+            campaign=campaign,
+            campaign_digest=digest_object(campaign),
+            data_policy=data_policy,
+            data_policy_digest=digest_object(data_policy),
+            publisher_validation=publisher_validation,
+            publisher_validation_digest=digest_object(publisher_validation),
+            climb=None,
+            climb_digest=None,
+        )
+
+    @property
+    def public_context(self) -> PublicContext | None:
+        """Return the public context artifacts built from this source carry."""
+        if self.climb_digest is None:
+            return None
+        return PublicContext(kind="climb", climb_digest=self.climb_digest)
+
+    @property
+    def title(self) -> str:
+        """Return what to call this comparison in a result a person reads.
+
+        A public Climb has a title written for readers. A locally derived
+        Campaign has only its own identity, and saying so is better than
+        inventing a name for it.
+        """
+        if self.climb is not None:
+            return self.climb.metadata.title
+        return f"{self.campaign.metadata.id} v{self.campaign.metadata.version}"
+
+    @property
+    def replaces_a_skill(self) -> bool:
+        """Return whether this Campaign's baseline carries the Skill being revised."""
+        return self.campaign.mutation_contract.kind is MutationKind.SKILL_REPLACEMENT