remember 0.1__tar.gz → 0.2.0__tar.gz

remember-0.2.0/.gitignore

@@ -0,0 +1,68 @@
+.loopy_loop/sessions/
+.loopy_loop/traces/
+.loopy_loop/trace_finalization_outbox/
+.loopy_loop/repository.json
+.loopy_loop/state.json
+.loopy_loop/state.json.lock
+.loopy_loop/state.json.archive_*.json
+
+# Disposable external research checkouts (never vendored)
+.research/
+
+# Python environments and generated caches
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+
+# IDE state
+.idea/
+
+# Cloudflare edge local secrets (never commit tokens)
+ops/cloudflare_edge/config.local.toml
+infra/benchmark-host/config.local.toml
+infra/disposable-dp-host/config.local.toml
+
+# Frontend install/build artifacts (source lives in fe/)
+fe/node_modules/
+fe/.next/
+fe/out/
+fe/*.tsbuildinfo
+fe/.pages-deploy.digest
+fe/.agent-browser-shots/
+fe/.pen-exports/
+
+# Observability host — secret-bearing / generated deploy artifacts (never commit)
+infra/obs/.env
+infra/obs/purge/purge.env
+infra/obs/purge/projects.env
+infra/obs/vmauth.rendered.yaml
+infra/obs/Caddyfile.rendered
+infra/obs/certs/
+
+# Generic secret / rendered shapes (F2 hygiene)
+*.pem
+.env
+*.env
+!*.env.example
+!infra/obs/.env.example
+*.rendered.yaml
+Caddyfile.rendered
+**/umcobs0.conf
+
+
+fe/storybook-static/
+infra/benchmark-host/config.beam.local.toml
+
+# fe_admin (D34)
+fe_admin/node_modules/
+fe_admin/out/
+fe_admin/.next/
+fe_admin/.agent-browser-shots/
+fe_admin/storybook-static/
+.dual-review/
+
+# Built client distributions (published via the release workflow, never committed).
+client/dist/
+client/.venv/

remember-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,57 @@
+# 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/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "remember"
+version = "0.2.0"
+description = "Control-plane client for the remember.dev managed memory service."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "Apache-2.0" }
+authors = [{ name = "WriteIt.ai s.r.o.", email = "info@writeit.ai" }]
+keywords = ["remember.dev", "rememberstack", "memory", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+# D43 rule 1: the cloud distribution may depend on the memory client; never the
+# reverse. The memory verbs stay in rememberstack — this package adds only the
+# control-plane questions that engine has no business answering.
+dependencies = [
+    "httpx>=0.27",
+    "rememberstack>=0.8.1",
+]
+
+[project.urls]
+Homepage = "https://remember.dev"
+Documentation = "https://remember.dev/docs"
+Source = "https://github.com/writeitai/ultimate-memory-cloud"
+
+# D43 rule 3: this project declares NO console script named `remember`. That
+# entry point belongs to `rememberstack` alone, and colliding on it would be a
+# PATH conflict between two installed distributions.
+[project.scripts]
+remember-status = "remember.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/remember"]
+
+# The client's tests are their own suite: the repository's root pytest run is
+# scoped to ``src/tests`` and never collects them. Declaring the section here
+# also makes ``client`` pytest's rootdir, so a run does not inherit the service's
+# asyncio settings.
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = ["pytest>=8.3", "respx>=0.21", "mypy>=1.14", "ruff>=0.9"]

remember-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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