ushabti 0.1.0.dev0__py3-none-any.whl

ushabti/__init__.py

@@ -0,0 +1,135 @@
+"""Ushabti SDK: the shared vocabulary and building blocks of the workforce."""
+
+from importlib.metadata import version
+
+from ushabti.config import LogFormat, Mode, Settings, configure_logging
+from ushabti.errors import (
+    MissingExtraError,
+    ModelError,
+    SpellError,
+    UnknownImplementError,
+    UnresolvedEnvError,
+    UnweighedWriteError,
+    UshabtiError,
+)
+from ushabti.field import Field, FieldKind
+from ushabti.here_am_i import HereAmI
+from ushabti.implements import (
+    Implement,
+    ImplementKind,
+    ImplementRegistry,
+    ImplementSpec,
+    default_registry,
+)
+from ushabti.maat import (
+    Comparison,
+    Condition,
+    Isfet,
+    Maat,
+    MaatAssertion,
+    MaatOutcome,
+    MaatStatus,
+    Observe,
+)
+from ushabti.models import (
+    Completion,
+    Message,
+    ModelProvider,
+    Role,
+    StopReason,
+    ToolCall,
+    Usage,
+    build_provider,
+)
+from ushabti.omen import Omen
+from ushabti.papyrus import JsonlPapyrus, Papyrus, PapyrusEntry, PapyrusEvent
+from ushabti.spell import (
+    ModelProviderName,
+    ModelSpec,
+    PapyrusSpec,
+    ResolvedSpell,
+    Spell,
+    SpellMetadata,
+    SpellSpec,
+    VigilSpec,
+    load_spell,
+    parse_spell,
+    resolve_spell,
+)
+from ushabti.summons import Summons, SummonsSource, SummonsState
+from ushabti.weighing import (
+    DefaultWeighing,
+    Verdict,
+    Weighing,
+    WeighingPolicy,
+    WeighingRequest,
+    WeighingResult,
+    WeighingRule,
+)
+
+__version__ = version("ushabti")
+
+__all__ = [
+    "Comparison",
+    "Completion",
+    "Condition",
+    "DefaultWeighing",
+    "Field",
+    "FieldKind",
+    "HereAmI",
+    "Implement",
+    "ImplementKind",
+    "ImplementRegistry",
+    "ImplementSpec",
+    "Isfet",
+    "JsonlPapyrus",
+    "LogFormat",
+    "Maat",
+    "MaatAssertion",
+    "MaatOutcome",
+    "MaatStatus",
+    "Message",
+    "MissingExtraError",
+    "Mode",
+    "ModelError",
+    "ModelProvider",
+    "ModelProviderName",
+    "ModelSpec",
+    "Observe",
+    "Omen",
+    "Papyrus",
+    "PapyrusEntry",
+    "PapyrusEvent",
+    "PapyrusSpec",
+    "ResolvedSpell",
+    "Role",
+    "Settings",
+    "Spell",
+    "SpellError",
+    "SpellMetadata",
+    "SpellSpec",
+    "StopReason",
+    "Summons",
+    "SummonsSource",
+    "SummonsState",
+    "ToolCall",
+    "UnknownImplementError",
+    "UnresolvedEnvError",
+    "UnweighedWriteError",
+    "Usage",
+    "UshabtiError",
+    "Verdict",
+    "VigilSpec",
+    "Weighing",
+    "WeighingPolicy",
+    "WeighingRequest",
+    "WeighingResult",
+    "WeighingRule",
+    "__version__",
+    "build_provider",
+    "configure_logging",
+    "default_registry",
+    "load_spell",
+    "parse_spell",
+    "resolve_spell",
+]

ushabti/_base.py

