remember 0.2.0__py3-none-any.whl

remember/__init__.py

@@ -0,0 +1,74 @@
+"""Control-plane client for the remember.dev managed service.
+
+PyPI project **`remember`**, import name **`remember`** (D43 left the import name
+open and required the first publish to document it; this is that record). The
+distribution installs **no** ``remember`` console script — that entry point
+belongs to ``rememberstack`` alone, and two distributions competing for one name
+on ``PATH`` is the collision D43 rule 3 forbids.
+
+What this package is for
+------------------------
+
+``rememberstack`` answers *memory* questions: ingest a document, search claims,
+run an assured operation. It cannot answer the questions an operator of that
+memory also has —
+
+* is my deployment ready?
+* what is my balance, and what did that ingest cost?
+* has spend safety parked my work?
+
+Those live on the control plane, which until D53 accepted only a browser session
+cookie. This client speaks to it with a **control-plane token** (``umc_cp_…``):
+organisation-scoped, read-only, bounded lifetime, revocable by its bearer.
+
+    from remember import CloudClient
+
+    with CloudClient.from_env() as cloud:
+        status = cloud.billing_status()
+        print(status.state, status.balance)
+
+Getting a credential
+--------------------
+
+A control-plane token is not a deployment API token: `umc_dp_…` authenticates
+*memory* calls at a deployment's ingress and is rejected here. Mint one with
+`POST /v1/orgs/<org>/control-tokens` while signed in to the app — there is no
+button for it yet, the API landed before the interface did. Then:
+
+    export REMEMBER_CLOUD_TOKEN='umc_cp_…'
+    export REMEMBER_CLOUD_ORG='your-organisation-id'
+
+The secret is shown once. `remember login` does not yet mint this kind — that
+needs an amendment to the device grant (D40), tracked in D53 §6.
+
+What it deliberately does not do
+--------------------------------
+
+No memory verbs. No second ingest, search, or envelope contract (D35). If you
+want to *use* the memory, use ``rememberstack``; this package tells you what the
+memory costs and whether it is ready.
+"""
+
+from remember.client import CloudClient
+from remember.errors import CloudError
+from remember.errors import NotPermitted
+from remember.errors import RateLimited
+from remember.errors import Unauthenticated
+from remember.models import BillingStatus
+from remember.models import Deployment
+from remember.models import LedgerEntry
+from remember.models import SpendGate
+
+__all__ = [
+    "BillingStatus",
+    "CloudClient",
+    "CloudError",
+    "Deployment",
+    "LedgerEntry",
+    "NotPermitted",
+    "RateLimited",
+    "SpendGate",
+    "Unauthenticated",
+]
+
+__version__ = "0.2.0"

remember/cli.py

