membase-sdk 0.1.0__py3-none-any.whl

membase/__init__.py

@@ -0,0 +1,40 @@
+"""Membase — your memory, from code. ``pip install membase-sdk``.
+
+from membase import Membase
+client = Membase()  # MEMBASE_API_KEY
+"""
+
+from ._version import __version__
+from .client import DEFAULT_BASE_URL, Membase
+from .errors import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    MembaseError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnprocessableEntityError,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "Membase",
+    "MembaseError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+    "__version__",
+]

membase/_version.py

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

membase/client.py

@@ -0,0 +1,247 @@
+"""The Membase client: one developer key, the account's memory.
+
+    from membase import Membase
+
+    client = Membase()                       # MEMBASE_API_KEY, optional MEMBASE_BASE_URL
+    client.add("Call notes …", container="mv-…", custom_id="call-1")
+    client.search("what did we decide about the ledger")
+    client.profile(q="working hours")
+
+Every method is one operation of the agent protocol (the REST namespace under
+``https://api.app.membase.io/v1``); the access level, reach and confirmation rules are enforced
+server-side, so nothing here can do what the key cannot.
+"""
+
+from __future__ import annotations
+
+import os
+import random
+import time
+from typing import Any
+
+import httpx
+
+from ._version import __version__
+from .errors import APIConnectionError, APITimeoutError, error_for
+
+DEFAULT_BASE_URL = "https://api.app.membase.io"
+#: A search is a turn inside the user's memory; the first one after a quiet spell can take up
+#: to a minute while the memory wakes, so the default is generous.
+DEFAULT_TIMEOUT = 90.0
+DEFAULT_MAX_RETRIES = 2
+_RETRY_STATUSES = {408, 409, 429}
+
+
+class Membase:
+    """The client. Thread-safe for reads; one instance per process is fine."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | None = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        api_key = api_key if api_key is not None else os.environ.get("MEMBASE_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "no API key: pass api_key= or set MEMBASE_API_KEY "
+                "(Connect › Developer keys in the Membase app)"
+            )
+        self.api_key = api_key
+        self.base_url = (base_url or os.environ.get("MEMBASE_BASE_URL") or DEFAULT_BASE_URL).rstrip(
+            "/"
+        )
+        self.max_retries = max(0, int(max_retries))
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(base_url=self.base_url, timeout=timeout)
+        self.containers = _Containers(self)
+        self.documents = _Documents(self)
+        self.memories = _Memories(self)
+
+    # -- the four verbs most code needs ---------------------------------------------------
+
+    def add(
+        self,
+        content: str | None = None,
+        *,
+        container: str,
+        url: str | None = None,
+        title: str = "",
+        metadata: dict | None = None,
+        custom_id: str = "",
+    ) -> dict:
+        """Hand a document (its text, or a public ``url`` to fetch) to a container. Returns at
+        once with ``status: queued`` and a ``document_id``; the container learns it in the
+        background — ``documents.get(id)["learned"]`` turns true when it has. The same
+        ``custom_id`` again is a no-op, so retries are safe."""
+        body: dict[str, Any] = {"container": container, "title": title, "custom_id": custom_id}
+        if content is not None:
+            body["content"] = content
+        if url is not None:
+            body["url"] = url
+        if metadata is not None:
+            body["metadata"] = metadata
+        return self._request("POST", "/v1/documents", json=body)
+
+    def search(self, q: str, *, container: str | None = None, limit: int | None = None) -> dict:
+        """Passages the containers hold on ``q``, most relevant first, each naming its
+        container. ``container`` omitted searches every container in reach. Retrieval, not an
+        answer — ``ask`` is the agent's answer. ``containers[]`` in the result marks any
+        container that could not answer yet (still waking)."""
+        body: dict[str, Any] = {"q": q}
+        if container is not None:
+            body["container"] = container
+        if limit is not None:
+            body["limit"] = limit
+        return self._request("POST", "/v1/search", json=body)
+
+    def profile(self, q: str | None = None) -> dict:
+        """Who the user is: ``static`` (standing facts), ``dynamic`` (the most recently
+        changed facts) and, with ``q``, ``results`` relevant to the topic. Needs a key minted
+        with the profile tick."""
+        return self._request("GET", "/v1/profile", params={"q": q} if q else None)
+
+    def ask(self, message: str, *, model: str | None = None) -> dict:
+        """The exposed agent's answer to ``message`` (an agent-endpoint credential)."""
+        body: dict[str, Any] = {"message": message}
+        if model is not None:
+            body["model"] = model
+        return self._request("POST", "/v1/ask", json=body)
+
+    def rules(self) -> dict:
+        """The user's standing rules for how their memory is used by this credential."""
+        return self._request("GET", "/v1/rules")
+
+    # -- plumbing -------------------------------------------------------------------------
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> Membase:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict | None = None,
+        params: dict | None = None,
+    ) -> Any:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"membase-sdk-python/{__version__}",
+        }
+        attempt = 0
+        while True:
+            try:
+                r = self._http.request(method, path, json=json, params=params, headers=headers)
+            except httpx.TimeoutException as e:
+                if attempt < self.max_retries:
+                    attempt += 1
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise APITimeoutError(f"{method} {path} timed out") from e
+            except httpx.HTTPError as e:
+                if attempt < self.max_retries:
+                    attempt += 1
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise APIConnectionError(f"{method} {path}: {e}") from e
+            if 200 <= r.status_code < 300:
+                return r.json() if r.content else None
+            if (
+                r.status_code in _RETRY_STATUSES or r.status_code >= 500
+            ) and attempt < self.max_retries:
+                attempt += 1
+                time.sleep(_backoff(attempt, r.headers.get("Retry-After")))
+                continue
+            try:
+                body = r.json()
+            except ValueError:
+                body = {"error": {"message": r.text}}
+            raise error_for(r.status_code, body)
+
+
+def _backoff(attempt: int, retry_after: str | None = None) -> float:
+    if retry_after:
+        try:
+            return min(float(retry_after), 30.0)
+        except ValueError:
+            pass
+    return min(0.5 * (2 ** (attempt - 1)), 8.0) * (0.5 + random.random())
+
+
+class _Containers:
+    def __init__(self, client: Membase) -> None:
+        self._c = client
+
+    def list(self) -> dict:
+        """The containers this key may use — every one, for the account's owner."""
+        return self._c._request("GET", "/v1/containers")
+
+
+class _Documents:
+    def __init__(self, client: Membase) -> None:
+        self._c = client
+
+    def list(self, *, container: str | None = None) -> dict:
+        """The documents the containers in reach have read, newest first, each with
+        ``learned``."""
+        return self._c._request(
+            "GET", "/v1/documents", params={"container": container} if container else None
+        )
+
+    def get(self, document_id: str) -> dict:
+        """One document, with whether its container has learned it yet."""
+        return self._c._request("GET", f"/v1/documents/{document_id}")
+
+    def delete(self, document_id: str, *, confirm: bool = False) -> dict:
+        """Remove one document everywhere (the file goes to the Files trash). Needs Full
+        access and ``confirm=True``; without it the answer is ``status:
+        confirmation_required`` with a ``how`` sentence to relay, not an error."""
+        return self._c._request(
+            "DELETE", f"/v1/documents/{document_id}", params={"confirm": _flag(confirm)}
+        )
+
+
+class _Memories:
+    def __init__(self, client: Membase) -> None:
+        self._c = client
+
+    def add(
+        self,
+        content: str,
+        *,
+        container: str | None = None,
+        static: bool = False,
+        title: str = "",
+    ) -> dict:
+        """Save one fact. ``static=True`` is a standing fact about the user and goes to their
+        profile; otherwise a note the container reads. ``container`` may be omitted when
+        exactly one is in reach."""
+        body: dict[str, Any] = {"content": content, "static": static, "title": title}
+        if container is not None:
+            body["container"] = container
+        return self._c._request("POST", "/v1/memories", json=body)
+
+    def forget(
+        self, memory_id: str, *, container: str | None = None, confirm: bool = False
+    ) -> dict:
+        """Forget one learned fact. Same confirmation rule as ``documents.delete``."""
+        params: dict[str, Any] = {"confirm": _flag(confirm)}
+        if container is not None:
+            params["container"] = container
+        return self._c._request("DELETE", f"/v1/memories/{memory_id}", params=params)
+
+
+def _flag(v: bool) -> str:
+    return "true" if v else "false"