@@ -0,0 +1,80 @@
+"""Shared building blocks for the SDK's data models.
+
+This module is private. Import the public models from ``ushabti`` instead.
+"""
+
+import re
+import uuid
+from datetime import UTC, datetime, timedelta
+from typing import Annotated
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, PlainSerializer, StringConstraints
+
+
+class StrictModel(BaseModel):
+    """Base for models a person writes by hand, such as a spell.
+
+    Unknown keys are an error, so a typo never passes silently.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True, use_attribute_docstrings=True)
+
+
+class WireModel(BaseModel):
+    """Base for models sent between processes or written to Papyrus.
+
+    Unknown keys are ignored, so an older reader can accept a newer writer.
+    """
+
+    model_config = ConfigDict(extra="ignore", frozen=True, use_attribute_docstrings=True)
+
+
+Name = Annotated[str, StringConstraints(pattern=r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$", max_length=63)]
+"""A lowercase name in DNS label style: letters, digits, and inner hyphens."""
+
+
+def utc_now() -> datetime:
+    """The current time, always timezone-aware and in UTC."""
+    return datetime.now(UTC)
+
+
+def new_id() -> str:
+    """A fresh random identifier."""
+    return uuid.uuid4().hex
+
+
+_DURATION = re.compile(r"^(\d+(?:\.\d+)?)(ms|s|m|h|d)$")
+_UNIT_SECONDS = {"ms": 0.001, "s": 1.0, "m": 60.0, "h": 3600.0, "d": 86400.0}
+
+
+def parse_duration(value: object) -> object:
+    """Turn ``"60s"``, ``"5m"``, or a number of seconds into a timedelta."""
+    if isinstance(value, bool):
+        raise ValueError("expected a duration such as 60s, not a boolean")
+    if isinstance(value, int | float):
+        return timedelta(seconds=value)
+    if isinstance(value, str):
+        match = _DURATION.match(value.strip())
+        if match is None:
+            raise ValueError("expected a duration such as 500ms, 60s, 5m, 1h, or 1d")
+        return timedelta(seconds=float(match.group(1)) * _UNIT_SECONDS[match.group(2)])
+    return value
+
+
+def format_duration(value: timedelta) -> str:
+    """Render a timedelta in the same compact form ``parse_duration`` reads."""
+    seconds = value.total_seconds()
+    for unit, size in (("d", 86400), ("h", 3600), ("m", 60)):
+        if seconds >= size and seconds % size == 0:
+            return f"{int(seconds // size)}{unit}"
+    if seconds == int(seconds):
+        return f"{int(seconds)}s"
+    return f"{round(seconds * 1000)}ms"
+
+
+Duration = Annotated[
+    timedelta,
+    BeforeValidator(parse_duration),
+    PlainSerializer(format_duration, return_type=str),
+]
+"""A timedelta written as a short string such as ``60s`` or ``5m``."""

ushabti/config.py

@@ -0,0 +1,129 @@
+"""Process settings, read from environment variables with the USHABTI_ prefix."""
+
+import logging
+import sys
+from enum import StrEnum
+from pathlib import Path
+from typing import Self
+
+import structlog
+from pydantic import PositiveFloat, SecretStr, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Mode(StrEnum):
+    """The topology an ushabti runs in."""
+
+    SOLO = "solo"
+    INDEPENDENT = "independent"
+    OVERSEEN = "overseen"
+
+
+class LogFormat(StrEnum):
+    CONSOLE = "console"
+    JSON = "json"
+
+
+class Settings(BaseSettings):
+    """Settings for one process. Every key maps to ``USHABTI_<KEY>``.
+
+    Secrets live here and nowhere else: they come from the environment, never
+    from a spell or any other file.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="USHABTI_",
+        env_ignore_empty=True,
+        extra="ignore",
+        use_attribute_docstrings=True,
+    )
+
+    mode: Mode = Mode.SOLO
+    """Topology: `solo`, `independent`, or `overseen`."""
+
+    name: str | None = None
+    """Name of this ushabti. Defaults to the name of its spell."""
+
+    admin_token: SecretStr | None = None
+    """Bearer token for every endpoint that makes an ushabti or overseer do
+    something: summons, halt, resume, and registration. Unset disables them."""
+
+    overseer_url: str | None = None
+    """Base URL of the overseer. Required in `overseen` mode."""
+
+    advertise_url: str | None = None
+    """URL where the overseer can reach this ushabti."""
+
+    here_am_i_interval: PositiveFloat = 30.0
+    """Seconds between "Here am I" messages to the overseer."""
+
+    papyrus_path: Path | None = None
+    """Overrides the Papyrus path the spell declares."""
+
+    fake_script: Path | None = None
+    """YAML file of scripted completions for the `fake` model provider."""
+
+    host: str = "127.0.0.1"
+    """Address the HTTP server binds to."""
+
+    port: int = 8080
+    """Port the HTTP server listens on."""
+
+    log_level: str = "INFO"
+    """Log level name, such as `INFO` or `DEBUG`."""
+
+    log_format: LogFormat = LogFormat.CONSOLE
+    """Log output: `console` for people, `json` for log shippers."""
+
+    @model_validator(mode="after")
+    def _mode_matches_overseer(self) -> Self:
+        if self.mode is Mode.OVERSEEN and self.overseer_url is None:
+            raise ValueError("USHABTI_MODE=overseen requires USHABTI_OVERSEER_URL")
+        if self.overseer_url is not None and self.mode is not Mode.OVERSEEN:
+            raise ValueError("USHABTI_OVERSEER_URL is set, so USHABTI_MODE must be overseen")
+        if self.mode is Mode.OVERSEEN and self.admin_token is None:
+            raise ValueError(
+                "USHABTI_MODE=overseen requires USHABTI_ADMIN_TOKEN: "
+                "an overseer only accepts an ushabti that presents it"
+            )
+        return self
+
+    def admin_token_value(self) -> str | None:
+        """The admin token in the clear, or None when the endpoints are disabled."""
+        return None if self.admin_token is None else self.admin_token.get_secret_value()
+
+
+class _StderrLogger:
+    """Writes each log line to whatever ``sys.stderr`` is at that moment.
+
+    Looking the stream up on every call, and not once at setup, keeps logging
+    working after stderr is redirected or replaced.
+    """
+
+    def msg(self, message: str) -> None:
+        sys.stderr.write(message + "\n")
+        sys.stderr.flush()
+
+    log = debug = info = warn = warning = msg
+    fatal = failure = err = error = critical = exception = msg
+
+
+def configure_logging(level: str = "INFO", log_format: LogFormat = LogFormat.CONSOLE) -> None:
+    """Send structured logs to stderr, leaving stdout for command output."""
+    renderer: structlog.typing.Processor = (
+        structlog.processors.JSONRenderer()
+        if log_format is LogFormat.JSON
+        else structlog.dev.ConsoleRenderer()
+    )
+    threshold = logging.getLevelNamesMapping().get(level.upper(), logging.INFO)
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso", utc=True),
+            renderer,
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(threshold),
+        logger_factory=lambda *args: _StderrLogger(),
+        cache_logger_on_first_use=False,
+    )