@@ -0,0 +1,113 @@
+"""``remember-status`` — one command that answers the operator's question.
+
+Named for what it does, and deliberately **not** ``remember``: that console
+script belongs to ``rememberstack`` alone (D43 rule 3), and two installed
+distributions competing for one name on ``PATH`` is a conflict no user should
+have to debug.
+
+    $ remember-status
+    deployment  active     bb81063d-…dc57d4f1fe87
+    endpoint    live       bb81063d-….dp.remember.dev
+    billing     active     balance 42.10
+    spend       allow
+
+Exit status is meaningful, so a shell can branch: ``0`` ready, ``1`` not ready,
+``2`` could not ask.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+import sys
+
+from remember.client import CloudClient
+from remember.errors import CloudError
+from remember.errors import RateLimited
+from remember.errors import Unauthenticated
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Print one organisation's status; return an exit code a script can use."""
+    parser = argparse.ArgumentParser(
+        prog="remember-status",
+        description=(
+            "Report a remember.dev organisation's deployment, billing, and "
+            "spend state. Reads REMEMBER_CLOUD_TOKEN and REMEMBER_CLOUD_ORG."
+        ),
+    )
+    parser.add_argument("--org", default=None, help="organisation id")
+    parser.add_argument("--url", default=None, help="control-plane base URL")
+    parser.add_argument(
+        "--quiet", action="store_true", help="print nothing; use the exit status only"
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        overrides = {}
+        if args.org:
+            overrides["org_id"] = args.org
+        if args.url:
+            overrides["base_url"] = args.url
+        with CloudClient.from_env(**overrides) as cloud:
+            return _report(cloud=cloud, quiet=bool(args.quiet))
+    except ValueError as error:
+        # Missing configuration: tell the user what to set, not a stack trace.
+        print(f"remember-status: {error}", file=sys.stderr)
+        return 2
+    except Unauthenticated as error:
+        print(
+            f"remember-status: credential rejected ({error}). "
+            "Mint a fresh control-plane token with "
+            "POST /v1/orgs/<org>/control-tokens while signed in.",
+            file=sys.stderr,
+        )
+        return 2
+    except RateLimited as error:
+        wait = f" retry in {error.retry_after:.0f}s" if error.retry_after else ""
+        print(f"remember-status: rate limited{wait}", file=sys.stderr)
+        return 2
+    except CloudError as error:
+        print(f"remember-status: {error}", file=sys.stderr)
+        return 2
+
+
+def _report(*, cloud: CloudClient, quiet: bool) -> int:
+    """Print the four facts worth knowing, and decide the exit code."""
+    deployment = cloud.deployment()
+    billing = cloud.billing_status()
+    gate = None
+    if deployment is not None:
+        gate = cloud.spend_gate(deployment_id=deployment.id)
+
+    if not quiet:
+        if deployment is None:
+            _line("deployment", "none", "no deployment provisioned yet")
+        else:
+            _line("deployment", deployment.state, deployment.id)
+            _line(
+                "endpoint",
+                "live" if deployment.hostname_live else "not serving",
+                deployment.hostname or "unknown",
+            )
+        balance = f"balance {billing.balance}" if billing.balance else ""
+        _line("billing", billing.state, balance)
+        if gate is not None:
+            _line("spend", gate.decision, gate.reason_code or "")
+
+    # Every fact printed above counts toward the exit code. A script that
+    # branches on `remember-status` is asking "can work run right now", and a
+    # zero exit while the spend gate says `park` would send it straight into a
+    # refusal. `is_ready` already covers endpoint liveness as well as state.
+    ready = (
+        deployment is not None
+        and deployment.is_ready
+        and billing.can_spend
+        and (gate is None or gate.allows_work)
+    )
+    return 0 if ready else 1
+
+
+def _line(label: str, state: str, detail: str = "") -> None:
+    """One aligned row, so several runs stack readably in a terminal."""
+    print(f"{label:<11} {state:<10} {detail}".rstrip())

remember/client.py

@@ -0,0 +1,246 @@
+"""The control-plane client.
+
+One class, a handful of read methods, and no memory verbs. Everything it can do
+is what D53's ``status:read`` profile permits — which is deliberate: a credential
+that could do more would be a credential worth stealing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from collections.abc import Mapping
+from contextlib import contextmanager
+import os
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from remember.errors import CloudError
+from remember.errors import NotPermitted
+from remember.errors import RateLimited
+from remember.errors import Unauthenticated
+from remember.models import BillingStatus
+from remember.models import Deployment
+from remember.models import LedgerEntry
+from remember.models import SpendGate
+
+#: Where the managed control plane lives. Overridable for local dogfood.
+DEFAULT_BASE_URL = "https://remember.dev/app/api"
+
+#: Environment variables, named so they cannot be confused with the memory
+#: client's ``REMEMBERSTACK_*`` pair — a machine often holds both.
+TOKEN_ENV = "REMEMBER_CLOUD_TOKEN"
+ORG_ENV = "REMEMBER_CLOUD_ORG"
+BASE_URL_ENV = "REMEMBER_CLOUD_URL"
+
+
+class CloudClient:
+    """Ask the control plane what it knows about one organisation.
+
+    The credential is organisation-bound, so the organisation is fixed for the
+    life of the client rather than passed per call: a control token cannot act
+    on another organisation, and an API that invited you to try would be
+    misleading.
+    """
+
+    def __init__(
+        self,
+        *,
+        token: str,
+        org_id: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        """Bind a credential to one organisation."""
+        if not token:
+            raise ValueError("a control-plane token is required")
+        if not org_id:
+            raise ValueError("an organisation id is required")
+        self._org_id = org_id
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            transport=transport,
+            headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
+        )
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> "CloudClient":
+        """Build from ``REMEMBER_CLOUD_TOKEN`` / ``_ORG`` / ``_URL``.
+
+        The usual shape for an agent: credentials in the environment, nothing in
+        the code.
+        """
+        token = overrides.pop("token", None) or os.getenv(TOKEN_ENV, "")
+        org_id = overrides.pop("org_id", None) or os.getenv(ORG_ENV, "")
+        base_url = (
+            overrides.pop("base_url", None)
+            or os.getenv(BASE_URL_ENV)
+            or DEFAULT_BASE_URL
+        )
+        if not token:
+            raise ValueError(
+                f"set {TOKEN_ENV} to a control-plane token (umc_cp_…). "
+                "Mint one with POST /v1/orgs/<org>/control-tokens while signed "
+                "in; a deployment token (umc_dp_…) is a different credential "
+                "and the control plane rejects it"
+            )
+        if not org_id:
+            raise ValueError(f"set {ORG_ENV} to your organisation id")
+        return cls(token=token, org_id=org_id, base_url=base_url, **overrides)
+
+    @property
+    def org_id(self) -> str:
+        """The organisation this credential is bound to."""
+        return self._org_id
+
+    # -- the questions -------------------------------------------------
+
+    def billing_status(self) -> BillingStatus:
+        """Whether chargeable work may run, and what the balance is."""
+        return BillingStatus.from_payload(
+            self._get(f"/v1/orgs/{self._org_id}/billing/status")
+        )
+
+    def deployments(self) -> list[Deployment]:
+        """Every deployment this organisation has (today, zero or one)."""
+        payload = self._get(f"/v1/orgs/{self._org_id}/deployments")
+        rows = payload if isinstance(payload, list) else payload.get("items", [])
+        return [Deployment.from_payload(row) for row in rows]
+
+    def deployment(self) -> Deployment | None:
+        """The organisation's deployment, or None before one is provisioned."""
+        found = self.deployments()
+        return found[0] if found else None
+
+    def ledger(self, *, limit: int = 50) -> list[LedgerEntry]:
+        """The credit ledger: what was charged, newest first as the server sends.
+
+        ``limit`` is bounded by the server to 1..200; values outside that range
+        are rejected there rather than silently clamped here, so a caller sees
+        its own mistake.
+        """
+        payload = self._get(
+            f"/v1/orgs/{self._org_id}/billing/ledger", params={"limit": limit}
+        )
+        rows = payload if isinstance(payload, list) else payload.get("items", [])
+        return [LedgerEntry.from_payload(row) for row in rows]
+
+    def spend_gate(self, *, deployment_id: str) -> SpendGate:
+        """May work dispatch right now — and if not, why.
+
+        Worth asking before a large ingest: a refusal here is cheaper than a
+        refusal halfway through one.
+        """
+        return SpendGate.from_payload(
+            self._get(
+                f"/v1/orgs/{self._org_id}/deployments/{deployment_id}/spend-safety/gate"
+            )
+        )
+
+    def is_ready(self) -> bool:
+        """One call an agent can branch on: is there a deployment able to serve.
+
+        Convenience over :meth:`deployment`, because "am I ready" is the
+        question actually being asked.
+        """
+        found = self.deployment()
+        return found is not None and found.is_ready
+
+    # -- plumbing ------------------------------------------------------
+
+    def _get(self, path: str, *, params: Mapping[str, Any] | None = None) -> Any:
+        """Perform a read, translating D41 error envelopes into exceptions."""
+        try:
+            response = self._http.get(path, params=params)
+        except httpx.TimeoutException as error:
+            raise CloudError(f"timed out calling {path}", retryable=True) from error
+        except httpx.HTTPError as error:
+            raise CloudError(f"could not reach {path}: {error}") from error
+
+        if response.is_success:
+            return response.json()
+        raise _as_error(response)
+
+    def close(self) -> None:
+        """Release the underlying connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> "CloudClient":
+        """Support ``with CloudClient(...) as cloud:``."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """Close on exit."""
+        self.close()
+
+
+def _as_error(response: httpx.Response) -> CloudError:
+    """Turn a non-success response into the narrowest exception that fits.
+
+    D41's envelope is ``{"detail": {code, message, retryable, request_id}}``. A
+    response that does not carry it — a proxy error page, say — still produces a
+    typed exception, so a caller never has to handle two failure shapes.
+    """
+    code: str | None = None
+    message = f"HTTP {response.status_code}"
+    retryable = False
+    request_id = response.headers.get("X-Request-Id")
+
+    with _tolerating_bad_json():
+        body = response.json()
+        detail = body.get("detail") if isinstance(body, dict) else None
+        if isinstance(detail, dict):
+            code = detail.get("code")
+            message = detail.get("message") or message
+            retryable = bool(detail.get("retryable", False))
+            request_id = detail.get("request_id") or request_id
+        elif isinstance(detail, str):
+            # Pre-D41 routes still answer with a bare string.
+            message = detail
+
+    shared = {
+        "status_code": response.status_code,
+        "code": code,
+        "retryable": retryable,
+        "request_id": request_id,
+    }
+    if response.status_code == 401:
+        return Unauthenticated(message, **shared)  # type: ignore[arg-type]
+    if response.status_code == 403:
+        return NotPermitted(message, **shared)  # type: ignore[arg-type]
+    if response.status_code == 429:
+        return RateLimited(
+            message,
+            retry_after=_retry_after(response),
+            **shared,  # type: ignore[arg-type]
+        )
+    return CloudError(message, **shared)  # type: ignore[arg-type]
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    """Seconds from ``Retry-After``, when the server sent a usable one."""
+    raw = response.headers.get("Retry-After")
+    if not raw:
+        return None
+    try:
+        return float(raw)
+    except ValueError:
+        # HTTP-date form; the caller's own backoff is better than a bad guess.
+        return None
+
+
+@contextmanager
+def _tolerating_bad_json() -> Iterator[None]:
+    """Ignore an unparseable error body rather than masking the real failure."""
+    try:
+        yield
+    except (ValueError, AttributeError):
+        return

remember/errors.py

@@ -0,0 +1,76 @@
+"""Failures a control-plane call can produce, typed so a caller can branch.
+
+D41 binds one error envelope for machine traffic:
+
+    {"detail": {"code": …, "message": …, "retryable": bool, "request_id": …}}
+
+Clients branch on ``code``, never on ``message`` — the message is operator-safe
+prose and explicitly non-authoritative. These exceptions carry the code through
+so a caller can do the same, and expose ``retryable`` rather than making every
+caller re-derive it from a status number.
+"""
+
+from __future__ import annotations
+
+
+class CloudError(Exception):
+    """Base for every control-plane failure.
+
+    Carries the D41 envelope fields when the server sent them. A response that
+    is not shaped like the envelope still produces one of these — with
+    ``code=None`` — so a caller never has to handle two failure shapes.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+        retryable: bool = False,
+        request_id: str | None = None,
+    ) -> None:
+        """Bind the envelope fields that were present."""
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.retryable = retryable
+        self.request_id = request_id
+
+    def __str__(self) -> str:
+        """Include the request id, because support will ask for it."""
+        base = super().__str__()
+        return f"{base} (request_id={self.request_id})" if self.request_id else base
+
+
+class Unauthenticated(CloudError):
+    """No credential, or one the server will not accept (401).
+
+    Also raised for a revoked or expired credential, and for one whose
+    membership has ended — from a client's point of view these are the same
+    situation: sign in again and mint a fresh credential.
+    """
+
+
+class NotPermitted(CloudError):
+    """Authenticated, but this credential may not do this (403).
+
+    Distinct from :class:`Unauthenticated` because retrying will not help and a
+    fresh credential of the same profile will not either — the profile itself
+    does not permit the call, or the credential belongs to a different
+    organisation.
+    """
+
+
+class RateLimited(CloudError):
+    """Admission refused the call (429).
+
+    ``retry_after`` is the server's own advice in seconds when it gave any.
+    """
+
+    def __init__(
+        self, message: str, *, retry_after: float | None = None, **kwargs: object
+    ) -> None:
+        """Bind the retry hint alongside the envelope fields."""
+        super().__init__(message, **kwargs)  # type: ignore[arg-type]
+        self.retry_after = retry_after

