lunaris-integrations 0.8.0__tar.gz

lunaris_integrations-0.8.0/.gitignore

@@ -0,0 +1,125 @@
+# --- Rust ---
+/target
+target/
+**/*.rs.bk
+Cargo.lock.bak
+*.pdb
+
+# --- Python (PyO3 builds, evals, harnesses) ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.venv/
+venv/
+.python-version
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+uv.lock
+.tox/
+htmlcov/
+.coverage
+*.egg-info/
+build/
+dist/
+wheels/
+
+# --- Node / TypeScript (NAPI bindings) ---
+node_modules/
+.pnp
+.pnp.js
+*.tsbuildinfo
+.next/
+.turbo/
+.npm/
+.yarn/
+dist-ts/
+*.node
+
+# --- Editors / OS ---
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# --- Tooling caches ---
+.serena/
+.ruff_cache/
+.cargo/
+.rustup/
+# .claude/ is local tooling (settings.local.json, worktrees/, the
+# plugin-materialized `add` skill) EXCEPT the project-authored `/dream`
+# skill (engram-soul-loop task 9), which is a real shipped deliverable and
+# must be committed with the branch, not left as a local-only artifact.
+.claude/*
+!.claude/skills/
+.claude/skills/*
+!.claude/skills/dream/
+
+# --- Local env / secrets ---
+.env
+.env.local
+.env.*.local
+secrets/
+credentials.json
+# Provider API keys. The LME harness reads its key from MINIMAX_API_KEY or
+# from LUNARIS_BENCH_KEY_FILE (a path outside the repo); this is the backstop
+# for the habit of dropping a `*.key` next to the runner. No tracked file has
+# ever used this extension.
+*.key
+
+# --- Eval artefacts (large corpora, downloaded models) ---
+evals/data/
+evals/results/
+models/
+*.gguf
+*.safetensors
+*.onnx
+
+# --- LongMemEval harness output (scripts/bench/lme) ---
+# The runners default LME_RESULTS_DIR to target/lme, already covered by
+# `/target` above. These rules make the harness directory itself un-dirtyable
+# if an operator repoints LME_RESULTS_DIR at it: the SCRIPTS are tracked, the
+# run artifacts, caches and Moon scratch dirs never are. The LongMemEval
+# dataset is external and is never committed either (it downloads into
+# LUNARIS_EVAL_CACHE_DIR, default ~/.cache/lunaris/eval-hub).
+scripts/bench/lme/**/q*.json
+scripts/bench/lme/**/*.log
+scripts/bench/lme/**/config.fp
+scripts/bench/lme/**/config.env
+scripts/bench/lme/**/extract-cache/
+scripts/bench/lme/**/graphon/
+scripts/bench/lme/**/graphoff/
+scripts/bench/lme/**/fill/
+scripts/bench/lme/**/moon*/
+
+# --- Local Postgres / Moon dev state ---
+pgdata/
+moon-data/
+*.wal
+*.snapshot
+tmp/
+# Moon writes these into its --dir cwd; if a bench is run with `--dir .`
+# accidentally they end up in the repo root. Always-ignore so they don't
+# get staged or committed.
+appendonlydir/
+shard-*/
+replication.state
+*.aof
+*.rdb
+
+# --- Live measurement scratch reports ---
+LIVE-MEASUREMENT-REPORT.md
+milestones/v0.1.1-bench/cache/
+
+# mdBook build output
+/docs/book/book/
+
+# embedded-moon data dir (--features embedded-moon)
+# Matches the dir written by the production binary (repo root) AND by
+# cargo tests with --features embedded-moon (CWD = crates/lunaris-mcp/).
+# No leading slash — intentional, matches at any directory depth.
+.lunaris-moon/

