databaset 0.1.0__py3-none-any.whl

databaset/__init__.py

@@ -0,0 +1,7 @@
+"""Databaset Python SDK — AI memory store, recall, and forget."""
+
+from databaset.errors import ApiError, DatabasetError, ValidationError
+from databaset.memory import Memory
+
+__all__ = ["Memory", "DatabasetError", "ValidationError", "ApiError"]
+__version__ = "0.1.0"

databaset/client.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from databaset.errors import ApiError, DatabasetError
+
+DEFAULT_BASE_URL = "https://api.databaset.com"
+API_KEY_PREFIX = "db_"
+
+
+class DatabasetClient:
+  def __init__(
+    self,
+    api_key: str,
+    *,
+    base_url: str | None = None,
+    timeout: float = 30.0,
+  ):
+    self.api_key = _assert_api_key(api_key)
+    self.base_url = _normalize_base_url(base_url or os.environ.get("DATABASET_API_URL") or DEFAULT_BASE_URL)
+    self.timeout = timeout
+
+  def request(
+    self,
+    method: str,
+    path: str,
+    *,
+    json_body: dict[str, Any] | None = None,
+    params: dict[str, Any] | None = None,
+  ) -> dict[str, Any]:
+    url = f"{self.base_url}{path}"
+    if params:
+      filtered = {k: v for k, v in params.items() if v is not None and v != ""}
+      if filtered:
+        url = f"{url}?{urllib.parse.urlencode(filtered)}"
+
+    data = None
+    headers = {
+      "Authorization": f"Bearer {self.api_key}",
+      "Accept": "application/json",
+    }
+    if json_body is not None:
+      data = json.dumps(json_body).encode("utf-8")
+      headers["Content-Type"] = "application/json"
+
+    req = urllib.request.Request(url, data=data, headers=headers, method=method.upper())
+
+    try:
+      with urllib.request.urlopen(req, timeout=self.timeout) as res:
+        raw = res.read().decode("utf-8")
+        if not raw:
+          return {}
+        return json.loads(raw)
+    except urllib.error.HTTPError as e:
+      raw = e.read().decode("utf-8", errors="replace")
+      body: dict[str, Any] = {}
+      if raw:
+        try:
+          body = json.loads(raw)
+        except json.JSONDecodeError:
+          body = {"raw": raw}
+      message = body.get("error") or body.get("message") or f"HTTP {e.code}"
+      raise ApiError(message, status=e.code, code=body.get("code"), body=body) from e
+    except urllib.error.URLError as e:
+      raise DatabasetError(
+        f"Network error — is the API running at {self.base_url}? ({e.reason})"
+      ) from e
+    except json.JSONDecodeError as e:
+      raise DatabasetError("Invalid JSON response from API") from e
+
+
+def _normalize_base_url(base_url: str) -> str:
+  if not base_url or not base_url.strip():
+    raise DatabasetError("base_url must be a non-empty string")
+  return base_url.rstrip("/")
+
+
+def _assert_api_key(api_key: str) -> str:
+  if not api_key or not str(api_key).strip():
+    raise DatabasetError("api_key is required (or set DATABASET_API_KEY)")
+  key = str(api_key).strip()
+  if not key.startswith(API_KEY_PREFIX):
+    raise DatabasetError(f'api_key must start with "{API_KEY_PREFIX}"')
+  return key

databaset/errors.py

@@ -0,0 +1,15 @@
+class DatabasetError(Exception):
+  def __init__(self, message: str, *, status: int | None = None, code: str | None = None, body=None):
+    super().__init__(message)
+    self.status = status
+    self.code = code
+    self.body = body
+
+
+class ValidationError(DatabasetError):
+  def __init__(self, message: str):
+    super().__init__(message, code="validation_error")
+
+
+class ApiError(DatabasetError):
+  pass