remember/models.py

@@ -0,0 +1,211 @@
+"""What the control plane returns, narrowed to what a caller needs.
+
+These are deliberately *not* generated from OpenAPI. The generated client is the
+browser app's contract and changes with it; a published wheel needs a surface
+that stays still. So each model takes the fields this package promises and
+ignores the rest, and an added server field is a non-event rather than a
+breakage.
+
+Unknown enum-ish values are kept as strings for the same reason: a new
+deployment state should print, not raise.
+
+**The field names here are a contract with the server, not a convention.** They
+were wrong once — this client read ``balance`` and compared the billing state to
+lowercase ``"active"``, while the control plane sends ``balance_credits`` and
+``ACTIVE`` — and every test passed, because the tests asserted the same invented
+shape. ``src/tests/test_remember_client_contract.py`` now feeds real server
+response models through these parsers, so the next such drift fails in CI
+instead of in a user's terminal.
+
+Two conventions in the API this file has to absorb, rather than pass on:
+
+* the two state enums disagree about case. ``DeploymentState`` is lowercase
+  (``active``); ``BillingState`` is uppercase (``ACTIVE``). Comparisons here are
+  case-insensitive so a caller never has to know which is which.
+* money arrives as a JSON string (Pydantic renders ``Decimal`` that way) and
+  stays a string here. It is displayed and compared, never arithmetic'd by this
+  client, and ``float`` would be the wrong type for money.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+
+def _text(payload: Mapping[str, Any], key: str) -> str | None:
+    """A string field, or None when absent or empty."""
+    value = payload.get(key)
+    return value if isinstance(value, str) and value else None
+
+
+def _money(payload: Mapping[str, Any], *keys: str) -> str | None:
+    """A decimal amount as a string, from the first key that carries one.
+
+    Accepts a JSON number as well as a string: the server renders ``Decimal`` as
+    a string today, and a client that broke if that changed would be brittle for
+    no benefit. Several keys may be given where the API has a preferred field
+    and a deprecated alias.
+    """
+    for key in keys:
+        value = payload.get(key)
+        if isinstance(value, str) and value:
+            return value
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return str(value)
+    return None
+
+
+def _moment(payload: Mapping[str, Any], key: str) -> datetime | None:
+    """An ISO-8601 timestamp, or None when absent or unparseable."""
+    raw = _text(payload, key)
+    if raw is None:
+        return None
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+@dataclass(frozen=True)
+class Deployment:
+    """One deployment's identity and where a client reaches it."""
+
+    id: str
+    state: str
+    hostname: str | None
+    hostname_live: bool
+    created_at: datetime | None
+
+    @property
+    def is_ready(self) -> bool:
+        """True when this deployment can actually be reached.
+
+        Both halves are required. ``state == "active"`` is the control plane's
+        view of provisioning, but the hostname is a *designed* public name that
+        does not resolve to a serving process until the live flag says so
+        (D33) — so an active deployment whose flag is false would hand a caller
+        an endpoint that refuses connections.
+
+        The engine's own readiness — whether the memory is warm — is a separate
+        question, asked through ``rememberstack``.
+        """
+        return self.state.lower() == "active" and self.hostname_live
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> Deployment:
+        """Narrow a deployment response."""
+        return cls(
+            id=_text(payload, "id") or "",
+            state=_text(payload, "state") or "unknown",
+            hostname=_text(payload, "data_plane_hostname"),
+            hostname_live=bool(payload.get("data_plane_hostname_live", False)),
+            created_at=_moment(payload, "created_at"),
+        )
+
+
+@dataclass(frozen=True)
+class BillingStatus:
+    """Whether this organisation may incur chargeable work, and what it has."""
+
+    state: str
+    balance: str | None
+    cap: str | None
+
+    @property
+    def can_spend(self) -> bool:
+        """True when billing is in a state that permits chargeable work.
+
+        Case-insensitive: ``BillingState`` sends ``ACTIVE``, and a caller
+        should not have to know that.
+        """
+        return self.state.upper() == "ACTIVE"
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> BillingStatus:
+        """Narrow a billing-status response (``CommercialStatusResponse``)."""
+        return cls(
+            state=_text(payload, "billing_state") or "unknown",
+            balance=_money(payload, "balance_credits"),
+            cap=_money(payload, "monthly_cap_credits"),
+        )
+
+
+@dataclass(frozen=True)
+class SpendGate:
+    """The pre-dispatch decision: may work run right now, and if not, why.
+
+    This is the question an agent should ask before a large ingest, and the one
+    that explains a refusal after the fact.
+    """
+
+    decision: str
+    reason_code: str | None
+    spent_usd: str | None
+    ceiling_usd: str | None
+    parked: bool
+
+    @property
+    def allows_work(self) -> bool:
+        """True when the gate currently permits dispatch."""
+        return self.decision.lower() == "allow"
+
+    @property
+    def is_parked(self) -> bool:
+        """True when work is paused rather than refused.
+
+        Parked is recoverable — a cap raise or an operator action releases it —
+        where refused means the request will not succeed as sent.
+
+        Taken from the server's own ``is_parked`` flag rather than inferred from
+        the decision: a policy can be parked while the decision reads something
+        else, and the server is the authority on which.
+        """
+        return self.parked
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> SpendGate:
+        """Narrow a spend-gate response (``DispatchGateResponse``)."""
+        decision = _text(payload, "decision") or "unknown"
+        return cls(
+            decision=decision,
+            reason_code=_text(payload, "reason_code"),
+            # ``spent_usd`` is the server's deprecated alias for
+            # ``estimate_spent_usd``; prefer the current name, accept the old.
+            spent_usd=_money(payload, "estimate_spent_usd", "spent_usd"),
+            ceiling_usd=_money(payload, "ceiling_usd"),
+            parked=bool(payload.get("is_parked", decision.lower() == "park")),
+        )
+
+
+@dataclass(frozen=True)
+class LedgerEntry:
+    """One append-only credit-ledger line: what was charged, and what remained.
+
+    The ledger answers "what did that cost me", which D43 expects this
+    distribution to be able to show alongside status and balance.
+    """
+
+    entry_id: str
+    position: int | None
+    entry_type: str
+    amount: str | None
+    balance_after: str | None
+    description: str | None
+    created_at: datetime | None
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> LedgerEntry:
+        """Narrow a ledger entry (``LedgerEntryResponse``)."""
+        position = payload.get("ledger_position")
+        return cls(
+            entry_id=_text(payload, "credit_entry_id") or "",
+            position=position if isinstance(position, int) else None,
+            entry_type=_text(payload, "entry_type") or "unknown",
+            amount=_money(payload, "amount"),
+            balance_after=_money(payload, "balance_after"),
+            description=_text(payload, "description"),
+            created_at=_moment(payload, "created_at"),
+        )

