openmagpie 0.1.0__py3-none-any.whl

openmagpie/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

openmagpie/action_template.yaml

@@ -0,0 +1,18 @@
+# A single watch action: `{kind, config}`. Author it for:
+#   magpie watch action add  --watch <watch_id> -f action.yaml   # new action
+#   magpie watch action edit  <action_id>       -f action.yaml   # replace one
+# Or run either with no -f to fill in this template (add) / edit the
+# action's current config (edit) in $EDITOR.
+#
+# `kind` selects the action type; `config` is its kind-specific settings.
+# A chain's first action is typically a semantic_filter (an LLM relevance
+# gate that STOPS the chain when an item scores below `threshold`); delivery
+# actions (log, webhook) follow. Each kind has its own `config` shape; the
+# semantic_filter below is the common starting point (see `magpie watch
+# template` for a full chain, or `magpie watch action get <id>` for a live one).
+
+kind: semantic_filter
+config:
+  instructions: posts about an interesting new open-source LLM release
+  threshold: 0.7   # pass when relevance >= this (0.0 < threshold <= 1.0)
+  # engine: {kind: "", model: ""}   # optional; empty = server default

openmagpie/api/__init__.py

@@ -0,0 +1,56 @@
+"""Top-level API coordinator.
+
+`Api` owns the underlying MagpieClient and exposes resource sub-clients
+lazily via `@cached_property`. Call sites read like an SDK:
+
+    ac.api.auth.me()
+    ac.api.auth.create_device_session()
+    ac.api.feed.list()
+    ac.api.feed.create({...})
+
+Adding a resource = one new file in `api/`, one cached_property here.
+"""
+
+from __future__ import annotations
+
+from functools import cached_property
+
+from ..http import MagpieClient
+from .activity import ActivityApi
+from .auth import AuthApi
+from .delivery import DeliveryApi
+from .engine import EngineApi
+from .feed import FeedApi
+from .watch import WatchApi
+
+
+class Api:
+    def __init__(self, http: MagpieClient) -> None:
+        self._http = http
+
+    @cached_property
+    def auth(self) -> AuthApi:
+        return AuthApi(self._http)
+
+    @cached_property
+    def feed(self) -> FeedApi:
+        return FeedApi(self._http)
+
+    @cached_property
+    def watch(self) -> WatchApi:
+        return WatchApi(self._http)
+
+    @cached_property
+    def activity(self) -> ActivityApi:
+        return ActivityApi(self._http)
+
+    @cached_property
+    def delivery(self) -> DeliveryApi:
+        return DeliveryApi(self._http)
+
+    @cached_property
+    def engine(self) -> EngineApi:
+        return EngineApi(self._http)
+
+
+__all__ = ["ActivityApi", "Api", "AuthApi", "DeliveryApi", "EngineApi", "FeedApi", "WatchApi"]

openmagpie/api/_params.py

@@ -0,0 +1,20 @@
+"""Shared query-param helper for the cursor-paginated observability lists."""
+
+from __future__ import annotations
+
+
+def list_params(
+    *, state: str | None = None, after: str | None = None, limit: int | None = None, window: str | None = None
+) -> dict[str, str] | None:
+    """The cursor-list query params shared by the activity / delivery list
+    endpoints, dropping the unset ones. None when empty so httpx sends none."""
+    params: dict[str, str] = {}
+    if state:
+        params["state"] = state
+    if after:
+        params["after"] = after
+    if limit is not None:
+        params["limit"] = str(limit)
+    if window:
+        params["window"] = window
+    return params or None

openmagpie/api/activity.py

