techtree 0.1.0__py3-none-any.whl

techtree/models/catalog.py

@@ -0,0 +1,227 @@
+"""The packaged catalog and what it can tell a caller. Decisions 0003 A6/A7.
+
+Three things live here.
+
+The *index* is the map from a public Climb reference, and from every object
+digest it depends on, to a file inside the package. It is generated, never
+hand-edited, and it is typed and schema'd so that a hand-edit is caught rather
+than shipped. Paths are relative and non-escaping; digests appear once; two
+digests never claim the same file.
+
+The *summary* is what ``techtree climb show`` needs in one object: identity,
+what is being measured, and the rights the participant would be agreeing to.
+``DataPolicySummary`` is a deliberate projection rather than the whole
+``DataPolicy``, because a listing that reprinted the full policy tree would be
+read by nobody.
+
+The *compatibility result* is the honest answer to "could I actually run this
+here?" — host platform, engine state, evaluation backend — as a list of typed
+issues. ``compatible`` is derived from the blocking issues rather than asserted
+alongside them, so a result cannot claim to be runnable while listing the
+reason it is not. Before WP4 an absent engine blocks ``prepare`` while ``list``
+and ``show`` still display the Climb.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Literal, Self
+
+from pydantic import Field, model_validator
+
+from techtree.models.base import Digest, NonEmptyString, ProtocolModel
+from techtree.models.evaluation_backend import EvaluationBackendKind
+
+__all__ = [
+    "CatalogClimbEntry",
+    "CatalogIndex",
+    "CatalogObjectLocation",
+    "ClimbSummary",
+    "CompatibilityIssue",
+    "CompatibilityResult",
+    "DataPolicySummary",
+    "EngineCompatibilityStatus",
+]
+
+
+def _check_relative_catalog_path(value: str) -> str:
+    """Reject absolute, escaping, or non-POSIX catalog paths."""
+    if value != value.strip():
+        raise ValueError(f"catalog path has surrounding whitespace: {value!r}")
+    if value.startswith("/") or (len(value) > 1 and value[1] == ":"):
+        raise ValueError(f"catalog paths are relative to the catalog root: {value!r}")
+    if "\\" in value:
+        raise ValueError(f"catalog paths use forward slashes: {value!r}")
+    if any(segment in ("", ".", "..") for segment in value.split("/")):
+        raise ValueError(f"catalog path is not a normalized relative path: {value!r}")
+    return value
+
+
+# ---------------------------------------------------------------------------
+# The index
+# ---------------------------------------------------------------------------
+
+
+class CatalogClimbEntry(ProtocolModel):
+    """One public Climb the package ships."""
+
+    reference: NonEmptyString
+    digest: Digest
+    path: NonEmptyString
+
+    @model_validator(mode="after")
+    def _check_path(self) -> Self:
+        """Reject a path that leaves the catalog root."""
+        _check_relative_catalog_path(self.path)
+        return self
+
+
+class CatalogObjectLocation(ProtocolModel):
+    """Where one content-addressed object lives, and what kind it is."""
+
+    kind: Literal[
+        "campaign",
+        "data_policy",
+        "taskset_validation",
+        "validation_evidence",
+    ]
+    path: NonEmptyString
+    media_type: NonEmptyString
+
+    @model_validator(mode="after")
+    def _check_path(self) -> Self:
+        """Reject a path that leaves the catalog root."""
+        _check_relative_catalog_path(self.path)
+        return self
+
+
+class CatalogIndex(ProtocolModel):
+    """The generated map of everything the package ships.
+
+    Decisions document 0003 A7. Path existence, digest verification, and the
+    kind-matches-the-request check belong to the repository that loads these
+    files; what can be decided from the document alone is decided here.
+    """
+
+    schema_version: Literal["techtree.catalog.v1alpha1"]
+    climbs: list[CatalogClimbEntry]
+    objects: dict[Digest, CatalogObjectLocation]
+
+    @model_validator(mode="after")
+    def _check_index_is_unambiguous(self) -> Self:
+        """Reject repeated references, repeated digests, or shared paths."""
+        references = [entry.reference for entry in self.climbs]
+        if len(set(references)) != len(references):
+            raise ValueError("each Climb reference appears once in the catalog")
+        climb_digests = [entry.digest for entry in self.climbs]
+        if len(set(climb_digests)) != len(climb_digests):
+            raise ValueError("each Climb digest appears once in the catalog")
+
+        paths = [entry.path for entry in self.climbs] + [
+            location.path for location in self.objects.values()
+        ]
+        if len(set(paths)) != len(paths):
+            raise ValueError(
+                "two catalog entries claim the same file; a digest-to-path map "
+                "that is not one-to-one cannot be verified"
+            )
+        return self
+
+
+# ---------------------------------------------------------------------------
+# Compatibility
+# ---------------------------------------------------------------------------
+
+
+class CompatibilityIssue(ProtocolModel):
+    """One reason a Climb might not run here."""
+
+    code: NonEmptyString
+    severity: Literal["warning", "error"]
+    message: NonEmptyString
+    blocking: bool
+
+    @model_validator(mode="after")
+    def _check_blocking_implies_error(self) -> Self:
+        """Reject a warning that also claims to block."""
+        if self.blocking and self.severity != "error":
+            raise ValueError("a blocking issue is an error, not a warning")
+        return self
+
+
+class EngineCompatibilityStatus(StrEnum):
+    """What is known about the required engine on this host."""
+
+    UNKNOWN = "unknown"
+    NOT_INSTALLED = "not_installed"
+    INSTALLED_UNVERIFIED = "installed_unverified"
+    VERIFIED = "verified"
+
+
+class CompatibilityResult(ProtocolModel):
+    """Whether this host can run this Climb, and what stands in the way."""
+
+    compatible: bool
+    host_platform: NonEmptyString
+    host_supported: bool
+    required_engine_digest: Digest
+    engine_status: EngineCompatibilityStatus
+    evaluation_backend_kind: EvaluationBackendKind
+    evaluation_backend_supported: bool
+    issues: list[CompatibilityIssue]
+
+    @model_validator(mode="after")
+    def _check_compatibility_follows_from_the_issues(self) -> Self:
+        """Reject a verdict that disagrees with the issues it lists."""
+        blocking = any(issue.blocking for issue in self.issues)
+        if self.compatible and blocking:
+            raise ValueError("compatible is true only when no listed issue is blocking")
+        if not self.compatible and not blocking:
+            raise ValueError(
+                "an incompatible result must list the blocking issue that made "
+                "it incompatible"
+            )
+        if len({issue.code for issue in self.issues}) != len(self.issues):
+            raise ValueError("each compatibility issue is reported once")
+        return self
+
+
+# ---------------------------------------------------------------------------
+# Summaries
+# ---------------------------------------------------------------------------
+
+
+class DataPolicySummary(ProtocolModel):
+    """The four rights a participant most needs to see before starting."""
+
+    raw_episode_server_upload: Literal["allowed", "prohibited", "consent_required"]
+    raw_episode_training_use: Literal["allowed", "prohibited", "consent_required"]
+    candidate_skill_public_release: Literal[
+        "required_for_climb",
+        "allowed",
+        "prohibited",
+        "consent_required",
+    ]
+    uplift_report_visibility: Literal["public", "private", "prohibited"]
+
+
+class ClimbSummary(ProtocolModel):
+    """Everything ``climb list`` and ``climb show`` display, in one object."""
+
+    reference: NonEmptyString
+    climb_digest: Digest
+    campaign_spec_digest: Digest
+    title: NonEmptyString
+    summary: NonEmptyString
+    status: Literal["open", "closed", "development"]
+    purpose: NonEmptyString
+    taskset_id: NonEmptyString
+    task_count: int = Field(ge=1)
+    subject_harness: NonEmptyString
+    subject_harness_version: NonEmptyString
+    mutation_kind: Literal["skill_insertion"]
+    candidate_skill_visibility: Literal["public", "private"]
+    evaluation_backend: EvaluationBackendKind
+    proof_grade: Literal["development_only", "P1"]
+    data_policy: DataPolicySummary
+    compatibility: CompatibilityResult

techtree/models/cli.py

@@ -0,0 +1,151 @@
+"""The machine-readable CLI surface. Spec section 11.14.
+
+The CLI is the stable boundary a host agent programs against, so its output has
+a shape rather than a format. Every command returns one ``CliEnvelope``:
+succeeded or not, what it produced, what it wants to say, and — at most three —
+what could sensibly be done next.
+
+``NextAction`` is the part that makes the boundary usable by something that is
+not a person. An action carries an argv list, or a named host-agent tool with
+arguments, and says whether a human must confirm it first. That last flag is
+not advisory: it is how an irreversible step stays irreversible-by-a-person
+even when a machine is driving.
+
+Nothing in this module knows about the filesystem, the catalog, or a run. It is
+the vocabulary those layers speak in, which is also why
+:mod:`techtree.errors` can project a typed error into a ``CliError`` without
+either module depending on the other's behavior.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Final, Literal, Self
+
+from pydantic import Field, model_validator
+
+from techtree.models.base import JsonValue, NonEmptyString, ProtocolModel
+
+__all__ = [
+    "MAX_NEXT_ACTIONS",
+    "CheckStatus",
+    "CliEnvelope",
+    "CliError",
+    "CliMessage",
+    "DoctorCheck",
+    "MessageLevel",
+    "NextAction",
+]
+
+#: A host agent that is offered ten choices is being asked to plan, not to act.
+#: Three is the documented ceiling.
+MAX_NEXT_ACTIONS: Final = 3
+
+
+class MessageLevel(StrEnum):
+    """How much attention a message deserves."""
+
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+class CliMessage(ProtocolModel):
+    """One thing the CLI has to say."""
+
+    level: MessageLevel
+    code: NonEmptyString | None
+    text: NonEmptyString
+
+
+class NextAction(ProtocolModel):
+    """A concrete next step, addressed to a person or to a host agent."""
+
+    id: NonEmptyString
+    label: NonEmptyString
+    reason: NonEmptyString | None
+    cli: list[NonEmptyString] | None
+    hermes_tool: NonEmptyString | None
+    hermes_args: dict[str, JsonValue] | None
+    requires_user_confirmation: bool
+
+    @model_validator(mode="after")
+    def _check_action_is_actionable(self) -> Self:
+        """Reject an action nothing could carry out."""
+        if self.cli is None and self.hermes_tool is None:
+            raise ValueError(
+                "a next action must offer a CLI argv list, a host-agent tool, or both"
+            )
+        if self.cli is not None and not self.cli:
+            raise ValueError("a CLI next action needs at least the command name")
+        if self.hermes_args is not None and self.hermes_tool is None:
+            raise ValueError("hermes_args without hermes_tool has nothing to call")
+        return self
+
+
+class CliError(ProtocolModel):
+    """The machine-safe projection of a failure."""
+
+    code: NonEmptyString
+    message: NonEmptyString
+    retryable: bool
+    details: dict[str, JsonValue]
+
+
+class CliEnvelope[T](ProtocolModel):
+    """The single response shape every command returns.
+
+    ``data`` is command-specific, which is why the type is a parameter. The
+    published schema describes the envelope; each command documents its own
+    payload.
+    """
+
+    schema_version: Literal["techtree.cli.v1"]
+    ok: bool
+    command: NonEmptyString
+    data: T | None
+    messages: list[CliMessage]
+    warnings: list[CliMessage]
+    next_actions: list[NextAction] = Field(max_length=MAX_NEXT_ACTIONS)
+    error: CliError | None
+
+    @model_validator(mode="after")
+    def _check_success_and_failure_are_distinguishable(self) -> Self:
+        """Reject an envelope that reports success and failure at once."""
+        if self.ok and self.error is not None:
+            raise ValueError("a successful command reports no error")
+        if not self.ok and self.error is None:
+            raise ValueError("a failed command must say why it failed")
+        if len({action.id for action in self.next_actions}) != len(self.next_actions):
+            raise ValueError("next actions must have distinct identifiers")
+        return self
+
+
+class CheckStatus(StrEnum):
+    """The outcome of one Doctor check."""
+
+    PASS = "pass"
+    WARN = "warn"
+    FAIL = "fail"
+    SKIP = "skip"
+
+
+class DoctorCheck(ProtocolModel):
+    """One environment check and what it found."""
+
+    id: NonEmptyString
+    label: NonEmptyString
+    status: CheckStatus
+    detail: NonEmptyString
+    blocking: bool
+    metadata: dict[str, JsonValue]
+
+    @model_validator(mode="after")
+    def _check_blocking_implies_failure(self) -> Self:
+        """Reject a blocking check that reports nothing wrong."""
+        if self.blocking and self.status in (CheckStatus.PASS, CheckStatus.SKIP):
+            raise ValueError(
+                "a check that passed or was skipped cannot block; blocking is "
+                "what a failure means, not a separate opinion about it"
+            )
+        return self

