manifold-cli 0.0.39__py3-none-any.whl

manifold_cli/models/credentials.py

@@ -0,0 +1,19 @@
+from pydantic import BaseModel
+
+
+class Credentials(BaseModel):
+    api_url: str
+    workos_client_id: str
+    access_token: str
+    refresh_token: str
+
+
+class RunnerCredential(BaseModel):
+    """A minted runner token, as the runner box stores it.
+
+    `api_url` is recorded with it so a token pasted against the wrong
+    deployment fails on the mismatch rather than as an opaque 401.
+    """
+
+    api_url: str
+    token: str

manifold_cli/models/errors.py

@@ -0,0 +1,121 @@
+import json
+
+
+class ManifoldApiError(Exception):
+    def __init__(self, status_code: int, body: str):
+        self.status_code = status_code
+        self.body = body
+        super().__init__(f"manifold API error {status_code}: {body[:200]}")
+
+    @property
+    def detail(self) -> str | None:
+        """The human-readable ``detail`` from the error body."""
+        return error_detail(self.body)
+
+
+class WorkOSAuthError(Exception):
+    """Terminal device-flow or refresh failure."""
+
+    def __init__(self, error: str, description: str | None = None):
+        self.error = error
+        self.description = description
+        super().__init__(description or error)
+
+
+class NotLoggedInError(Exception):
+    """No stored credentials."""
+
+    def __init__(self, message: str = "Not logged in."):
+        super().__init__(message)
+
+
+class SessionExpiredError(Exception):
+    """Stored credentials are invalid and could not be refreshed."""
+
+    def __init__(self, message: str = "Session expired."):
+        super().__init__(message)
+
+
+class NoRunnerCredentialError(Exception):
+    """No stored runner credential."""
+
+    def __init__(self, message: str = "No runner credential stored."):
+        super().__init__(message)
+
+
+class AccessTokenRejectedError(Exception):
+    """The access token exported for registration was refused."""
+
+    def __init__(self, message: str = "Access token rejected."):
+        super().__init__(message)
+
+
+class InvalidAccessTokenError(Exception):
+    """The exported access token cannot be placed in an HTTP header."""
+
+    def __init__(self):
+        super().__init__("MANIFOLD_TOKEN is not a valid credential.")
+
+
+class NoRunnerHomeError(Exception):
+    """No runner home to act on, either named or on the box at all."""
+
+    def __init__(self, message: str = "This box has no runner home."):
+        super().__init__(message)
+
+
+class AmbiguousRunnerHomeError(Exception):
+    """More than one runner home on the box, and the caller named none."""
+
+    def __init__(self, handles: list[str]):
+        self.handles = handles
+        super().__init__(
+            f"This box has {len(handles)} runner homes ({', '.join(handles)}). "
+            f"Name one with --runner."
+        )
+
+
+class RunnerCredentialRejectedError(Exception):
+    """The stored runner credential was refused.
+
+    A runner token is revoked rather than rotated, so a 401 is terminal: it was
+    revoked, or it belongs to another deployment.
+    """
+
+    def __init__(self, message: str = "Runner credential rejected."):
+        super().__init__(message)
+
+
+class RunnerDeploymentMismatchError(Exception):
+    """The stored runner credential was minted against another deployment."""
+
+    def __init__(self, stored: str, configured: str):
+        self.stored = stored
+        self.configured = configured
+        super().__init__(
+            f"Runner credential is for {stored}, "
+            f"but this box is configured for {configured}."
+        )
+
+
+def error_detail(body: str) -> str | None:
+    """The human-readable ``detail`` from a JSON error body.
+
+    Returns None when the body is not JSON or ``detail`` is not a string
+    (e.g. FastAPI's request-validation errors, whose detail is a list), so
+    callers can fall back to their own message.
+    """
+    detail = raw_error_detail(body)
+    return detail if isinstance(detail, str) else None
+
+
+def raw_error_detail(body: str) -> object:
+    """The ``detail`` of a JSON error body as sent.
+
+    None where the body is not a JSON object with ``detail``.
+    """
+    try:
+        payload = json.loads(body)
+    except ValueError:
+        return None
+    return payload.get("detail") if isinstance(payload, dict) else None

manifold_cli/models/log.py