@@ -0,0 +1,39 @@
+"""Activity (run audit) API resource client.
+
+The flat observability noun over one action's `WatchActionRun`s: the list
+(`/v1/actions/<id>/activity`, whose first page also carries the summary
+rollup) and one run's detail (`/v1/action-activity/<id>`). Shapes live once in
+`openmagpie_schema.watch`; the server is the authority.
+"""
+
+from __future__ import annotations
+
+from openmagpie_schema.watch import WatchActionRunListResponse, WatchActionRunView
+
+from .. import routes
+from ..http import MagpieClient
+from ._params import list_params
+
+
+class ActivityApi:
+    def __init__(self, http: MagpieClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        action_id: str,
+        *,
+        state: str | None = None,
+        after: str | None = None,
+        limit: int | None = None,
+        window: str | None = None,
+    ) -> WatchActionRunListResponse:
+        # `window` is the summary preset (server resolves it to bounds); the
+        # first page carries the summary rollup, paged calls don't.
+        params = list_params(state=state, after=after, limit=limit, window=window)
+        raw = self._http.get(routes.actions.runs(action_id), params=params)
+        return WatchActionRunListResponse.model_validate(raw)
+
+    def get(self, activity_id: str) -> WatchActionRunView:
+        raw = self._http.get(routes.action_activity.detail(activity_id))
+        return WatchActionRunView.model_validate(raw)

openmagpie/api/auth.py