databaset/memory.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from databaset.client import DatabasetClient
+from databaset.errors import ValidationError
+
+
+def _require(value: Any, field: str) -> str:
+  if value is None or str(value).strip() == "":
+    raise ValidationError(f"{field} is required")
+  return str(value).strip()
+
+
+def _clamp_int(value: Any, min_v: int, max_v: int, default: int) -> int:
+  try:
+    n = int(value)
+  except (TypeError, ValueError):
+    return default
+  return max(min_v, min(max_v, n))
+
+
+def _clamp_float(value: Any, min_v: float, max_v: float, default: float) -> float:
+  try:
+    n = float(value)
+  except (TypeError, ValueError):
+    return default
+  return max(min_v, min(max_v, n))
+
+
+class Memory:
+  def __init__(
+    self,
+    api_key: str | None = None,
+    *,
+    base_url: str | None = None,
+    app_id: str | None = None,
+    timeout: float = 30.0,
+    client: DatabasetClient | None = None,
+  ):
+    key = api_key or os.environ.get("DATABASET_API_KEY")
+    self.default_app_id = app_id
+    self.client = client or DatabasetClient(key, base_url=base_url, timeout=timeout)
+
+  def store(
+    self,
+    user_id: str,
+    text: str,
+    *,
+    app_id: str | None = None,
+    metadata: dict[str, Any] | None = None,
+  ) -> dict[str, Any]:
+    uid = _require(user_id, "user_id")
+    content = _require(text, "text")
+    body: dict[str, Any] = {"userId": uid, "text": content}
+    resolved_app = app_id or self.default_app_id
+    if resolved_app:
+      body["appId"] = resolved_app
+    if metadata is not None:
+      if not isinstance(metadata, dict):
+        raise ValidationError("metadata must be a dict")
+      body["metadata"] = metadata
+    return self.client.request("POST", "/v1/memories", json_body=body)
+
+  def recall(
+    self,
+    user_id: str,
+    query: str,
+    *,
+    app_id: str | None = None,
+    limit: int | None = None,
+    min_score: float | None = None,
+    format: str = "string",
+  ) -> str | list[dict[str, Any]]:
+    uid = _require(user_id, "user_id")
+    q = _require(query, "query")
+    result = self.client.request(
+      "GET",
+      "/v1/memories/recall",
+      params={
+        "userId": uid,
+        "query": q,
+        "appId": app_id or self.default_app_id,
+        "limit": _clamp_int(limit, 1, 100, 5),
+        "minScore": _clamp_float(min_score, 0.0, 1.0, 0.7),
+        "format": format,
+      },
+    )
+    if format == "array":
+      return result.get("memories") or []
+    return result.get("context") or ""
+
+  def recall_raw(self, user_id: str, query: str, **kwargs: Any) -> list[dict[str, Any]]:
+    out = self.recall(user_id, query, format="array", **kwargs)
+    return out if isinstance(out, list) else []
+
+  def list(
+    self,
+    user_id: str,
+    *,
+    app_id: str | None = None,
+    page: int | None = None,
+    page_size: int | None = None,
+  ) -> dict[str, Any]:
+    uid = _require(user_id, "user_id")
+    return self.client.request(
+      "GET",
+      "/v1/memories",
+      params={
+        "userId": uid,
+        "appId": app_id or self.default_app_id,
+        "page": _clamp_int(page, 0, 10_000, 0),
+        "pageSize": _clamp_int(page_size, 1, 100, 20),
+      },
+    )
+
+  def forget(self, memory_id: str) -> dict[str, Any]:
+    mid = _require(memory_id, "memory_id")
+    return self.client.request("DELETE", f"/v1/memories/{mid}")
+
+  def forget_user(self, user_id: str, *, app_id: str | None = None) -> dict[str, Any]:
+    uid = _require(user_id, "user_id")
+    return self.client.request(
+      "DELETE",
+      "/v1/memories",
+      params={"userId": uid, "appId": app_id or self.default_app_id},
+    )
+
+  def forget_bulk(self, ids: list[str]) -> dict[str, Any]:
+    if not ids:
+      raise ValidationError("ids must be a non-empty list")
+    return self.client.request(
+      "DELETE",
+      "/v1/memories/bulk",
+      json_body={"ids": [str(i).strip() for i in ids]},
+    )

databaset-0.1.0.dist-info/METADATA

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: databaset
+Version: 0.1.0
+Summary: Official Databaset memory SDK for Python
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# Databaset Python SDK
+
+Default API: **`https://api.databaset.com`**
+
+```bash
+pip install -e ./sdks/python
+```
+
+```python
+import os
+from databaset import Memory
+
+memory = Memory(api_key=os.environ["DATABASET_API_KEY"])
+
+memory.store("user_123", "Prefers dark mode", metadata={"source": "api"})
+context = memory.recall("user_123", "editor preferences")
+print(context)
+```
+
+Set `DATABASET_API_KEY=db_...`. Optional `DATABASET_API_URL` (defaults to production).
+
+Local backend:
+
+```python
+memory = Memory(
+    api_key=os.environ["DATABASET_API_KEY"],
+    base_url="http://localhost:8085",
+)
+```

databaset-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+databaset/__init__.py,sha256=mc0bJu73A_j73TDWSr7zwOCRMkIIAjkkNMlP_aMs_-4,269
+databaset/client.py,sha256=dS3ZU63vyyxh7h4Sa8ExEryYCDEGF7Yg1F7B8duP-Bc,2701
+databaset/errors.py,sha256=0KpZ7NG6nuZ7d6iiPEsz_OmENd0YYs9_G01UfeN6eaI,405
+databaset/memory.py,sha256=EKnzYMDJePrln0Hsyw58gF4vAdIalPQXnOiYcXfYxFk,3873
+databaset-0.1.0.dist-info/METADATA,sha256=pU0WbmBZRfZ-KqI1k0y12hzu03VjYXHQmuUUsbXwomg,836
+databaset-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+databaset-0.1.0.dist-info/top_level.txt,sha256=-HICYufy2jNjV5KCvziZlMIkd7p_IFkjjisC9D9E20U,10
+databaset-0.1.0.dist-info/RECORD,,

databaset-0.1.0.dist-info/WHEEL

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

databaset-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+databaset