@@ -0,0 +1,114 @@
+"""A run's captured output: what a runner reports, and what a reader reads back."""
+
+from datetime import datetime
+from enum import StrEnum
+from uuid import UUID
+
+from pydantic import BaseModel, Field, field_validator
+
+from manifold_cli.models.run import AssignmentReason, AssignmentStatus, RunSide
+
+
+class LogSource(StrEnum):
+    """Which channel of a process's output a line came from."""
+
+    STDOUT = "stdout"
+    STDERR = "stderr"
+
+
+class LogProducer(StrEnum):
+    """Which process produced a captured stream."""
+
+    RUNNER = "runner"
+    WORKER = "worker"
+
+
+class ReportedStream(BaseModel):
+    """One worker's output on one source, as a batch declares it.
+
+    Declared on every batch rather than once, so a post lost in transit leaves a
+    reader's stream list short only until the next one repairs it. `ended_at` and
+    `exit_code` are what a close reports, and stay None while the worker runs.
+    """
+
+    producer: LogProducer
+    worker_index: int = Field(ge=0)
+    source: LogSource
+    ended_at: datetime | None = None
+    exit_code: int | None = None
+
+
+class ReportedLine(BaseModel):
+    """One captured line, at its position in the stream.
+
+    `ts` is when the runner read the line rather than when the batch carrying it
+    was sent, so the interval a batch is held for does not collapse a worker's
+    lines onto one instant.
+    """
+
+    producer: LogProducer
+    worker_index: int = Field(ge=0)
+    source: LogSource
+    seq: int = Field(ge=0)
+    ts: datetime
+    text: str
+
+    @field_validator("text")
+    @classmethod
+    def _without_nul(cls, text: str) -> str:
+        """Drop the one character the store behind this cannot hold.
+
+        A worker writing bytes to a pipe produces a NUL, which is valid UTF-8 and
+        so survives the decode intact. The column it lands in refuses one, and
+        the refusal costs the whole batch the line rode in rather than the line.
+        """
+        return text.replace("\x00", "")
+
+
+class LogBatch(BaseModel):
+    """One post: every stream the side has, and the lines since the last one.
+
+    A batch carrying no lines is not a no-op. It is what puts a worker in a
+    reader's list while its container is still pulling an image, and what reports
+    a worker gone once it has exited.
+    """
+
+    streams: list[ReportedStream]
+    lines: list[ReportedLine] = []
+
+
+class RunLogStream(BaseModel):
+    """One stream of one assignment of a run, with its size and its process's exit.
+
+    `assignment_id`, `producer`, `worker_index` and `source` identify the
+    stream to read.
+    """
+
+    assignment_id: UUID
+    side: RunSide
+    status: AssignmentStatus
+    reason: AssignmentReason | None
+    producer: LogProducer
+    worker_index: int
+    source: LogSource
+    line_count: int
+    exit_code: int | None
+
+
+class LogLine(BaseModel):
+    """One stored line of a stream, at its `seq`."""
+
+    seq: int
+    ts: datetime
+    text: str
+
+
+class LogMatch(BaseModel):
+    """One line that matched a search, with the lines around it in its stream."""
+
+    assignment_id: UUID
+    producer: LogProducer
+    worker_index: int
+    source: LogSource
+    seq: int
+    lines: list[LogLine]

manifold_cli/models/observability.py

@@ -0,0 +1,121 @@
+"""What a runner reports about its box's resource usage and the policy's steps.
+
+The server exports each report to Honeycomb, and stores only the resource usage
+samples.
+"""
+
+from uuid import UUID
+
+from pydantic import AwareDatetime, BaseModel
+
+from manifold_cli.models.run import AssignmentDispatch, RunSide
+
+
+class GpuUsage(BaseModel):
+    index: int
+    name: str
+    utilization_percent: float
+    memory_used_bytes: int
+    memory_total_bytes: int
+
+
+class AssignmentAttributes(BaseModel):
+    """The run side assigned to the runner at a sample's `sampled_at` or a policy
+    step's `ended_at`."""
+
+    assignment_id: UUID
+    run_id: UUID
+    side: RunSide
+    policy_slug: str
+    policy_version: str
+    benchmark_slug: str
+    benchmark_version: str
+    shards: int
+
+
+class ResourceUsageSample(BaseModel):
+    """The box's resource usage over the interval between two host readings.
+
+    The disk and network byte counts cover the interval since the previous
+    reading. `assignment` is None while the runner does not have an assignment.
+    The Docker fields are None when the runner could not read the Docker daemon.
+    """
+
+    gpus: list[GpuUsage]
+    assignment: AssignmentAttributes | None
+    sampled_at: AwareDatetime
+    # cpu
+    cpu_utilization_percent: float
+    load_average_1m: float
+    # memory
+    memory_used_bytes: int
+    # disk
+    io_wait_percent: float
+    disk_read_bytes: int
+    disk_write_bytes: int
+    docker_root_free_bytes: int | None
+    tmp_free_bytes: int
+    # network
+    network_received_bytes: int
+    network_sent_bytes: int
+    # docker
+    docker_image_count: int | None
+    docker_image_bytes: int | None
+
+
+class ReportResourceUsageRequest(BaseModel):
+    samples: list[ResourceUsageSample]
+    # Sent once per request instead of per sample because they do not change
+    # between samples.
+    cpu_count: int
+    memory_total_bytes: int
+
+
+class PolicyStep(BaseModel):
+    """One policy step that the policy side's bridge timed.
+
+    A step runs from the runner writing the last byte of an OBSERVATION frame to
+    the policy until the runner reads the start of the ACTION frame that answers
+    it. The runner times each connection's steps separately, so a step includes
+    the time the policy spends serving other connections.
+    """
+
+    ended_at: AwareDatetime
+    duration_sec: float
+
+
+class ReportPolicyMetricsRequest(BaseModel):
+    assignment: AssignmentAttributes
+    steps: list[PolicyStep]
+
+
+class BenchmarkStep(BaseModel):
+    """One step that the benchmark side's bridge timed.
+
+    The round trip runs from the runner writing the last byte of an OBSERVATION
+    frame to the policy side until the runner reads the start of the ACTION
+    frame that answers it. `policy_step_sec` is the duration of the same step
+    that the policy side's bridge timed and sent after the ACTION frame.
+    """
+
+    ended_at: AwareDatetime
+    round_trip_sec: float
+    policy_step_sec: float
+
+
+class ReportBenchmarkMetricsRequest(BaseModel):
+    assignment: AssignmentAttributes
+    steps: list[BenchmarkStep]
+
+
+def create_assignment_attributes(dispatch: AssignmentDispatch) -> AssignmentAttributes:
+    return AssignmentAttributes(
+        assignment_id=dispatch.assignment.id,
+        run_id=dispatch.run.id,
+        side=dispatch.assignment.side,
+        policy_slug=dispatch.run.policy_slug,
+        policy_version=dispatch.run.policy_version,
+        benchmark_slug=dispatch.run.benchmark_slug,
+        benchmark_version=dispatch.run.benchmark_version,
+        shards=dispatch.shards,
+    )