@@ -0,0 +1,167 @@
+"""Auth API resource client + response models.
+
+`AuthApi` wraps the transport client with typed entrypoints for every
+`/v1/auth/*` endpoint. Accessed via `Api.auth` (see `api/__init__.py`),
+so call sites read `ac.api.auth.me()` rather than threading the raw
+http client through each handler.
+
+Models match the Django response shapes (see `core/auth_api/`); update
+both sides together when the contract changes.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel
+
+from .. import routes
+from ..constants import DeviceSessionStatus
+from ..http import MagpieClient, client_info
+
+
+class AuthUser(BaseModel):
+    id: str
+    email: str
+    account_id: str | None = None
+    created_at: str
+
+
+class TokenPair(BaseModel):
+    access_token: str
+    refresh_token: str
+    expires_in: int
+    token_type: Literal["Bearer"]  # OAuth2 token_type per RFC 6750
+    user: AuthUser
+
+
+class DeviceSessionCreated(BaseModel):
+    session_id: str
+    authorize_url: str
+    user_code: str
+    # Bearer credential the CLI presents on each poll. Returned by the
+    # server ONCE at create time; never persisted to disk. Identifies
+    # *this CLI process* as the legitimate poller for this session_id.
+    device_secret: str
+    expires_in: int
+
+
+class DeviceSessionPending(BaseModel):
+    status: Literal[DeviceSessionStatus.PENDING]
+
+
+class DeviceSessionExpired(BaseModel):
+    status: Literal[DeviceSessionStatus.EXPIRED]
+
+
+class DeviceSessionCompleted(TokenPair):
+    """Completed bag is a TokenPair plus the status tag for the union
+    discriminator. Inheriting keeps `AppContext.sign_in(bundle)` polymorphic
+    across the device-flow completion path and any future direct-login path.
+    """
+
+    status: Literal[DeviceSessionStatus.COMPLETED]
+
+
+DeviceSessionPoll = DeviceSessionPending | DeviceSessionCompleted | DeviceSessionExpired
+
+
+class CliToken(BaseModel):
+    """Metadata for one personal access token. Never carries the raw
+    secret; only the mint response (`CliTokenCreated`) does, once."""
+
+    id: str
+    name: str
+    last_four: str
+    created_at: datetime
+    last_used_at: datetime | None = None
+    expires_at: datetime | None = None
+
+
+class CliTokenCreated(CliToken):
+    """`POST` response: metadata plus the raw `token`, shown once."""
+
+    token: str
+
+
+class TokensApi:
+    """Resource client for `/v1/auth/tokens/*`, bearer lifecycle."""
+
+    def __init__(self, http: MagpieClient) -> None:
+        self._http = http
+
+    def revoke(self) -> None:
+        """Invalidate the current bearer token server-side. Best-effort:
+        the server returns 200 even if the token is already revoked, so
+        this won't raise except on transport errors.
+        """
+        self._http.post(routes.auth.tokens.revoke)
+
+
+class CliTokensApi:
+    """Resource client for `/v1/auth/cli-tokens`, personal access tokens."""
+
+    def __init__(self, http: MagpieClient) -> None:
+        self._http = http
+
+    def create(self, *, name: str, expires_in_days: int | None = None) -> CliTokenCreated:
+        body: dict[str, object] = {"name": name}
+        if expires_in_days is not None:
+            body["expires_in_days"] = expires_in_days
+        raw = self._http.post(routes.auth.cli_tokens, json_body=body)
+        return CliTokenCreated.model_validate(raw)
+
+    def list(self) -> list[CliToken]:
+        raw = self._http.get(routes.auth.cli_tokens)
+        return [CliToken.model_validate(t) for t in raw]
+
+    def revoke(self, token_id: str) -> None:
+        self._http.delete(routes.auth.cli_token(token_id))
+
+
+class AuthApi:
+    """Resource client for `/v1/auth/*`."""
+
+    def __init__(self, http: MagpieClient) -> None:
+        self._http = http
+        self.tokens = TokensApi(http)
+        self.cli_tokens = CliTokensApi(http)
+
+    def create_device_session(self) -> DeviceSessionCreated:
+        raw = self._http.post(
+            routes.auth.device_sessions,
+            with_auth=False,
+            # Structured CLI identity. Server stores it under `initiator`
+            # in the cache bag; the authorize page renders the fields
+            # directly with no User-Agent parsing.
+            json_body={"client": client_info()},
+        )
+        return DeviceSessionCreated.model_validate(raw)
+
+    def poll_device_session(self, session_id: str, *, device_secret: str) -> DeviceSessionPoll:
+        raw = self._http.get(
+            routes.auth.device_session(session_id),
+            # (Re-)login: authenticated by the device secret, NOT the stored
+            # bearer. Sending a stale/revoked credential here would get the
+            # poll rejected with 401 before the device secret is checked.
+            with_auth=False,
+            headers={"X-Device-Secret": device_secret},
+        )
+        status = raw.get("status")
+        match status:
+            case DeviceSessionStatus.COMPLETED:
+                return DeviceSessionCompleted.model_validate(raw)
+            case DeviceSessionStatus.EXPIRED:
+                return DeviceSessionExpired.model_validate(raw)
+            case DeviceSessionStatus.PENDING:
+                return DeviceSessionPending.model_validate(raw)
+            case _:
+                # An unknown status means the server contract changed
+                # out from under us. Failing loud beats quietly treating
+                # it as pending and looping forever.
+                raise RuntimeError(f"unknown device-session status from server: {status!r}")
+
+    def me(self) -> AuthUser:
+        raw = self._http.get(routes.auth.me)
+        return AuthUser.model_validate(raw)

openmagpie/api/delivery.py

@@ -0,0 +1,36 @@
+"""Delivery (outbound HTTP call audit) API resource client.
+
+The flat observability noun over one action's `WatchActionDelivery`s: the list
+(`/v1/actions/<id>/deliveries`, lean rows) and one delivery's detail
+(`/v1/action-deliveries/<id>`, including the sent request payload). Shapes live
+once in `openmagpie_schema.watch`; the server is the authority.
+"""
+
+from __future__ import annotations
+
+from openmagpie_schema.watch import WatchActionDeliveryListResponse, WatchActionDeliveryView
+
+from .. import routes
+from ..http import MagpieClient
+from ._params import list_params
+
+
+class DeliveryApi:
+    def __init__(self, http: MagpieClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        action_id: str,
+        *,
+        state: str | None = None,
+        after: str | None = None,
+        limit: int | None = None,
+    ) -> WatchActionDeliveryListResponse:
+        params = list_params(state=state, after=after, limit=limit)
+        raw = self._http.get(routes.actions.deliveries(action_id), params=params)
+        return WatchActionDeliveryListResponse.model_validate(raw)
+
+    def get(self, delivery_id: str) -> WatchActionDeliveryView:
+        raw = self._http.get(routes.deliveries.detail(delivery_id))
+        return WatchActionDeliveryView.model_validate(raw)

openmagpie/api/engine.py

@@ -0,0 +1,34 @@
+"""Engines API resource client.
+
+Wraps `/v1/engines`. Response models live in the shared
+`openmagpie_schema.engine` module and are imported verbatim.
+
+Intended to back a future pre-flight check (surfacing "LLM unreachable"
+at config time beats discovering it via 500-per-judge-cycle once polling
+starts); no `magpie` command consumes it yet.
+"""
+
+from __future__ import annotations
+
+from openmagpie_schema.engine import EngineListResponse, EngineStatus
+
+from .. import routes
+from ..http import MagpieClient
+
+__all__ = ["EngineApi", "EngineListResponse", "EngineStatus"]
+
+
+class EngineApi:
+    """Resource client for `/v1/engines`."""
+
+    def __init__(self, http: MagpieClient) -> None:
+        self._http = http
+
+    def list(self) -> list[EngineStatus]:
+        """GET /v1/engines — registered engines + reachability snapshot.
+
+        Returns the unwrapped items list; the envelope is internal and
+        callers always want the per-engine entries.
+        """
+        raw = self._http.get(routes.engines.collection)
+        return EngineListResponse.model_validate(raw).items

openmagpie/api/feed.py

@@ -0,0 +1,151 @@
+"""Feeds API resource client.
+
+Wraps the `/v1/feeds` endpoints. Response
+models live ONCE in the shared `openmagpie_schema.feed` package
+(populated by the server, imported verbatim here). Only `FeedEnvelope`
+(the request envelope the CLI *constructs*) is CLI-owned.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from openmagpie_schema.feed import (
+    FeedItemListResponse,
+    FeedItemWire,
+    FeedListResponse,
+    FeedMutationResponse,
+    FeedView,
+    FeedWire,
+    SourceInput,
+    SourceSetResult,
+    SourceWire,
+)
+from openmagpie_schema.wire import ConfigBlob
+
+from .. import routes
+from ..http import MagpieClient
+
+__all__ = [
+    "FeedApi",
+    "FeedEnvelope",
+    "FeedItemListResponse",
+    "FeedItemWire",
+    "FeedListResponse",
+    "FeedMutationResponse",
+    "FeedView",
+    "FeedWire",
+    "SourceSetResult",
+    "SourceWire",
+]
+
+
+class FeedEnvelope(BaseModel):
+    """The envelope the CLI constructs for a feed write (request side).
+    CLI-owned, distinct from the server-emitted models. `data` carries
+    the kind-specific config (retention + default_field_map), opaque
+    here; the server validates it. `sources` is the optional starter
+    source list for curated feeds (server creates Source rows
+    atomically with the Feed). Extra keys ignored (so the edit seed's
+    read-only fields drop on round-trip)."""
+
+    name: str
+    kind: str = "curated"
+    poll_interval_seconds: int = 300
+    data: ConfigBlob = {}
+    sources: list[SourceInput] = []
+
+    model_config = {"extra": "ignore"}
+
+
+class FeedApi:
+    """Resource client for `/v1/feeds`."""
+
+    def __init__(self, http: MagpieClient) -> None:
+        self._http = http
+
+    def create(self, body: dict[str, Any], *, dry_run: bool = False) -> FeedMutationResponse:
+        params = {"dry_run": "true"} if dry_run else None
+        raw = self._http.post(routes.feeds.collection, json_body=body, params=params)
+        return FeedMutationResponse.model_validate(raw)
+
+    def list(self, *, after: str | None = None, limit: int | None = None) -> FeedListResponse:
+        """One page of feeds (cursor-paginated, newest-first by ULID pk).
+        `after` = id of the last feed from the previous page; omit on first
+        call. The returned `next_cursor` is None when there are no more rows.
+        """
+        params: dict[str, Any] = {}
+        if after:
+            params["after"] = after
+        if limit is not None:
+            params["limit"] = limit
+        raw = self._http.get(routes.feeds.collection, params=params or None)
+        return FeedListResponse.model_validate(raw)
+
+    def get(self, feed_id: str) -> FeedView:
+        """GET one feed's CONFIG detail (account-scoped): the kind-independent
+        envelope + display `summary` + its current source set. The item log is a
+        separate read (`feed item list` / GET /v1/feeds/<id>/items); this view is
+        the feed's configuration, not its items."""
+        raw = self._http.get(routes.feeds.detail(feed_id))
+        return FeedView.model_validate(raw)
+
+    def update(self, feed_id: str, body: dict[str, Any], *, dry_run: bool = False) -> FeedMutationResponse:
+        params = {"dry_run": "true"} if dry_run else None
+        raw = self._http.put(routes.feeds.detail(feed_id), json_body=body, params=params)
+        return FeedMutationResponse.model_validate(raw)
+
+    def delete(self, feed_id: str) -> None:
+        self._http.delete(routes.feeds.detail(feed_id))
+
+    # ── Items sub-resource (read-only) ─────────────────────────────────
+
+    def list_items(self, feed_id: str, *, after: str | None = None, limit: int | None = None) -> FeedItemListResponse:
+        """One page of the feed's items (cursor-paginated, newest-first by ULID
+        pk). `after` = id of the last item from the previous page; the returned
+        `next_cursor` is None when there are no more rows."""
+        params: dict[str, Any] = {}
+        if after:
+            params["after"] = after
+        if limit is not None:
+            params["limit"] = limit
+        raw = self._http.get(routes.feeds.items(feed_id), params=params or None)
+        return FeedItemListResponse.model_validate(raw)
+
+    def get_item(self, item_id: str) -> FeedItemWire:
+        """GET one feed item by its own (globally unique) ULID, account-scoped."""
+        raw = self._http.get(routes.feed_items.detail(item_id))
+        return FeedItemWire.model_validate(raw)
+
+    # ── Sources sub-resource ───────────────────────────────────────────
+
+    def list_sources(self, feed_id: str) -> list[SourceWire]:
+        raw = self._http.get(routes.feeds.sources(feed_id))
+        items = (raw or {}).get("items") or []
+        return [SourceWire.model_validate(it) for it in items]
+
+    def get_source(self, source_id: str) -> SourceWire:
+        """GET one source by its own (globally unique) ULID; the server resolves
+        its feed (sources address by own id, not feed-scoped)."""
+        raw = self._http.get(routes.feed_sources.detail(source_id))
+        return SourceWire.model_validate(raw)
+
+    def set_sources(
+        self,
+        feed_id: str,
+        sources: list[dict[str, Any]],
+        *,
+        dry_run: bool = False,
+    ) -> SourceSetResult:
+        raw = self._http.put(
+            routes.feeds.sources(feed_id),
+            json_body={"sources": sources, "dry_run": dry_run},
+        )
+        return SourceSetResult.model_validate(raw)
+
+    def delete_source(self, source_id: str) -> None:
+        # By the source's own id; the server resolves its feed (sources address
+        # by own id now, not feed-scoped).
+        self._http.delete(routes.feed_sources.detail(source_id))

