elan-sdk 0.1.0__py3-none-any.whl

elan_sdk/__init__.py

@@ -0,0 +1,175 @@
+"""The Elan API, as a developer's backend calls it.
+
+    from elan_sdk import AsyncElan
+
+    async with AsyncElan.from_env() as elan:
+        print((await elan.whoami())["tenant_id"])
+
+ONE BASE URL AND ONE CREDENTIAL. Two services sit behind that host, split by
+path, and the ledger and the action store are not publicly routed at all —
+which is the client's problem and not yours.
+
+WHAT THIS DOES NOT COVER, named here because it is the first question: projects,
+deployments, secrets, validation and service users belong to the `elan` CLI and
+are documented in `docs/developer-docs/api.md`. This is the runtime, the money
+and the approvals — the calls a product makes while it is serving a request.
+"""
+
+from elan_sdk._version import __version__
+from elan_sdk.artifacts import UploadTicket
+from elan_sdk.auth import ClientCredentials, StaticToken, TokenSource, claims_of
+from elan_sdk.client import AsyncElan
+from elan_sdk.config import Config
+from elan_sdk.errors import (
+    BadRequest,
+    Conflict,
+    CredentialsRefused,
+    DependencyRefused,
+    ElanError,
+    EndUserEventsElsewhere,
+    Forbidden,
+    NotFound,
+    NotWired,
+    PaymentRequired,
+    Problem,
+    ProjectNotNamed,
+    ServerError,
+    StreamClosed,
+    StreamError,
+    StreamRefused,
+    TicketIsNotACredential,
+    TicketRefused,
+    TransportError,
+    Unauthenticated,
+    Unavailable,
+)
+from elan_sdk.models.actions import (
+    Action,
+    ActionBatch,
+    ActionPage,
+    BatchOutcome,
+    Decision,
+    Label,
+    Policy,
+    PolicyScopes,
+    StoredPolicy,
+    Ticket,
+    ToolCall,
+    ToolOutcome,
+)
+from elan_sdk.models.events import (
+    CONTENT_KINDS,
+    KNOWN_KINDS,
+    PROGRESS_KINDS,
+    TERMINAL_KINDS,
+    AgentEvent,
+    author_of,
+    dedupe_by_path,
+    text_of,
+)
+from elan_sdk.models.money import (
+    Balance,
+    ChargedRun,
+    CostRow,
+    HoldPage,
+    HoldRow,
+    InvocationCharge,
+    LatencyBucket,
+    LatencySeries,
+    ModelUsage,
+    MoneyBucket,
+    MoneySeries,
+    RunBucket,
+    RunSeries,
+    StatementEntry,
+    StatementPage,
+    TokenBucket,
+    TokenSeries,
+    ToolBucket,
+    ToolSeries,
+    Transaction,
+    UsageRow,
+    Wallet,
+    WalletPage,
+)
+from elan_sdk.money import MICROS_PER_USD, dollars, micros
+from elan_sdk.sync import Elan
+
+__all__ = [
+    "Action",
+    "ActionBatch",
+    "ActionPage",
+    "AgentEvent",
+    "AsyncElan",
+    "BadRequest",
+    "Balance",
+    "BatchOutcome",
+    "CONTENT_KINDS",
+    "ChargedRun",
+    "ClientCredentials",
+    "Config",
+    "Conflict",
+    "CostRow",
+    "CredentialsRefused",
+    "Decision",
+    "DependencyRefused",
+    "Elan",
+    "ElanError",
+    "EndUserEventsElsewhere",
+    "Forbidden",
+    "HoldPage",
+    "HoldRow",
+    "InvocationCharge",
+    "KNOWN_KINDS",
+    "Label",
+    "LatencyBucket",
+    "LatencySeries",
+    "MICROS_PER_USD",
+    "ModelUsage",
+    "MoneyBucket",
+    "MoneySeries",
+    "NotFound",
+    "NotWired",
+    "PROGRESS_KINDS",
+    "PaymentRequired",
+    "Policy",
+    "PolicyScopes",
+    "Problem",
+    "ProjectNotNamed",
+    "RunBucket",
+    "RunSeries",
+    "ServerError",
+    "StatementEntry",
+    "StatementPage",
+    "StaticToken",
+    "StoredPolicy",
+    "StreamClosed",
+    "StreamError",
+    "StreamRefused",
+    "TERMINAL_KINDS",
+    "Ticket",
+    "UploadTicket",
+    "TicketIsNotACredential",
+    "TicketRefused",
+    "TokenBucket",
+    "TokenSeries",
+    "TokenSource",
+    "ToolBucket",
+    "ToolCall",
+    "ToolOutcome",
+    "ToolSeries",
+    "Transaction",
+    "TransportError",
+    "Unauthenticated",
+    "Unavailable",
+    "UsageRow",
+    "Wallet",
+    "WalletPage",
+    "__version__",
+    "author_of",
+    "claims_of",
+    "dedupe_by_path",
+    "dollars",
+    "micros",
+    "text_of",
+]