remember-0.2.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.5
+Name: remember
+Version: 0.2.0
+Summary: Control-plane client for the remember.dev managed memory service.
+Project-URL: Homepage, https://remember.dev
+Project-URL: Documentation, https://remember.dev/docs
+Project-URL: Source, https://github.com/writeitai/ultimate-memory-cloud
+Author-email: "WriteIt.ai s.r.o." <info@writeit.ai>
+License: Apache-2.0
+Keywords: agents,memory,remember.dev,rememberstack
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: rememberstack>=0.8.1
+Description-Content-Type: text/markdown
+
+# remember
+
+Control-plane client for the [remember.dev](https://remember.dev) managed memory service.
+
+`rememberstack` answers *memory* questions — ingest a document, search claims, run an assured
+operation. This package answers the questions an operator of that memory also has:
+
+- is my deployment ready?
+- what is my balance, and what did that ingest cost?
+- has spend safety parked my work?
+
+```python
+from remember import CloudClient
+
+with CloudClient.from_env() as cloud:
+    if cloud.is_ready():
+        print(cloud.billing_status().balance)
+```
+
+```console
+$ remember-status
+deployment  active     bb81063d-6b7b-41d0-a1df-dc57d4f1fe87
+endpoint    live       bb81063d-6b7b-41d0-a1df-dc57d4f1fe87.dp.remember.dev
+billing     active     balance 42.10
+spend       allow
+```
+
+## Install
+
+```console
+pip install remember
+```
+
+This installs `rememberstack` too. The `remember` **command** comes from that package and is
+unaffected by this one; this distribution adds only `remember-status`.
+
+## Credentials
+
+This client authenticates with a **control-plane token** (`umc_cp_…`) — the D53 credential kind.
+It is not the same thing as a deployment API token (`umc_dp_…`): that one authenticates *memory*
+calls at the deployment's ingress and will be rejected here.
+
+Mint one with `POST /v1/orgs/<org>/control-tokens` while signed in to the app. There is no button
+for this yet — the API landed before the interface did — so today it is a call, not a click:
+
+```console
+export REMEMBER_CLOUD_TOKEN='umc_cp_…'
+export REMEMBER_CLOUD_ORG='your-organisation-id'
+```
+
+The secret is shown once. The credential is organisation-scoped, **read-only**, expires (90 days by
+default), and can be surrendered by its holder at any time.
+
+## What it will not do
+
+No memory verbs, no second ingest or search contract. To *use* the memory, use `rememberstack`
+pointed at your deployment; this package tells you what that memory costs and whether it is ready.

remember-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+remember/__init__.py,sha256=v6mMsS-pndNfiQ6PyNI5miatwCMoCiwBQoYoEpGuorU,2617
+remember/cli.py,sha256=ccGGEPce5J382n3MnzHlGIjW9TBBmYfm1gXhjYUo-lc,4266
+remember/client.py,sha256=N9BcXCsgGTuKt-Rqhgw_CZtgxKk6fquL5cp8PJy1Ds8,9050
+remember/errors.py,sha256=r9NqkeuGG8FCKk8w7jpxzGNsov0geGXj0kYdI7xz4pg,2643
+remember/models.py,sha256=x977fyTNdcmwRathe0w5phXOAzBVx8DnlTFjSXHaJSk,7928
+remember/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+remember-0.2.0.dist-info/METADATA,sha256=RP_T6cIRI3TZ22bi0Du-kc9xpCOzJWGsaBh-BE_94bE,2768
+remember-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+remember-0.2.0.dist-info/entry_points.txt,sha256=DscNeNcF7FdWiAJMO-PUEPErgrBVnNZMbqkaZjXiBQM,54
+remember-0.2.0.dist-info/RECORD,,

remember-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

remember-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+remember-status = remember.cli:main