openmagpie/api/watch.py

@@ -0,0 +1,100 @@
+"""Watches API resource client.
+
+Wraps the `/v1/watches` endpoints. ALL shapes live ONCE in the shared
+`openmagpie_schema.watch` package (the server is the authority) and are
+imported verbatim here — including the write envelope `WatchInput`, which
+the CLI constructs. No CLI-side copy. Mirrors `api/feed.py`.
+"""
+
+from __future__ import annotations
+
+import builtins
+from typing import Any
+
+from openmagpie_schema.watch import (
+    WatchActionWire,
+    WatchInput,
+    WatchListResponse,
+    WatchMutationResponse,
+    WatchView,
+    WatchWire,
+)
+
+from .. import routes
+from ..http import MagpieClient
+
+__all__ = [
+    "WatchApi",
+    "WatchInput",
+    "WatchListResponse",
+    "WatchMutationResponse",
+    "WatchView",
+    "WatchWire",
+]
+
+
+class WatchApi:
+    """Resource client for `/v1/watches`."""
+
+    def __init__(self, http: MagpieClient) -> None:
+        self._http = http
+
+    def create(self, body: dict[str, Any], *, dry_run: bool = False) -> WatchMutationResponse:
+        params = {"dry_run": "true"} if dry_run else None
+        raw = self._http.post(routes.watches.collection, json_body=body, params=params)
+        return WatchMutationResponse.model_validate(raw)
+
+    def list(self, *, after: str | None = None, limit: int | None = None) -> WatchListResponse:
+        """One page of watches (cursor-paginated, newest-first by ULID pk).
+        `after` = id of the last watch from the previous page; omit on the
+        first call. `next_cursor` is None when there are no more rows."""
+        params: dict[str, Any] = {}
+        if after:
+            params["after"] = after
+        if limit is not None:
+            params["limit"] = limit
+        raw = self._http.get(routes.watches.collection, params=params or None)
+        return WatchListResponse.model_validate(raw)
+
+    def get(self, watch_id: str) -> WatchView:
+        """GET one watch (account-scoped). Carries the initial path's
+        ordered action chain."""
+        raw = self._http.get(routes.watches.detail(watch_id))
+        return WatchView.model_validate(raw)
+
+    def update(self, watch_id: str, body: dict[str, Any], *, dry_run: bool = False) -> WatchMutationResponse:
+        params = {"dry_run": "true"} if dry_run else None
+        raw = self._http.put(routes.watches.detail(watch_id), json_body=body, params=params)
+        return WatchMutationResponse.model_validate(raw)
+
+    def delete(self, watch_id: str) -> None:
+        self._http.delete(routes.watches.detail(watch_id))
+
+    # ── Actions sub-resource (the chain) ────────────────────────────────
+
+    def list_actions(self, watch_id: str) -> builtins.list[WatchActionWire]:
+        raw = self._http.get(routes.watches.actions(watch_id))
+        items = (raw or {}).get("items") or []
+        return [WatchActionWire.model_validate(it) for it in items]
+
+    def get_action(self, action_id: str) -> WatchActionWire:
+        """GET one action's definition (kind + redacted config + summary) by its
+        own id; the watch/chain is resolved server-side, not in the path."""
+        raw = self._http.get(routes.actions.detail(action_id))
+        return WatchActionWire.model_validate(raw)
+
+    def add_action(
+        self, watch_id: str, kind: str, config: dict[str, Any], *, rank: int | None = None
+    ) -> WatchActionWire:
+        body: dict[str, Any] = {"kind": kind, "config": config}
+        if rank is not None:
+            body["rank"] = rank
+        raw = self._http.post(routes.watches.actions(watch_id), json_body=body)
+        return WatchActionWire.model_validate(raw)
+
+    def edit_action(self, action_id: str, kind: str, config: dict[str, Any]) -> WatchActionWire:
+        raw = self._http.put(routes.actions.detail(action_id), json_body={"kind": kind, "config": config})
+        return WatchActionWire.model_validate(raw)
+
+    def delete_action(self, action_id: str) -> None:
+        self._http.delete(routes.actions.detail(action_id))