ushabti/errors.py

@@ -0,0 +1,58 @@
+"""Errors the SDK raises on purpose."""
+
+from collections.abc import Iterable
+
+
+class UshabtiError(Exception):
+    """Base class for every error the SDK raises on purpose."""
+
+
+class SpellError(UshabtiError, ValueError):
+    """A spell failed validation. ``problems`` lists every reason found."""
+
+    def __init__(self, problems: Iterable[str], *, source: str = "spell") -> None:
+        self.problems = tuple(problems)
+        self.source = source
+        lines = "\n".join(f"  - {problem}" for problem in self.problems)
+        super().__init__(f"{source} is not a valid spell:\n{lines}")
+
+
+class UnresolvedEnvError(UshabtiError):
+    """A value references environment variables that are not set."""
+
+    def __init__(self, variables: Iterable[str]) -> None:
+        self.variables = tuple(variables)
+        names = ", ".join(f"${{{name}}}" for name in self.variables)
+        super().__init__(f"environment variable not set: {names}")
+
+
+class MissingExtraError(UshabtiError, ImportError):
+    """An optional dependency is needed but its extra is not installed."""
+
+    def __init__(self, extra: str, package: str) -> None:
+        self.extra = extra
+        self.package = package
+        super().__init__(
+            f'the "{package}" package is not installed; '
+            f'install it with: pip install "ushabti[{extra}]"'
+        )
+
+
+class ModelError(UshabtiError):
+    """A model provider is misconfigured or its request failed."""
+
+
+class UnknownImplementError(UshabtiError, LookupError):
+    """An implement name is not in the registry."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        super().__init__(f"{name} is not a registered implement")
+
+
+class UnweighedWriteError(UshabtiError):
+    """An implement was asked to run without a PASS verdict from the weighing.
+
+    This is the guard behind the rule that no write implement runs without a
+    verdict. Reaching it means a caller skipped the weighing.
+    """

ushabti/field.py

@@ -0,0 +1,42 @@
+"""A field: a target an ushabti tends."""
+
+from enum import StrEnum
+from typing import Self
+
+from pydantic import model_validator
+
+from ushabti._base import Name, StrictModel
+
+
+class FieldKind(StrEnum):
+    KUBERNETES = "kubernetes"
+    PROXMOX = "proxmox"
+    PROMETHEUS = "prometheus"
+    SERVICE = "service"
+
+
+class Field(StrictModel):
+    """A target an ushabti tends: a K3s cluster, a namespace, a Proxmox node, a service."""
+
+    name: Name
+    """Name of the field. A summons (a unit of work) refers to a field by this name."""
+
+    kind: FieldKind
+    """What the field is: `kubernetes`, `proxmox`, `prometheus`, or `service`."""
+
+    namespaces: tuple[str, ...] = ()
+    """Kubernetes namespaces to tend. Only valid when `kind` is `kubernetes`."""
+
+    nodes: tuple[str, ...] = ()
+    """Proxmox node names to tend. Only valid when `kind` is `proxmox`."""
+
+    endpoint: str | None = None
+    """Base URL of the field, usually an environment reference such as `${PROMETHEUS_URL}`."""
+
+    @model_validator(mode="after")
+    def _keys_match_kind(self) -> Self:
+        if self.namespaces and self.kind is not FieldKind.KUBERNETES:
+            raise ValueError("namespaces is only valid when kind is kubernetes")
+        if self.nodes and self.kind is not FieldKind.PROXMOX:
+            raise ValueError("nodes is only valid when kind is proxmox")
+        return self

ushabti/here_am_i.py

@@ -0,0 +1,48 @@
+"""Here am I: the message an ushabti answers with."""
+
+from datetime import datetime
+
+import pydantic
+
+from ushabti._base import WireModel, utc_now
+from ushabti.config import Mode
+
+
+class HereAmI(WireModel):
+    """The health signal and acknowledgement of one ushabti.
+
+    It is the body of the health endpoint, and it is what an ushabti sends to
+    its overseer to register and to stay registered. It carries the fields and
+    implements of the spell so the overseer can route a summons (a unit of
+    work) without holding the spell itself.
+    """
+
+    name: str
+    """Name of the ushabti."""
+
+    spell: str
+    """Name of the spell it runs."""
+
+    mode: Mode
+    """Topology it runs in: `solo`, `independent`, or `overseen`."""
+
+    halted: bool
+    """True when the ushabti is halted: it observes but does not act."""
+
+    last_vigil: datetime | None = None
+    """When the last vigil tick finished, or None before the first one."""
+
+    fields: tuple[str, ...] = ()
+    """Names of the fields the spell covers."""
+
+    implements: tuple[str, ...] = ()
+    """Names of the implements the spell may use."""
+
+    url: str | None = None
+    """Where the overseer can reach this ushabti."""
+
+    version: str | None = None
+    """Version of the agent runtime."""
+
+    sent_at: datetime = pydantic.Field(default_factory=utc_now)
+    """When this message was produced."""

ushabti/implements/__init__.py

@@ -0,0 +1,185 @@
+"""Implements: the tools an ushabti can use.
+
+Every implement is either ``read`` or ``write``. A write implement only runs
+when the weighing (the safety gate) returned ``PASS`` for it. That rule is
+enforced here, in ``Implement.run``, so no caller can skip it by accident.
+"""
+
+import re
+from abc import ABC, abstractmethod
+from collections.abc import Iterable, Iterator, Mapping
+from enum import StrEnum
+from typing import TYPE_CHECKING, ClassVar, Final, final
+
+from pydantic import JsonValue
+
+from ushabti._base import WireModel
+from ushabti.errors import UnknownImplementError, UnweighedWriteError
+from ushabti.field import Field
+
+if TYPE_CHECKING:
+    from ushabti.weighing import WeighingResult
+
+IMPLEMENT_NAME: Final = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$")
+"""Implement names look like ``kubernetes.list_pods``: a namespace, a dot, an operation."""
+
+NO_PARAMETERS: Final[Mapping[str, JsonValue]] = {
+    "type": "object",
+    "properties": {},
+    "additionalProperties": False,
+}
+
+
+class ImplementKind(StrEnum):
+    """Whether an implement only observes or can change something."""
+
+    READ = "read"
+    WRITE = "write"
+
+
+class ImplementSpec(WireModel):
+    """What a model is told about an implement."""
+
+    name: str
+    kind: ImplementKind
+    description: str
+    parameters: dict[str, JsonValue]
+
+
+class Implement(ABC):
+    """A tool an ushabti can use.
+
+    Subclasses set ``name``, ``kind``, ``description``, and ``parameters`` (a
+    JSON Schema for the arguments), and implement ``_run``. Callers use
+    ``run``, which checks the verdict first.
+
+    This is an abstract base class and not a structural protocol on purpose:
+    the verdict check lives in ``run``, and only inheritance guarantees that
+    every implement carries it.
+    """
+
+    name: ClassVar[str]
+    kind: ClassVar[ImplementKind]
+    description: ClassVar[str]
+    parameters: ClassVar[Mapping[str, JsonValue]] = NO_PARAMETERS
+
+    @final
+    async def run(
+        self,
+        arguments: Mapping[str, JsonValue],
+        *,
+        field: Field | None = None,
+        weighed: "WeighingResult | None" = None,
+    ) -> JsonValue:
+        """Run the implement, refusing unless the weighing allows it.
+
+        A write implement needs a ``PASS`` verdict naming this implement. A
+        read implement may run without one, which is how the vigil observes,
+        but when a verdict is given it must also be ``PASS``.
+        """
+        self._require_pass(weighed)
+        return await self._run(arguments, field)
+
+    @abstractmethod
+    async def _run(self, arguments: Mapping[str, JsonValue], field: Field | None) -> JsonValue:
+        """Do the work. Never call this directly: go through ``run``."""
+
+    def spec(self) -> ImplementSpec:
+        """The description of this implement that a model sees."""
+        return ImplementSpec(
+            name=self.name,
+            kind=self.kind,
+            description=self.description,
+            parameters=dict(self.parameters),
+        )
+
+    def _require_pass(self, weighed: "WeighingResult | None") -> None:
+        # Imported here because weighing imports this module for ImplementKind.
+        from ushabti.weighing import Verdict
+
+        if weighed is None:
+            if self.kind is ImplementKind.READ:
+                return
+            raise UnweighedWriteError(
+                f"{self.name} is a write implement and was not weighed; "
+                "a write only runs with a PASS verdict"
+            )
+        if weighed.implement != self.name:
+            raise UnweighedWriteError(
+                f"the verdict is for {weighed.implement}, not for {self.name}"
+            )
+        if weighed.verdict is not Verdict.PASS:
+            raise UnweighedWriteError(
+                f"{self.name} was weighed {weighed.verdict.value}; only PASS may run"
+            )
+
+
+class ImplementRegistry:
+    """The implements a process knows about, by name."""
+
+    def __init__(self, implements: Iterable[Implement] = ()) -> None:
+        self._implements: dict[str, Implement] = {}
+        for implement in implements:
+            self.register(implement)
+
+    def register(self, implement: Implement) -> None:
+        """Add an implement. Its name must be well formed and not taken."""
+        name = getattr(implement, "name", None)
+        if not isinstance(name, str) or IMPLEMENT_NAME.match(name) is None:
+            raise ValueError(
+                f"implement name {name!r} must look like namespace.operation, "
+                "in lowercase letters, digits, and underscores"
+            )
+        if not isinstance(getattr(implement, "kind", None), ImplementKind):
+            raise ValueError(f"implement {name} must declare kind as read or write")
+        if not getattr(implement, "description", ""):
+            raise ValueError(f"implement {name} must have a description")
+        if name in self._implements:
+            raise ValueError(f"implement {name} is already registered")
+        self._implements[name] = implement
+
+    def get(self, name: str) -> Implement:
+        """The implement with this name, or UnknownImplementError."""
+        try:
+            return self._implements[name]
+        except KeyError:
+            raise UnknownImplementError(name) from None
+
+    def find(self, name: str) -> Implement | None:
+        """The implement with this name, or None."""
+        return self._implements.get(name)
+
+    def kind_of(self, name: str) -> ImplementKind | None:
+        """The kind of the named implement, or None when it is not registered."""
+        implement = self._implements.get(name)
+        return None if implement is None else implement.kind
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(sorted(self._implements))
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._implements
+
+    def __iter__(self) -> Iterator[Implement]:
+        return iter(self._implements.values())
+
+    def __len__(self) -> int:
+        return len(self._implements)
+
+
+def builtin_implements() -> tuple[Implement, ...]:
+    """Fresh instances of every implement that ships with the SDK."""
+    # Imported here because these modules import Implement from this one.
+    from ushabti.implements import kubernetes, noop, prometheus, proxmox
+
+    return (
+        *noop.implements(),
+        *kubernetes.implements(),
+        *proxmox.implements(),
+        *prometheus.implements(),
+    )
+
+
+def default_registry() -> ImplementRegistry:
+    """A new registry holding the built-in implements."""
+    return ImplementRegistry(builtin_implements())