elan_sdk/_tls.py

@@ -0,0 +1,35 @@
+"""A TLS context that trusts the same roots every HTTP call here does.
+
+MOVED FROM `elan_cli/stream.py`, WHICH FOUND THIS THE HARD WAY. macOS's
+python.org builds ship NO CA BUNDLE. OpenSSL's default path finds nothing, so a
+perfectly valid Let's Encrypt certificate fails with
+
+    CERTIFICATE_VERIFY_FAILED: unable to get local issuer certificate
+
+while `curl` and `openssl s_client` accept it on the same machine — and every
+HTTP call in this SDK works, because httpx bundles certifi and `websockets`
+uses the system default. So the symptom is ONE FEATURE failing on TLS while
+everything else is fine, which reads as a server problem.
+
+`scripts/zitadel_configure.py` carries the same note for the same reason. This
+is that lesson arriving in a third place, which is why it is a module rather
+than a line.
+"""
+
+from __future__ import annotations
+
+
+def trust() -> object | None:
+    """A certifi-backed SSL context, or None to fall back to the system's."""
+    import ssl  # noqa: PLC0415
+
+    try:
+        import certifi  # noqa: PLC0415
+    except ImportError:  # pragma: no cover - certifi is a declared dependency
+        # The system default is still worth trying: on Linux it is correct, and
+        # failing outright here would be worse than failing at the handshake.
+        return None
+    return ssl.create_default_context(cafile=certifi.where())
+
+
+__all__ = ["trust"]

elan_sdk/_version.py

@@ -0,0 +1,8 @@
+"""One version number, two registries.
+
+The npm package publishes the same string, and
+`tests/test_sdk_packaging.py` asserts they agree — because a developer reading
+two SDKs' versions should be able to tell whether they describe the same API.
+"""
+
+__version__ = "0.1.0"

elan_sdk/actions.py