techtree/models/climb.py

@@ -0,0 +1,254 @@
+"""The public wrapper around a Campaign. Spec section 11.6, decisions 0002.
+
+A Climb is an invitation: a slug, a title, a window, and the rules a
+participant is agreeing to. It holds a digest of the Campaign and nothing of
+the Campaign's contents. No model, harness, runtime, taskset, scoring, or
+mutation setting appears here, and ``extra="forbid"`` keeps it that way.
+
+``ResolvedClimb`` is the assembled graph — Climb, Campaign, DataPolicy, and
+publisher validation receipt, each with the digest it was loaded under. Putting
+the four objects in one validated model is what lets the contradictions be
+caught in one place: a public Climb that promises to publish a report its data
+policy forbids is not a malformed document, it is a document that lies, and it
+raises :class:`~techtree.errors.PolicyError` rather than a validation error so
+the caller can tell those apart.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Self
+
+from pydantic import Field, model_validator
+
+from techtree.errors import PolicyError
+from techtree.models.base import Digest, NonEmptyString, ProtocolModel, UtcDateTime
+from techtree.models.campaign import CampaignSpec
+from techtree.models.data_policy import DataPolicy
+from techtree.models.validation import TasksetValidationReceipt
+
+__all__ = [
+    "CandidateConstraints",
+    "CandidatePolicy",
+    "ClimbManifest",
+    "ClimbMetadata",
+    "LeaderboardPolicy",
+    "PublicationPolicy",
+    "ResolvedClimb",
+    "check_climb_policy_consistency",
+]
+
+
+class CandidateConstraints(ProtocolModel):
+    """How many skills a candidate submits, and in which format."""
+
+    min_skills: int = Field(ge=0)
+    max_skills: int = Field(ge=1)
+    format: Literal["techtree-instruction-skill-v1"]
+
+    @model_validator(mode="after")
+    def _check_bounds(self) -> Self:
+        """Reject bounds no submission could satisfy."""
+        if self.min_skills > self.max_skills:
+            raise ValueError("min_skills cannot exceed max_skills")
+        return self
+
+
+class CandidatePolicy(ProtocolModel):
+    """What participants submit and whether it becomes public."""
+
+    required_mutation: Literal["skill_insertion"]
+    skill_visibility: Literal["public", "private"]
+    constraints: CandidateConstraints
+
+
+class PublicationPolicy(ProtocolModel):
+    """What Techtree publishes about a completed run."""
+
+    report_visibility: Literal["public", "private"]
+    raw_episode_visibility: Literal["private", "prohibited"]
+    public_trace_projection: Literal["redacted", "none"]
+    proof_grade: Literal["development_only", "P1"]
+
+
+class LeaderboardPolicy(ProtocolModel):
+    """Whether results are ranked publicly, and on what evidence."""
+
+    enabled: bool
+    evidence_required: Literal[
+        "not_required",
+        "complete",
+        "complete_or_partial",
+    ]
+
+
+class ClimbMetadata(ProtocolModel):
+    """Public identity and schedule."""
+
+    id: NonEmptyString
+    slug: NonEmptyString
+    version: int = Field(ge=1)
+    title: NonEmptyString
+    summary: NonEmptyString
+    status: Literal["open", "closed", "development"]
+    opens_at: UtcDateTime | None = None
+    closes_at: UtcDateTime | None = None
+
+    @model_validator(mode="after")
+    def _check_window(self) -> Self:
+        """Reject a schedule that closes before it opens."""
+        if (
+            self.opens_at is not None
+            and self.closes_at is not None
+            and self.closes_at <= self.opens_at
+        ):
+            raise ValueError("closes_at must be after opens_at")
+        return self
+
+
+class ClimbManifest(ProtocolModel):
+    """A public invitation to run one Campaign."""
+
+    schema_version: Literal["techtree.climb.v1alpha1"]
+    kind: Literal["Climb"]
+    metadata: ClimbMetadata
+    campaign_spec_digest: Digest
+    candidate_policy: CandidatePolicy
+    publication: PublicationPolicy
+    leaderboard: LeaderboardPolicy
+
+    @model_validator(mode="after")
+    def _check_leaderboard_matches_proof_grade(self) -> Self:
+        """Reject a public ranking built on development-only proofs."""
+        if self.publication.proof_grade == "development_only" and (
+            self.leaderboard.enabled
+        ):
+            raise ValueError(
+                "a development_only Climb cannot enable a leaderboard; its "
+                "results are not evidence of anything comparable"
+            )
+        return self
+
+
+def check_climb_policy_consistency(
+    climb: ClimbManifest,
+    data_policy: DataPolicy,
+) -> None:
+    """Raise :class:`PolicyError` when a Climb promises what its policy forbids.
+
+    Every check compares a public promise against the rights statement the
+    Campaign runs under. A mismatch is a rights problem, not a schema problem,
+    so it is reported as one.
+    """
+    candidate = climb.candidate_policy
+    publication = climb.publication
+    skill_release = data_policy.candidate_skill.public_release
+
+    if candidate.skill_visibility == "public" and skill_release == "prohibited":
+        raise PolicyError(
+            "the Climb publishes candidate skills but the DataPolicy prohibits "
+            "releasing them",
+            details={
+                "skill_visibility": candidate.skill_visibility,
+                "candidate_skill_public_release": skill_release,
+            },
+        )
+    if candidate.skill_visibility == "private" and (
+        skill_release == "required_for_climb"
+    ):
+        raise PolicyError(
+            "the DataPolicy requires candidate skills to be released but the "
+            "Climb keeps them private",
+            details={
+                "skill_visibility": candidate.skill_visibility,
+                "candidate_skill_public_release": skill_release,
+            },
+        )
+
+    if publication.report_visibility == "public" and (
+        data_policy.derived_artifacts.uplift_report != "public"
+    ):
+        raise PolicyError(
+            "the Climb publishes the uplift report but the DataPolicy does not "
+            "make it public",
+            details={
+                "report_visibility": publication.report_visibility,
+                "uplift_report": data_policy.derived_artifacts.uplift_report,
+            },
+        )
+
+    if publication.public_trace_projection == "redacted" and (
+        data_policy.derived_artifacts.redacted_trace_projection != "public"
+    ):
+        raise PolicyError(
+            "the Climb publishes a redacted trace projection but the DataPolicy "
+            "does not make it public",
+            details={
+                "public_trace_projection": publication.public_trace_projection,
+                "redacted_trace_projection": (
+                    data_policy.derived_artifacts.redacted_trace_projection
+                ),
+            },
+        )
+
+    if publication.raw_episode_visibility == "private" and (
+        data_policy.raw_episodes.local_retention == "prohibited"
+    ):
+        raise PolicyError(
+            "the Climb keeps raw episodes privately visible but the DataPolicy "
+            "prohibits retaining them at all",
+            details={
+                "raw_episode_visibility": publication.raw_episode_visibility,
+                "local_retention": data_policy.raw_episodes.local_retention,
+            },
+        )
+
+
+class ResolvedClimb(ProtocolModel):
+    """A Climb with every object it points at, loaded and cross-checked."""
+
+    climb: ClimbManifest
+    climb_digest: Digest
+    campaign: CampaignSpec
+    campaign_digest: Digest
+    data_policy: DataPolicy
+    data_policy_digest: Digest
+    publisher_validation: TasksetValidationReceipt
+    publisher_validation_digest: Digest
+
+    @model_validator(mode="after")
+    def _check_graph(self) -> Self:
+        """Reject a graph whose edges do not point where its objects say."""
+        if self.climb.campaign_spec_digest != self.campaign_digest:
+            raise ValueError(
+                "the Climb references a different Campaign than the one resolved"
+            )
+        if self.campaign.data_policy_digest != self.data_policy_digest:
+            raise ValueError(
+                "the Campaign references a different DataPolicy than the one resolved"
+            )
+        if self.campaign.taskset.validation_receipt_digest != (
+            self.publisher_validation_digest
+        ):
+            raise ValueError(
+                "the Campaign references a different validation receipt than "
+                "the one resolved"
+            )
+
+        mutation = self.campaign.mutation_contract
+        candidate = self.climb.candidate_policy
+        if candidate.required_mutation != mutation.kind:
+            raise ValueError(
+                "the Climb requires a different mutation than the Campaign "
+                "contract defines"
+            )
+        if (
+            candidate.constraints.min_skills != mutation.minimum_skills
+            or candidate.constraints.max_skills != mutation.maximum_skills
+        ):
+            raise ValueError(
+                "the Climb candidate constraints do not match the Campaign "
+                "mutation bounds"
+            )
+
+        check_climb_policy_consistency(self.climb, self.data_policy)
+        return self