lunaris_integrations-0.8.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: lunaris-integrations
+Version: 0.8.0
+Summary: Memory adapters for agent frameworks (LangGraph, CrewAI, Letta) on top of Lunaris.
+Project-URL: Homepage, https://github.com/pilotspace/lunaris
+Project-URL: Repository, https://github.com/pilotspace/lunaris
+Author: Lunaris
+License: Apache-2.0
+Keywords: agents,crewai,langgraph,letta,lunaris,memory
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.80; extra == 'crewai'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == 'langgraph'
+Provides-Extra: letta
+Requires-Dist: letta>=0.16; extra == 'letta'
+Provides-Extra: sdk
+Requires-Dist: lunaris; extra == 'sdk'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: respx>=0.21; extra == 'test'
+Description-Content-Type: text/markdown
+
+# lunaris-integrations
+
+Memory adapters that drop Lunaris into your existing agent framework. One thin,
+transport-agnostic layer — pick a transport once, reuse it across every adapter.
+
+```bash
+pip install -e "path/to/lunaris/integrations[langgraph]"   # or [crewai] / [letta]
+```
+
+`lunaris-integrations` is not on PyPI **yet**. `integrations-publish.yml`
+builds and uploads it on a `v*` tag, so from the next release on the line is:
+
+```bash
+pip install "lunaris-integrations[langgraph]"
+```
+
+Until that tag lands, install from a checkout with the `-e` form above — the
+one the [examples](../examples/) and CI both use, so it is the path that is
+actually exercised.
+
+## Why a separate package
+
+`lunaris_integrations` is a **pure-Python** package, separate from the native
+`lunaris` core wheel. Importing the client + scope layer never loads the
+compiled cdylib, and the framework deps (langgraph / crewai / letta) are
+**optional extras** — never hard dependencies of Lunaris core.
+
+## The shared client
+
+Every adapter is built over one `LunarisClient`, scope-bound at construction:
+
+| Transport            | Use when                                                        |
+|----------------------|-----------------------------------------------------------------|
+| `HttpLunarisClient`  | You run `lunaris-server`; talks the MemoryProtocol HTTP verbs.  |
+| `SdkLunarisClient`   | You embed the in-process `lunaris` wheel (`pip install lunaris`).|
+| `StubLunarisClient`  | Tests — records calls, returns canned hits (no backend).        |
+
+The HTTP transport binds scope to the JWT server-side; the partition scope
+**never travels on the wire**. Namespaces map to scopes through the Lunaris
+alphabet (`[A-Za-z0-9_\-.]{1,128}`, `:` rejected) so no key can byte-alias
+another scope's partition.
+
+## Adapters
+
+| Framework | Class                       | Maps                                  |
+|-----------|-----------------------------|---------------------------------------|
+| LangGraph | `langgraph.LunarisStore`    | `aput`/`aget`/`asearch` → ingest/recall |
+| CrewAI    | `crewai.LunarisCrewAIStorage` | `save`/`search`/`reset` → ingest/recall/forget |
+| Letta     | `letta.LunarisArchivalConnector` | `insert`/`search` → ingest/recall (connector shim + recipe) |
+
+> **Letta** ships as a client-backed connector shim + a [recipe](../examples/letta-lunaris/README.md):
+> its archival store is server-side, so there is no clean drop-in base to
+> subclass yet. The insert/search mapping is identical to the other adapters.
+
+## Examples
+
+Runnable per-framework examples live in [`../examples/`](../examples/):
+`langgraph-lunaris/`, `crewai-lunaris/`, `letta-lunaris/`.
+
+## Tests
+
+```bash
+pip install -e ".[langgraph,crewai,letta,test]"   # from integrations/
+pytest tests/
+```
+
+The unit layer runs against `StubLunarisClient` — no backend, model, or wheel.
+Live HTTP/SDK + a real framework end-to-end is exercised by the examples.

lunaris_integrations-0.8.0/README.md