openmagpie/cli.py

@@ -0,0 +1,60 @@
+"""Root Typer app + subcommand registration."""
+
+from __future__ import annotations
+
+import typer
+
+from .commands.activity import activity_app
+from .commands.auth import auth_app
+from .commands.delivery import delivery_app
+from .commands.feed import feed_app
+from .commands.watch import watch_app
+from .context import AppContext, bind_app_ctx, unbind_app_ctx
+
+app = typer.Typer(
+    name="magpie",
+    help="The magpie CLI. Talk to an OpenMagpie server.",
+    no_args_is_help=True,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    server: str | None = typer.Option(
+        None,
+        "--server",
+        "-s",
+        help="OpenMagpie server URL override for this invocation.",
+    ),
+) -> None:
+    """Build the shared AppContext (config + resource API) and bind it
+    into the ContextVar so every subcommand can pull it via `app_ctx()`.
+    """
+    obj = AppContext(server_url=server)
+    token = bind_app_ctx(obj)
+    ctx.call_on_close(obj.close)
+    ctx.call_on_close(lambda: unbind_app_ctx(token))
+
+
+app.add_typer(auth_app, name="auth", help="Sign in / out and inspect identity.")
+app.add_typer(
+    feed_app,
+    name="feed",
+    help="Curate + read feeds (the source set watches subscribe to).",
+)
+app.add_typer(
+    watch_app,
+    name="watch",
+    help="Build + manage watches (a feed subscription + action chain).",
+)
+app.add_typer(
+    activity_app,
+    name="activity",
+    help="Audit an action's runs: summary / list / one in full.",
+)
+app.add_typer(
+    delivery_app,
+    name="delivery",
+    help="Audit an action's outbound webhook calls.",
+)