membase/errors.py

@@ -0,0 +1,106 @@
+"""Errors, one class per HTTP status class, all carrying the platform's error envelope.
+
+The API answers every failure as ``{"error": {"code", "message", "details", "retryable",
+"trace_id"}}``. The status decides the class (so a caller can ``except RateLimitError``), the
+``code`` says which rule refused (``unauthorized`` for a container outside the key's reach,
+``capability_unavailable`` when the account's memory cannot run a turn, …), and ``trace_id`` is
+what to quote when reporting a problem.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class MembaseError(Exception):
+    """Base class of everything this package raises."""
+
+    def __init__(self, message: str, *, status: int | None = None, body: Any = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.body = body
+        err = body.get("error") if isinstance(body, dict) else None
+        err = err if isinstance(err, dict) else {}
+        self.code: str = str(err.get("code") or "")
+        self.details: Any = err.get("details")
+        self.retryable: bool = bool(err.get("retryable", False))
+        self.trace_id: str = str(err.get("trace_id") or "")
+
+    def __str__(self) -> str:  # pragma: no cover - formatting
+        bits = [self.message]
+        if self.status is not None:
+            bits.append(f"[{self.status}{' ' + self.code if self.code else ''}]")
+        if self.trace_id:
+            bits.append(f"trace_id={self.trace_id}")
+        return " ".join(bits)
+
+
+class APIConnectionError(MembaseError):
+    """The request never got an answer (DNS, connection refused, reset)."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The request ran past the client's timeout."""
+
+
+class APIStatusError(MembaseError):
+    """A non-2xx answer. Subclasses per status class below."""
+
+
+class BadRequestError(APIStatusError):
+    """400 — a malformed request: a missing ``q``, both ``content`` and ``url``, an ambiguous
+    ``container``."""
+
+
+class AuthenticationError(APIStatusError):
+    """401 — the request carried no bearer at all."""
+
+
+class PermissionDeniedError(APIStatusError):
+    """403 (``code: unauthorized``) — an unknown, expired or revoked key; a container outside
+    the key's reach; or a verb above its access level. Rotate the key, switch the memory on under
+    Reach on the key's page, or mint a key at a higher level."""
+
+
+class NotFoundError(APIStatusError):
+    """404 — an unknown document or memory id."""
+
+
+class ConflictError(APIStatusError):
+    """409."""
+
+
+class UnprocessableEntityError(APIStatusError):
+    """422 — the account's memory cannot run a turn on this deployment (``capability_unavailable``:
+    no agent container, no model), or a body FastAPI could not parse."""
+
+
+class RateLimitError(APIStatusError):
+    """429 — the account's turn budget is spent for now. Retried automatically; retry later."""
+
+
+class InternalServerError(APIStatusError):
+    """5xx."""
+
+
+_BY_STATUS: dict[int, type[APIStatusError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+}
+
+
+def error_for(status: int, body: Any, fallback: str = "") -> APIStatusError:
+    """The exception for a non-2xx answer."""
+    err = body.get("error") if isinstance(body, dict) else None
+    message = (err or {}).get("message") if isinstance(err, dict) else None
+    if not message and isinstance(body, dict) and body.get("detail"):
+        message = str(body["detail"])  # FastAPI's own 422 shape
+    message = message or fallback or f"HTTP {status}"
+    cls = _BY_STATUS.get(status) or (InternalServerError if status >= 500 else APIStatusError)
+    return cls(message, status=status, body=body)

membase_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: membase-sdk
+Version: 0.1.0
+Summary: Membase — your memory, from code. The official Python client for the Membase API.
+Author: Unibase
+License: MIT
+Project-URL: Homepage, https://www.app.membase.io
+Project-URL: Documentation, https://www.app.membase.io/skill
+Keywords: membase,memory,ai,agents,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.25
+
+# membase-sdk
+
+Your memory, from code. The official Python client for the [Membase](https://www.app.membase.io) API.
+
+```bash
+pip install membase-sdk
+export MEMBASE_API_KEY="mbk_…"     # Connect › Developer keys in the Membase app
+```
+
+```python
+from membase import Membase
+
+client = Membase()
+
+client.add("Call notes with Acme: they want SSO before the pilot.", container="mv-…", custom_id="call-2026-09-24")
+hits = client.search("what does Acme need before the pilot", limit=5)
+print(hits["results"][0]["content"])
+
+client.profile(q="working hours")           # who the user is (needs the profile tick on the key)
+client.containers.list()
+client.documents.list(container="mv-…")
+client.memories.add("The user prefers dark mode.", static=True)
+client.documents.delete("srcitem_…", confirm=True)   # Full access; confirm means the person agreed
+```
+
+Every method is one operation of the Membase agent protocol; access level, reach and confirmation
+rules are enforced server-side. Errors are one class per HTTP status (`PermissionDeniedError`,
+`RateLimitError`, …) and carry the API's `code` and `trace_id`. 429 and 5xx answers are retried
+twice with backoff; the default timeout is 90 s, because the first search after a quiet spell
+waits for the user's memory to wake.
+
+Docs: the developer documentation's *SDK Quickstart*. Works against a self-hosted Membase too:
+`Membase(base_url="http://localhost:8080")`.

membase_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+membase/__init__.py,sha256=XiUTUyFFbYimefhiWIyw0-RQXSV7NP1KKmDovuz_vt4,879
+membase/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+membase/client.py,sha256=0UX983LKUL6EDyJGd25xf_9G7QjEVblELHuFJYLWGek,9496
+membase/errors.py,sha256=nMEk_oBR8ctOucT_aufJtXBV2MNfL5UPez6pryEUNd4,3831
+membase/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+membase_sdk-0.1.0.dist-info/METADATA,sha256=5nDUjkZZvVaBnG6ksfsulqNcnxrWM8FrfZTX9kgF0i8,2075
+membase_sdk-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+membase_sdk-0.1.0.dist-info/top_level.txt,sha256=oerSw-WxE1-6RSn8wevBEM4W2vE83HLzciSxIfMGYhQ,8
+membase_sdk-0.1.0.dist-info/RECORD,,

membase_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

membase_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+membase