lucen-cli 0.1.0__py3-none-any.whl

lucen/__init__.py

@@ -0,0 +1,72 @@
+"""`from lucen import Hub` — MouseMouse from a Python script.
+
+    from lucen import Hub
+
+    hub = Hub()                  # LUCEN_API_URL / LUCEN_API_KEY, else ~/.config/lucen/credentials
+    hub.pull("lucen/laika", "./laika")               # every sha256 verified
+    hub.push("./my-dataset", "you/my-dataset", kind="dataset", public=True)
+    run = hub.runs.create({"template": "ppo_mujoco", "robot": "lucen/laika"}, follow=True)
+    gate = hub.rollouts.create(run.output_model_repo, "lucen/laika", battery="smoke", local=True)
+    print(gate.scorecard)
+
+A thin, typed surface over the `lucen` CLI's own engine (P5): the same
+credentials rules, the same push/pull/follow code, the same sentence for
+every refusal — as records and exceptions instead of lines and exit codes.
+It ships inside the `lucen-cli` distribution: installing `lucen-cli` (from
+the hub's own index or a checkout) is all it takes.
+"""
+
+from __future__ import annotations
+
+from lucen.errors import Conflict, Forbidden, HubError, HubUnreachable, NotFound, NotSignedIn
+from lucen.hub import Hub
+from lucen.progress import ProgressEvent
+from lucen.results import (
+    Cell,
+    Episode,
+    Gate,
+    LogEvent,
+    Me,
+    Member,
+    Org,
+    PullResult,
+    PushResult,
+    Repo,
+    RobotDraft,
+    RobotPublishResult,
+    RobotReport,
+    Rollout,
+    Run,
+    RunEstimate,
+    RunRecommendation,
+)
+from lucen_cli import __version__ as __version__
+
+__all__ = [
+    "Cell",
+    "Conflict",
+    "Episode",
+    "Forbidden",
+    "Gate",
+    "Hub",
+    "HubError",
+    "HubUnreachable",
+    "LogEvent",
+    "Me",
+    "Member",
+    "NotFound",
+    "NotSignedIn",
+    "Org",
+    "ProgressEvent",
+    "PullResult",
+    "PushResult",
+    "Repo",
+    "RobotDraft",
+    "RobotPublishResult",
+    "RobotReport",
+    "Rollout",
+    "Run",
+    "RunEstimate",
+    "RunRecommendation",
+    "__version__",
+]

lucen/errors.py

@@ -0,0 +1,141 @@
+"""One exception family, carrying the three lines a terminal user reads (C7).
+
+Every refusal the CLI prints is `Error: <what happened>` / `The hub said:
+<its sentence>` / `Fix: <one line>`. A script gets the same three things as
+attributes — :attr:`HubError.message`, :attr:`HubError.detail`,
+:attr:`HubError.fix` — and ``str(error)`` renders them the same way, so a
+traceback and a terminal say the same sentence about the same refusal.
+
+The subclasses follow the status the hub answered, which is also how the
+CLI picks its exit code:
+
+- :class:`NotSignedIn` — 401, or no key was configured at all,
+- :class:`Forbidden` — 403: the key lacks the scope, or the resource is not
+  yours to write,
+- :class:`NotFound` — 404: it does not exist, or it is private and you are not
+  a member (the hub never tells those two apart),
+- :class:`Conflict` — 409: already exists, blocked by history, already ended,
+- :class:`HubUnreachable` — the hub did not answer (a refused connection, a
+  timeout, or a 502/504/52x from the network in front of it).
+
+Everything else — a 422, a 5xx, a local refusal such as a directory with no
+files — is a plain :class:`HubError`. The translation from the CLI's own
+exceptions is :func:`from_cli_error`; nothing here imports typer.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from lucen_cli.errors import UNREACHABLE_STATUSES, ApiError, CLIError
+from lucen_cli.errors import HubUnreachable as _CLIHubUnreachable
+
+#: The one line every "not signed in" refusal ends with, phrased for a script.
+LOGIN_FIX_PYTHON = (
+    "Pass Hub(key='lucen_sk_…') with a key from the API keys page of the hub, "
+    "set LUCEN_API_KEY, or run `lucen auth login` once on this machine."
+)
+
+
+class HubError(Exception):
+    """What happened, what the hub said (if anything), and the fix."""
+
+    #: The HTTP status the hub answered, or None for a refusal made locally.
+    status: int | None
+    #: The hub's own sentence (an RFC 9457 `detail`), when it gave one.
+    detail: str | None
+    #: One line that makes the next attempt succeed, when there is one.
+    fix: str | None
+    #: A machine-readable code (`lucen robot` refusals: `interface.base`, …).
+    code: str | None
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        detail: str | None = None,
+        fix: str | None = None,
+        code: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.detail = detail
+        self.fix = fix
+        self.code = code
+
+    def __str__(self) -> str:
+        lines = [self.message]
+        if self.detail:
+            lines.append(f"  The hub said: {self.detail}")
+        if self.fix:
+            lines.append(f"Fix: {self.fix}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        """The same shape as `lucen --json` prints for an error."""
+        return {
+            "error": self.message,
+            "detail": self.detail,
+            "fix": self.fix,
+            "status": self.status,
+            "code": self.code,
+        }
+
+
+class NotSignedIn(HubError):
+    """401 — the hub rejected the credential — or no key is configured at all."""
+
+
+class Forbidden(HubError):
+    """403 — the key lacks the scope this call needs, or the resource is not yours."""
+
+
+class NotFound(HubError):
+    """404 — no such thing, or a private one you are not a member of (indistinguishable)."""
+
+
+class Conflict(HubError):
+    """409 — already exists, already ended, or blocked by history the hub keeps."""
+
+
+class HubUnreachable(HubError):
+    """The hub did not answer: no connection, a timeout, or a 502/504/52x in front of it."""
+
+
+def from_cli_error(exc: CLIError) -> HubError:
+    """The CLI's exception as this module's: same three lines, the subclass by status."""
+    status = exc.status if isinstance(exc, ApiError) else None
+    code = getattr(exc, "code", None)
+    kwargs: dict[str, Any] = {
+        "status": status,
+        "detail": exc.detail,
+        "fix": exc.hint,
+        "code": code if isinstance(code, str) else None,
+    }
+    if isinstance(exc, _CLIHubUnreachable):
+        return HubUnreachable(exc.message, **kwargs)
+    if status == 401:
+        return NotSignedIn(exc.message, **kwargs)
+    if status == 403:
+        return Forbidden(exc.message, **kwargs)
+    if status == 404:
+        return NotFound(exc.message, **kwargs)
+    if status == 409:
+        return Conflict(exc.message, **kwargs)
+    if status is not None and status in UNREACHABLE_STATUSES:
+        return HubUnreachable(exc.message, **kwargs)
+    return HubError(exc.message, **kwargs)
+
+
+__all__ = [
+    "LOGIN_FIX_PYTHON",
+    "Conflict",
+    "Forbidden",
+    "HubError",
+    "HubUnreachable",
+    "NotFound",
+    "NotSignedIn",
+    "from_cli_error",
+]