@@ -0,0 +1,68 @@
+# lunaris-integrations
+
+Memory adapters that drop Lunaris into your existing agent framework. One thin,
+transport-agnostic layer — pick a transport once, reuse it across every adapter.
+
+```bash
+pip install -e "path/to/lunaris/integrations[langgraph]"   # or [crewai] / [letta]
+```
+
+`lunaris-integrations` is not on PyPI **yet**. `integrations-publish.yml`
+builds and uploads it on a `v*` tag, so from the next release on the line is:
+
+```bash
+pip install "lunaris-integrations[langgraph]"
+```
+
+Until that tag lands, install from a checkout with the `-e` form above — the
+one the [examples](../examples/) and CI both use, so it is the path that is
+actually exercised.
+
+## Why a separate package
+
+`lunaris_integrations` is a **pure-Python** package, separate from the native
+`lunaris` core wheel. Importing the client + scope layer never loads the
+compiled cdylib, and the framework deps (langgraph / crewai / letta) are
+**optional extras** — never hard dependencies of Lunaris core.
+
+## The shared client
+
+Every adapter is built over one `LunarisClient`, scope-bound at construction:
+
+| Transport            | Use when                                                        |
+|----------------------|-----------------------------------------------------------------|
+| `HttpLunarisClient`  | You run `lunaris-server`; talks the MemoryProtocol HTTP verbs.  |
+| `SdkLunarisClient`   | You embed the in-process `lunaris` wheel (`pip install lunaris`).|
+| `StubLunarisClient`  | Tests — records calls, returns canned hits (no backend).        |
+
+The HTTP transport binds scope to the JWT server-side; the partition scope
+**never travels on the wire**. Namespaces map to scopes through the Lunaris
+alphabet (`[A-Za-z0-9_\-.]{1,128}`, `:` rejected) so no key can byte-alias
+another scope's partition.
+
+## Adapters
+
+| Framework | Class                       | Maps                                  |
+|-----------|-----------------------------|---------------------------------------|
+| LangGraph | `langgraph.LunarisStore`    | `aput`/`aget`/`asearch` → ingest/recall |
+| CrewAI    | `crewai.LunarisCrewAIStorage` | `save`/`search`/`reset` → ingest/recall/forget |
+| Letta     | `letta.LunarisArchivalConnector` | `insert`/`search` → ingest/recall (connector shim + recipe) |
+
+> **Letta** ships as a client-backed connector shim + a [recipe](../examples/letta-lunaris/README.md):
+> its archival store is server-side, so there is no clean drop-in base to
+> subclass yet. The insert/search mapping is identical to the other adapters.
+
+## Examples
+
+Runnable per-framework examples live in [`../examples/`](../examples/):
+`langgraph-lunaris/`, `crewai-lunaris/`, `letta-lunaris/`.
+
+## Tests
+
+```bash
+pip install -e ".[langgraph,crewai,letta,test]"   # from integrations/
+pytest tests/
+```
+
+The unit layer runs against `StubLunarisClient` — no backend, model, or wheel.
+Live HTTP/SDK + a real framework end-to-end is exercised by the examples.

lunaris_integrations-0.8.0/lunaris_integrations/__init__.py

@@ -0,0 +1,40 @@
+"""lunaris_integrations — memory adapters for agent frameworks.
+
+A thin, transport-agnostic layer on top of Lunaris. Every adapter
+(LangGraph / CrewAI / Letta) is built over the shared `LunarisClient`
+(HTTP MemoryProtocol or in-process lunaris-py SDK), so the adapters stay small
+and the framework deps are OPTIONAL extras — never a hard dep of `lunaris` core.
+
+    pip install lunaris-integrations[langgraph]   # or [crewai] / [letta]
+
+The framework adapter modules (`.langgraph`, `.crewai`, `.letta`) import their
+framework at module load and are version-guarded; import them only when the
+corresponding extra is installed.
+"""
+from __future__ import annotations
+
+from .client import (
+    ConfigError,
+    Hit,
+    HttpLunarisClient,
+    InvalidScope,
+    LunarisClient,
+    SdkLunarisClient,
+    StubLunarisClient,
+    UnsupportedFrameworkVersion,
+    namespace_to_scope,
+    require_base_methods,
+)
+
+__all__ = [
+    "Hit",
+    "LunarisClient",
+    "HttpLunarisClient",
+    "SdkLunarisClient",
+    "StubLunarisClient",
+    "ConfigError",
+    "InvalidScope",
+    "UnsupportedFrameworkVersion",
+    "namespace_to_scope",
+    "require_base_methods",
+]