@@ -0,0 +1,253 @@
+"""Tool approvals — and the batch, which is the thing to get right.
+
+THE NEXT MESSAGE RESOLVES EVERY CONFIRMATION A TURN RAISED. ADK keeps no notion
+of answering one of three, so deciding one and leaving the rest silently
+abandons them while the run reports finished — and sending a plain message
+abandons all of them with nothing said. So a turn's answers travel as ONE batch,
+published only when its last member is decided.
+
+`decide_batch` IS THEREFORE THE METHOD TO REACH FOR, and `decide` is honest
+about what it returns: `Decision.published` is false until the batch completes,
+which is the only way to know whether anything actually ran.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Literal
+
+from elan_sdk.models.actions import (
+    Action,
+    ActionBatch,
+    ActionPage,
+    BatchOutcome,
+    Decision,
+    Label,
+    action_from,
+)
+
+
+class Actions:
+    """What is waiting on a person, and answering it."""
+
+    def __init__(self, http, config=None) -> None:
+        self._http = http
+        self._config = config
+
+    def _project(self, project: str | None) -> str:
+        """WHICH OF THE TENANT'S PRODUCTS. Narrows; the credential authorises.
+
+        An agent slug is unique within a PROJECT and not within a tenant
+        (ADR-0054), so without this one inbox holds every project's
+        confirmations for the same target. Defaults to the client's own
+        project; pass `""` to see every project the credential may see. A
+        credential issued for one project is narrowed to it server-side
+        whether it asked or not, and naming a sibling is a `Forbidden`.
+        """
+        if project is not None:
+            return project
+        return getattr(self._config, "project", "") or ""
+
+    async def list(self, *, project: str | None = None, status: str = "pending",
+                   labels: Sequence[str] = (), target: str = "",
+                   session_id: str = "",
+                   scope: Literal["mine", "tenant"] = "mine",
+                   automatic: bool | None = None,
+                   kind: Literal["confirmation", "tool", "approval",
+                                 "all"] = "confirmation",
+                   user: str = "",
+                   limit: int = 100, offset: int = 0) -> ActionPage:
+        """Pending work, filtered.
+
+        `kind` DEFAULTS TO CONFIRMATIONS, which is a choice about what an inbox
+        is for: this store also holds long-running tool calls, whose answer is
+        a system's result rather than a person's judgement, and a queue mixing
+        the two is a queue nobody can act on. Those are `elan.tools`.
+
+        THERE ARE THREE KINDS, and `approval` was missing from this annotation
+        while the store accepted it throughout — so the one kind a developer
+        could not list through a typed client was the one with no namespace of
+        its own either. Those are `elan.approvals` now. `all` is every kind,
+        which the store accepts and anything else it refuses.
+
+        `automatic` IS TRI-STATE. None is every row, False is "only what a
+        person decided", True is "only what policy decided" — so a bool
+        default would delete one of the three.
+
+        LABELS COMBINE AS ANY-OF, because a category filter that narrowed to
+        the intersection usually shows nothing at all.
+
+        `user` NAMES ONE OF YOUR OWN END USERS as `eu:<id>`. It contradicts
+        `scope="tenant"`, which means every user, so sending both is a
+        `BadRequest` rather than a silent precedence.
+
+        `limit` REALLY IS THE LIMIT NOW. It was sent and dropped in transit, so
+        every caller received at most 100 rows beside a `total` reporting the
+        truth; `offset` walks the rest and `ActionPage.more` says whether to.
+        """
+        params: dict[str, Any] = {"project": self._project(project),
+                                  "status": status, "scope": scope,
+                                  "kind": kind, "limit": limit,
+                                  "offset": offset, "user": user,
+                                  "target": target, "session_id": session_id}
+        if automatic is not None:
+            params["automatic"] = automatic
+        if labels:
+            # A REPEATED PARAMETER AND NOT A JOINED ONE. The route declares
+            # `label: list[str] = Query(default=[])`, so `?label=a&label=b` is
+            # what it reads — a comma-joined value would arrive as one label
+            # named "a,b" and match nothing, silently.
+            params["label"] = list(labels)
+        answer = await self._http.get("/v1/actions", params=params)
+        rows = answer.get("actions", [])
+        return ActionPage(actions=tuple(action_from(row) for row in rows),
+                          total=int(answer.get("total", len(rows))),
+                          limit=int(answer.get("limit", limit)),
+                          offset=int(answer.get("offset", offset)))
+
+    async def labels(self, *, scope: Literal["mine", "tenant"] = "mine",
+                     project: str | None = None,
+                     user: str = "") -> tuple[Label, ...]:
+        """Which categories have work waiting, and how much.
+
+        THE ROUTE ANSWERS A BARE LIST where `/v1/actions` answers an object.
+        Normalised here so a caller never has to know which.
+        """
+        rows = await self._http.get(
+            "/v1/actions/labels",
+            params={"scope": scope, "project": self._project(project),
+                    "user": user})
+        return tuple(Label(label=row.get("label", ""),
+                           pending=int(row.get("pending", 0)))
+                     for row in rows or ())
+
+    async def get(self, action_id: str) -> Action | None:
+        """One action, or None.
+
+        VIA THE LIST, BECAUSE NO SINGLE-ACTION ROUTE IS PUBLISHED. rt-service
+        proxies the list, the labels and the decision, and nothing else — so
+        this is a filter rather than a fetch, and says so.
+        """
+        page = await self.list(status="all", kind="all", limit=500)
+        for action in page.actions:
+            if action.action_id == action_id:
+                return action
+        return None
+
+    async def batches(self, *, project: str | None = None,
+                      session_id: str = "", target: str = "",
+                      status: str = "pending",
+                      kind: Literal["confirmation", "tool", "all"] = "all",
+                      scope: Literal["mine", "tenant"] = "mine",
+                         user: str = "") -> tuple[ActionBatch, ...]:
+        """Pending work GROUPED BY TURN.
+
+        THE API HAS NO BATCH FILTER AND THE GROUPING IS WHAT A CALLER MUST NOT
+        GET WRONG, so it is done here rather than left as an exercise: every
+        member of a turn has to be answered before any of them takes effect.
+
+        `kind` DEFAULTS TO EVERYTHING HERE, unlike `list()`, because a batch is
+        a unit of work rather than an inbox — and a mixed turn's confirmation
+        half is meaningless without knowing a tool call is also outstanding.
+
+        `scope` AND `user` WERE MISSING HERE while `list()` and `labels()` both
+        took them, which made an admin's tenant-wide view ungroupable and made
+        this method unusable for the shape the SDK is built around — a backend
+        answering for its end users, whose confirmations are recorded against
+        `eu:<id>` and which `scope="mine"` therefore never finds. TypeScript
+        gained `scope` and this did not; both have all three now.
+        """
+        per_page = 500
+        found: list[Action] = []
+        offset = 0
+        while True:
+            # EVERY PAGE, NOT THE FIRST. Grouping is the whole point here, and
+            # a turn straddling a page boundary would be grouped from whichever
+            # members landed on it — then handed to `decide_batch`, which would
+            # answer those and silently abandon the rest. That is the exact
+            # failure this type exists to prevent, so it cannot depend on
+            # whether a caller remembered to page.
+            page = await self.list(project=project, status=status, target=target,
+                                   session_id=session_id, kind=kind, scope=scope,
+                                   user=user,
+                                   limit=per_page, offset=offset)
+            found.extend(page.actions)
+            if not page.actions or not page.more:
+                break
+            offset += per_page
+        grouped: dict[str, list[Action]] = {}
+        for action in found:
+            grouped.setdefault(action.batch_id, []).append(action)
+        return tuple(
+            ActionBatch(batch_id=batch_id,
+                        invocation_id=members[0].invocation_id,
+                        session_id=members[0].session_id,
+                        target_slug=members[0].target_slug,
+                        actions=tuple(members))
+            for batch_id, members in grouped.items())
+
+    async def decide(self, action_id: str, *, approved: bool, note: str = "",
+                     payload: Any = None,
+                     approve_all: bool = False,
+                     user: str = "") -> Decision:
+        """Answer ONE confirmation.
+
+        PREFER `decide_batch` UNLESS YOU KNOW THE TURN RAISED ONE. Answering
+        one of two silently abandons the other, and this method cannot tell you
+        that happened — only `published` tells you whether the batch completed.
+
+        `approve_all` WRITES A STANDING GRANT so the agent stops asking, and it
+        is recorded against the RUN'S OWNER rather than the decider: an admin
+        approving somebody else's card must not quietly grant themselves
+        autonomy while leaving the colleague asked about every call. 
+
+        `user` NAMES THE END USER THIS CARD BELONGS TO, for a backend answering
+        on their behalf. It authorises the call and does not change
+        `decided_by`, which is always the identity that really decided.
+        """
+        body: dict[str, Any] = {"approved": approved, "note": note,
+                                "payload": payload, "approve_all": approve_all}
+        if user:
+            body["user"] = user
+        answer = await self._http.post(
+            f"/v1/actions/{action_id}/decide", json=body)
+        return _decision(answer)
+
+    async def decide_batch(self, batch: ActionBatch | Sequence[str], *,
+                           approved: bool, note: str = "", payload: Any = None,
+                           approve_all: bool = False,
+                           user: str = "") -> BatchOutcome:
+        """Answer a whole turn, in order, and report what happened.
+
+        THE LAST ANSWER IS THE ONE THAT PUBLISHES, so these go one at a time
+        and the outcome carries every decision — including any the engine
+        recorded as abandoned, which can follow an approval and means NOTHING
+        RAN.
+        """
+        ids = (list(batch.action_ids) if isinstance(batch, ActionBatch)
+               else list(batch))
+        decisions: list[Decision] = []
+        for action_id in ids:
+            decisions.append(await self.decide(
+                action_id, approved=approved, note=note, payload=payload,
+                approve_all=approve_all, user=user))
+        last = decisions[-1] if decisions else None
+        return BatchOutcome(
+            batch_id=last.batch_id if last else "",
+            decisions=tuple(decisions),
+            complete=bool(last and last.batch_complete),
+            published=any(d.published for d in decisions))
+
+
+def _decision(answer: dict[str, Any]) -> Decision:
+    return Decision(
+        action_id=answer.get("action_id", ""),
+        status=answer.get("status", ""),
+        batch_id=answer.get("batch_id", ""),
+        batch_complete=bool(answer.get("batch_complete")),
+        published=bool(answer.get("published")),
+        rule_id=answer.get("rule_id"),
+    )
+
+
+__all__ = ["Actions"]

elan_sdk/agents.py

@@ -0,0 +1,44 @@
+"""What this tenant has deployed.
+
+A READ, AND ONLY A READ. Deploying is the CLI's and the console's business
+(ADR-0104 scoped projects and deployments out of this SDK); what a backend
+needs is what is running right now and what it declares — to render a card, or
+to explain to one of your users why a permission they granted did not take
+effect.
+"""
+
+from __future__ import annotations
+
+from elan_sdk.models.agents import DeployedAgent, agent_from
+
+
+class Agents:
+    """Reading what is deployed, and what each target declares."""
+
+    def __init__(self, http, config) -> None:
+        self._http = http
+        self._config = config
+
+    async def list(self, *, project: str | None = None) -> list[DeployedAgent]:
+        """Every target your credential may see.
+
+        `project` DEFAULTS TO THE CLIENT'S OWN, and `""` means every project
+        the credential may see — the same convention as `actions.list()`.
+        """
+        wanted = self._config.project if project is None else project
+        answer = await self._http.get("/v1/agents", params={"project": wanted})
+        return [agent_from(row) for row in (answer or {}).get("agents") or ()]
+
+    async def get(self, slug: str, *,
+                  project: str | None = None) -> DeployedAgent | None:
+        """One target, or None.
+
+        NONE RATHER THAN AN EXCEPTION, because "is this deployed" is a question
+        with a negative answer. There is no single-agent route, so this filters
+        the listing — which is also why it cannot tell "not deployed" from "not
+        yours", and must not, since the listing already collapses the two.
+        """
+        for agent in await self.list(project=project):
+            if agent.slug == slug:
+                return agent
+        return None