manifold_cli/models/organization.py

@@ -0,0 +1,19 @@
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel
+
+
+class Organization(BaseModel):
+    id: UUID
+    slug: str
+    display_name: str
+    created_at: datetime
+
+
+class OrganizationNotFoundError(Exception):
+    """The caller named an organization the server will not show them.
+
+    The server answers alike for one that does not exist and one the caller is
+    not a member of, so this covers both. Carries the server's message.
+    """

manifold_cli/models/pagination.py

@@ -0,0 +1,59 @@
+from collections.abc import Callable
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+# The largest page the API will serve; it rejects a request for more. However
+# many rows a caller asks for in total, the collector requests at most this many
+# per request.
+MAX_PAGE_LIMIT = 200
+
+# Guards against a server that keeps handing back a cursor: the collector stops
+# after this many pages. At the maximum page size that is still far more rows
+# than any command means to print.
+MAX_PAGES = 100
+
+
+class SortOrder(StrEnum):
+    """The end of a time-ordered list where the first page starts."""
+
+    ASC = "asc"
+    DESC = "desc"
+
+
+class Page[T](BaseModel):
+    """One page of a keyset-paginated list endpoint.
+
+    `total` counts every row matching the query, ignoring the page limit, so a
+    command can report how much it is showing. `next_cursor` is opaque: it is
+    echoed back to fetch the following page and never parsed here.
+    """
+
+    items: list[T]
+    total: int
+    next_cursor: str | None = None
+
+
+def collect[T](
+    fetch: Callable[[int, str | None], Page[T]], *, limit: int | None = None
+) -> tuple[list[T], int]:
+    """Read a paginated list by following its cursor, and report the total.
+
+    Stops once `limit` rows are in hand, or at the end of the list when no
+    limit is given. The total comes back alongside the rows because it counts
+    every match, so a truncated read can say what it left out.
+    """
+    items: list[T] = []
+    total = 0
+    cursor: str | None = None
+    for _ in range(MAX_PAGES):
+        remaining = MAX_PAGE_LIMIT if limit is None else limit - len(items)
+        page = fetch(min(remaining, MAX_PAGE_LIMIT), cursor)
+        items.extend(page.items)
+        total = page.total
+        if page.next_cursor is None or len(page.items) == 0:
+            break
+        if limit is not None and len(items) >= limit:
+            break
+        cursor = page.next_cursor
+    return (items if limit is None else items[:limit]), total

manifold_cli/models/policy.py

@@ -0,0 +1,49 @@
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from manifold_cli.models.catalog import Adapter, Visibility
+
+
+class Policy(BaseModel):
+    """A policy, owned by one organization.
+
+    `slug` is unique only within `owner_org_slug`, so the two together are what
+    names a policy, written `<org>/<slug>` where a command takes one.
+    """
+
+    id: UUID
+    owner_user_id: UUID
+    owner_org_id: UUID
+    owner_org_slug: str
+    slug: str
+    display_name: str
+    visibility: Visibility
+    created_at: datetime
+    updated_at: datetime
+
+
+class PolicyVersion(BaseModel):
+    """A runnable artifact under a policy — what a run actually executes."""
+
+    id: UUID
+    policy_id: UUID
+    version: str
+    adapter: Adapter
+    config: dict[str, Any]
+    minimum_gpu_memory_gb: int
+    minimum_driver_major: int | None
+    maximum_driver_major: int | None
+    minimum_gpu_count: int | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class PolicyNotFoundError(Exception):
+    """No policy visible to the caller matches this reference.
+
+    Carries the server's message, which contains the reference that failed to
+    resolve.
+    """