lunaris_integrations-0.8.0/lunaris_integrations/client.py

@@ -0,0 +1,287 @@
+"""Shared `LunarisClient` layer for the framework adapters.
+
+This is the ONE seam every adapter (LangGraph / CrewAI / Letta) talks to, so
+each adapter stays ~tens of LOC and transport-agnostic. Two production
+transports + a test double, all satisfying the same `LunarisClient` Protocol:
+
+- `HttpLunarisClient` — talks the MemoryProtocol HTTP verbs on lunaris-server
+  (`POST /v1/ingest`, `POST /v1/recall`, `POST /v1/forget`) with a Bearer JWT.
+  The partition scope is bound to the JWT on the server side, so it NEVER
+  travels on the wire (honors the server's scope discipline).
+- `SdkLunarisClient` — wraps the in-process lunaris-py handle. `lunaris` is
+  imported LAZILY so this module (and the whole unit-test layer) loads without
+  the compiled cdylib / a backend.
+- `StubLunarisClient` — records calls + returns canned hits; the unit layer
+  runs against this with no backend, model, or wheel.
+
+Frozen contract: `.add/tasks/sdk-integrations-dx/TASK.md` §3.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Iterable, Protocol, runtime_checkable
+
+# RFC 0001 Scope alphabet — must match `lunaris_core::scope::Scope::new`
+# (`[A-Za-z0-9_\-.]{1,128}`). `:` is rejected so an adapter can never mint a
+# scope string that byte-aliases another partition in `lunaris:{scope}:...`.
+_SCOPE_RE = re.compile(r"^[A-Za-z0-9_\-.]{1,128}$")
+
+
+@dataclass
+class Hit:
+    """One recalled item — the adapter-neutral shape every transport returns."""
+
+    id: str
+    content: str
+    score: float
+    source: str | None = None
+
+
+# ── Exceptions ────────────────────────────────────────────────────────────────
+class ConfigError(Exception):
+    """A transport was constructed without the config it needs to ever work
+    (e.g. an HTTP client with no base URL / an SDK client with no handle).
+    Raised AT CONSTRUCTION so no request is attempted at first use."""
+
+
+class InvalidScope(Exception):
+    """A namespace mapped to a scope outside the Lunaris alphabet."""
+
+    def __init__(self, value: object) -> None:
+        self.value = value
+        super().__init__(f"invalid_scope: {value!r}")
+
+
+class UnsupportedFrameworkVersion(Exception):
+    """The installed framework's base class/shape does not match the pinned
+    shape the adapter was written against — fail loud, never mis-map."""
+
+    def __init__(self, framework: str, found: object, expected: str) -> None:
+        self.framework = framework
+        self.found = found
+        self.expected = expected
+        super().__init__(
+            f"unsupported {framework} version: found {found!r}, expected {expected}"
+        )
+
+
+# ── Scope mapping ───────────────────────────────────────────────────────────
+def namespace_to_scope(ns: tuple[str, ...] | str) -> str:
+    """Map a framework namespace to a validated Lunaris scope string.
+
+    A tuple namespace (`("u", "mem")`) joins with `.` → `"u.mem"`. The result
+    is validated against the Scope alphabet; `:` / bad char / empty / >128
+    chars raise `InvalidScope` BEFORE any client call.
+    """
+    if isinstance(ns, str):
+        scope = ns
+    else:
+        parts = tuple(ns)
+        if not parts:
+            raise InvalidScope(ns)
+        scope = ".".join(str(p) for p in parts)
+    if not _SCOPE_RE.match(scope):
+        raise InvalidScope(scope)
+    return scope
+
+
+def require_base_methods(
+    base_cls: type,
+    required: Iterable[str],
+    *,
+    framework: str,
+    found: object,
+    expected: str,
+) -> None:
+    """Version-guard: raise `UnsupportedFrameworkVersion` if `base_cls` is
+    missing any required method. Called by each adapter at import/instantiation
+    so framework drift fails loud instead of silently mis-mapping."""
+    missing = sorted(m for m in required if not hasattr(base_cls, m))
+    if missing:
+        raise UnsupportedFrameworkVersion(framework, found, expected)
+
+
+# ── The client Protocol ─────────────────────────────────────────────────────
+@runtime_checkable
+class LunarisClient(Protocol):
+    """The single interface every adapter depends on. Scope-bound at
+    construction; the adapter supplies content + query, never a transport."""
+
+    scope: str
+
+    async def ingest(
+        self, source: str, content: str, metadata: dict | None = None
+    ) -> str: ...
+
+    async def recall(self, query: str, k: int = 10) -> list[Hit]: ...
+
+    async def forget_scope(self) -> None: ...
+
+
+# ── HTTP transport ──────────────────────────────────────────────────────────
+class HttpLunarisClient:
+    """MemoryProtocol-over-HTTP client. Scope is JWT-bound server-side and is
+    NEVER placed on the wire."""
+
+    def __init__(
+        self, base_url: str, token: str, scope: str, *, timeout: float = 10.0
+    ) -> None:
+        if not base_url:
+            raise ConfigError("HttpLunarisClient requires a base_url")
+        if not token:
+            raise ConfigError("HttpLunarisClient requires a Bearer token")
+        # Validate the scope at the boundary (no `:` byte-aliasing).
+        self.scope = namespace_to_scope(scope)
+        self._base_url = base_url.rstrip("/")
+        # httpx is a CORE dep of lunaris_integrations (not an optional extra).
+        import httpx
+
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=timeout,
+        )
+
+    async def ingest(
+        self, source: str, content: str, metadata: dict | None = None
+    ) -> str:
+        # `IngestBody.metadata` is a JSON object with `#[serde(default)]` — send
+        # `{}` (NEVER null) so `deny_unknown_fields` + the Map typing accept it.
+        resp = await self._client.post(
+            "/v1/ingest",
+            json={"source": source, "content": content, "metadata": metadata or {}},
+        )
+        resp.raise_for_status()
+        return _lsn_to_str(resp.json()["lsn"])
+
+    async def recall(self, query: str, k: int = 10) -> list[Hit]:
+        resp = await self._client.post("/v1/recall", json={"query": query, "k": k})
+        resp.raise_for_status()
+        # `/v1/recall` returns a BARE JSON array of hits (`Json(Vec<Hit>)`), not
+        # an object with a "hits" key.
+        return [_hit_from_dict(h) for h in resp.json()]
+
+    async def forget_scope(self) -> None:
+        # Soft-purge the whole JWT-bound scope: `ForgetTarget::Scope` with an
+        # empty-prefix `BySource` match (matches every source in the partition).
+        # `hard=false` so the D-21 dry_run→confirm 2-step is NOT required; the
+        # partition scope itself stays JWT-bound server-side.
+        resp = await self._client.post(
+            "/v1/forget",
+            json={
+                "target": {"Scope": {"BySource": ""}},
+                "hard": False,
+                "dry_run": False,
+            },
+        )
+        resp.raise_for_status()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+
+# ── In-process SDK transport ────────────────────────────────────────────────
+class SdkLunarisClient:
+    """Wraps the in-process lunaris-py handle (`open(url)`); `lunaris` is
+    imported lazily so this module loads without the compiled wheel. The live
+    path is exercised by the example + HUMAN-UAT (needs the wheel + a backend
+    per the py/ts SDK test caveat)."""
+
+    def __init__(self, handle: object, scope: str) -> None:
+        if handle is None:
+            raise ConfigError("SdkLunarisClient requires an open lunaris handle")
+        self.scope = namespace_to_scope(scope)
+        self._handle = handle
+
+    def _scoped(self):
+        import lunaris  # lazy — only the SDK transport needs the cdylib
+
+        return self._handle.scoped(lunaris.Scope(self.scope))
+
+    async def ingest(
+        self, source: str, content: str, metadata: dict | None = None
+    ) -> str:
+        import lunaris
+
+        builder = lunaris.EpisodeBuilder(source, content)
+        if metadata:
+            builder = builder.metadata(metadata)
+        lsn = await self._handle.scoped(lunaris.Scope(self.scope)).ingest(builder)
+        return str(lsn)
+
+    async def recall(self, query: str, k: int = 10) -> list[Hit]:
+        # `scoped.recall` returns pythonized hit dicts (scope-threaded). k is
+        # applied as a client-side cap; the DSL `.top(k)` path is available via
+        # the example for operators who need server-side top-k.
+        hits = await self._scoped().recall(query)
+        return [_hit_from_dict(h) for h in list(hits)[:k]]
+
+    async def forget_scope(self) -> None:
+        # The in-process lunaris-py binding does not expose scope-forget on
+        # ScopedLunaris (only ingest/recall/dsl). Use the HTTP transport for
+        # scope-clear / CrewAI reset(), or call the server's /v1/forget.
+        raise NotImplementedError(
+            "scope-forget is not exposed by the in-process lunaris-py binding; "
+            "use HttpLunarisClient for forget_scope / CrewAI reset()"
+        )
+
+
+# ── Test double ───────────────────────────────────────────────────────────-─
+class StubLunarisClient:
+    """Records every call + returns canned hits. The unit layer runs against
+    this — no backend, model, or wheel."""
+
+    def __init__(self, scope: str, hits: list[Hit] | None = None) -> None:
+        self.scope = scope
+        self._hits = hits or []
+        self.ingest_calls: list[tuple[str, str, dict | None]] = []
+        self.recall_calls: list[tuple[str, int]] = []
+        self.forget_calls = 0
+
+    async def ingest(
+        self, source: str, content: str, metadata: dict | None = None
+    ) -> str:
+        self.ingest_calls.append((source, content, metadata))
+        return f"stub-lsn-{len(self.ingest_calls)}"
+
+    async def recall(self, query: str, k: int = 10) -> list[Hit]:
+        self.recall_calls.append((query, k))
+        return list(self._hits[:k])
+
+    async def forget_scope(self) -> None:
+        self.forget_calls += 1
+
+
+def _hit_from_dict(d: dict) -> Hit:
+    """Map a `lunaris_retrieve::Hit` JSON object to the adapter-neutral `Hit`.
+
+    The server/SDK hit carries its body in `text` and its id as a byte array
+    (16-byte ULID `Vec<u8>`); `content` is also accepted for forward-compat.
+    """
+    return Hit(
+        id=_decode_id(d.get("id", "")),
+        content=str(d.get("content", d.get("text", ""))),
+        score=float(d.get("score", 0.0)),
+        source=(d.get("source") or None),
+    )
+
+
+def _decode_id(raw: object) -> str:
+    """`Hit.id` serializes as a byte array (`Vec<u8>`, 16-byte ULID). Hex-encode
+    it to a stable string id; pass a plain string through unchanged."""
+    if isinstance(raw, (list, tuple)):
+        try:
+            return bytes(int(b) & 0xFF for b in raw).hex()
+        except (TypeError, ValueError):
+            return ""
+    return str(raw)
+
+
+def _lsn_to_str(raw: object) -> str:
+    """`IngestResponse.lsn` serializes as `{"wall_ms":u64,"counter":u32}`.
+    Format it as the canonical `"{wall_ms}:{counter}"` (matches `Lsn` Display);
+    accept a plain string/number too."""
+    if isinstance(raw, dict) and "wall_ms" in raw:
+        return f"{raw['wall_ms']}:{raw.get('counter', 0)}"
+    return str(raw)