unshadow 0.2.0__tar.gz

unshadow-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unshadow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unshadow-0.2.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: unshadow
+Version: 0.2.0
+Summary: Python client for Unshadow Engine and agent banks.
+Author-email: Unshadow <support@unshadow.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://unshadow.dev
+Project-URL: Documentation, https://unshadow.dev/docs/api/sdk
+Project-URL: Repository, https://github.com/unshadow-ai/unshadow
+Project-URL: Issues, https://github.com/unshadow-ai/unshadow/issues
+Keywords: unshadow,memory,langchain,llamaindex,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.11; extra == "llamaindex"
+Dynamic: license-file
+
+# Unshadow (Python)
+
+Stdlib client for **Unshadow Engine**, plus an agent-bank client. PyPI name: `unshadow`.
+
+```bash
+pip install unshadow
+```
+
+From this repo, before the PyPI upload:
+
+```bash
+pip install ./packages/unshadow
+```
+
+LangChain is optional:
+
+```bash
+pip install "./packages/unshadow[langchain]"
+```
+
+## Engine
+
+`Unshadow` matches the TypeScript SDK: `context`, `search`, `extract`, `forget`, `profile`.
+
+```python
+from unshadow import Unshadow
+
+unshadow = Unshadow(api_key="unshadow_…")
+packed = unshadow.inject_context("What am I working on?", token_budget=1500)
+hits = unshadow.search("pnpm", limit=8, category="preference")
+unshadow.extract(
+    "User prefers pnpm",
+    source_type="ai_conversation",
+    idempotency_key="turn-1",
+)
+unshadow.forget(["11111111-1111-1111-1111-111111111111"])
+```
+
+`extract(..., idempotency_key=)` sends `Idempotency-Key`. Reads retry once on 429/5xx. `extract` retries only when that key is set. A new fact can supersede, contradict, or coexist with an older one. Search rows include `supersedes` and `superseded_by`. `UnshadowRetriever` copies `id`, `category`, `source_type`, and those lists into document metadata. Filter with `unshadow.search("editor", category="preference")`.
+
+### LangChain
+
+```python
+from langchain_unshadow import UnshadowRetriever
+from unshadow import Unshadow
+
+unshadow = Unshadow(api_key="unshadow_…")
+retriever = UnshadowRetriever(client=unshadow, k=8, prefer_context=True)
+docs = retriever.invoke("What did we decide about pnpm?")
+```
+
+`prefer_context` uses `POST /context` and splits `[mem:uuid]` lines. This is not `ConversationBufferMemory`.
+
+### LlamaIndex
+
+```bash
+pip install "./packages/unshadow[llamaindex]"
+```
+
+```python
+from llama_index_unshadow import UnshadowRetriever
+from unshadow import Unshadow
+
+unshadow = Unshadow(api_key="unshadow_…")
+retriever = UnshadowRetriever(unshadow, k=8, prefer_context=True)
+nodes = retriever.retrieve("What did we decide about pnpm?")
+```
+
+## Agent bank
+
+`UnshadowBank` is retain / recall / authorize. Those calls still use `/lattice/*`.
+
+```python
+from unshadow import UnshadowBank
+
+bank = UnshadowBank(api_key="unshadow_…")
+bank.remember("Ship on Fridays is forbidden.", conversation_key="agent-main")
+packed = bank.context("release policy")
+receipt = bank.authorize(["memory-id"], query="deploy production")
+bank.explain(packed["operation_id"])
+```
+
+| Name | HTTP |
+|------|------|
+| `remember` | `POST /lattice/retain` (delta, 32k cap, 409 retry) |
+| `explain` | `POST /lattice/explain` |
+| `authorize` | `POST /lattice/recall` with `purpose: tool_arg` |
+
+`retain` is an alias of `remember`. Hermes still uses `packages/lattice-hermes`.
+
+The bank client does not ingest files. Capture stores pages and repo notes. Link that project into the agent bank. `remember(..., source_url=...)` cites a URL.
+
+## Tests
+
+```bash
+python -m unittest discover -s packages/unshadow/tests
+```

unshadow-0.2.0/README.md

@@ -0,0 +1,97 @@
+# Unshadow (Python)
+
+Stdlib client for **Unshadow Engine**, plus an agent-bank client. PyPI name: `unshadow`.
+
+```bash
+pip install unshadow
+```
+
+From this repo, before the PyPI upload:
+
+```bash
+pip install ./packages/unshadow
+```
+
+LangChain is optional:
+
+```bash
+pip install "./packages/unshadow[langchain]"
+```
+
+## Engine
+
+`Unshadow` matches the TypeScript SDK: `context`, `search`, `extract`, `forget`, `profile`.
+
+```python
+from unshadow import Unshadow
+
+unshadow = Unshadow(api_key="unshadow_…")
+packed = unshadow.inject_context("What am I working on?", token_budget=1500)
+hits = unshadow.search("pnpm", limit=8, category="preference")
+unshadow.extract(
+    "User prefers pnpm",
+    source_type="ai_conversation",
+    idempotency_key="turn-1",
+)
+unshadow.forget(["11111111-1111-1111-1111-111111111111"])
+```
+
+`extract(..., idempotency_key=)` sends `Idempotency-Key`. Reads retry once on 429/5xx. `extract` retries only when that key is set. A new fact can supersede, contradict, or coexist with an older one. Search rows include `supersedes` and `superseded_by`. `UnshadowRetriever` copies `id`, `category`, `source_type`, and those lists into document metadata. Filter with `unshadow.search("editor", category="preference")`.
+
+### LangChain
+
+```python
+from langchain_unshadow import UnshadowRetriever
+from unshadow import Unshadow
+
+unshadow = Unshadow(api_key="unshadow_…")
+retriever = UnshadowRetriever(client=unshadow, k=8, prefer_context=True)
+docs = retriever.invoke("What did we decide about pnpm?")
+```
+
+`prefer_context` uses `POST /context` and splits `[mem:uuid]` lines. This is not `ConversationBufferMemory`.
+
+### LlamaIndex
+
+```bash
+pip install "./packages/unshadow[llamaindex]"
+```
+
+```python
+from llama_index_unshadow import UnshadowRetriever
+from unshadow import Unshadow
+
+unshadow = Unshadow(api_key="unshadow_…")
+retriever = UnshadowRetriever(unshadow, k=8, prefer_context=True)
+nodes = retriever.retrieve("What did we decide about pnpm?")
+```
+
+## Agent bank
+
+`UnshadowBank` is retain / recall / authorize. Those calls still use `/lattice/*`.
+
+```python
+from unshadow import UnshadowBank
+
+bank = UnshadowBank(api_key="unshadow_…")
+bank.remember("Ship on Fridays is forbidden.", conversation_key="agent-main")
+packed = bank.context("release policy")
+receipt = bank.authorize(["memory-id"], query="deploy production")
+bank.explain(packed["operation_id"])
+```
+
+| Name | HTTP |
+|------|------|
+| `remember` | `POST /lattice/retain` (delta, 32k cap, 409 retry) |
+| `explain` | `POST /lattice/explain` |
+| `authorize` | `POST /lattice/recall` with `purpose: tool_arg` |
+
+`retain` is an alias of `remember`. Hermes still uses `packages/lattice-hermes`.
+
+The bank client does not ingest files. Capture stores pages and repo notes. Link that project into the agent bank. `remember(..., source_url=...)` cites a URL.
+
+## Tests
+
+```bash
+python -m unittest discover -s packages/unshadow/tests
+```

unshadow-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unshadow"
+version = "0.2.0"
+description = "Python client for Unshadow Engine and agent banks."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Unshadow", email = "support@unshadow.dev" }]
+keywords = ["unshadow", "memory", "langchain", "llamaindex", "rag"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://unshadow.dev"
+Documentation = "https://unshadow.dev/docs/api/sdk"
+Repository = "https://github.com/unshadow-ai/unshadow"
+Issues = "https://github.com/unshadow-ai/unshadow/issues"
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3"]
+llamaindex = ["llama-index-core>=0.11"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

unshadow-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

unshadow-0.2.0/src/langchain_unshadow/__init__.py

@@ -0,0 +1,5 @@
+"""Optional LangChain retriever. Install ``langchain-core`` before importing."""
+
+from langchain_unshadow.retriever import UnshadowRetriever
+
+__all__ = ["UnshadowRetriever"]

unshadow-0.2.0/src/langchain_unshadow/retriever.py

@@ -0,0 +1,35 @@
+"""LangChain retriever over the Unshadow Engine client."""
+
+from typing import Any
+
+from langchain_core.callbacks import CallbackManagerForRetrieverRun
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+
+from unshadow.documents import documents_from_context, documents_from_search
+
+
+class UnshadowRetriever(BaseRetriever):
+    """Search Unshadow Engine. ``prefer_context`` uses ``POST /context``."""
+
+    client: Any
+    k: int = 8
+    prefer_context: bool = False
+
+    def _get_relevant_documents(
+        self,
+        query: str,
+        *,
+        run_manager: CallbackManagerForRetrieverRun,
+    ) -> list[Document]:
+        del run_manager
+        if self.prefer_context:
+            body = self.client.context(query, search_limit=self.k)
+            rows = documents_from_context(str(body.get("context") or ""), body.get("sources"))
+        else:
+            body = self.client.search(query, limit=self.k)
+            rows = documents_from_search(body)
+        return [
+            Document(page_content=row["page_content"], metadata=row["metadata"])
+            for row in rows[: self.k]
+        ]

unshadow-0.2.0/src/llama_index_unshadow/__init__.py

@@ -0,0 +1,5 @@
+"""Optional LlamaIndex retriever. Install ``llama-index-core`` before importing."""
+
+from llama_index_unshadow.retriever import UnshadowRetriever
+
+__all__ = ["UnshadowRetriever"]

unshadow-0.2.0/src/llama_index_unshadow/retriever.py

@@ -0,0 +1,32 @@
+"""LlamaIndex retriever over the Unshadow Engine client."""
+
+from typing import Any
+
+from llama_index.core.retrievers import BaseRetriever
+from llama_index.core.schema import NodeWithScore, QueryBundle, TextNode
+
+from unshadow.documents import documents_from_context, documents_from_search
+
+
+class UnshadowRetriever(BaseRetriever):
+    """Search Unshadow Engine. ``prefer_context`` uses ``POST /context``."""
+
+    def __init__(self, client: Any, k: int = 8, prefer_context: bool = False, **kwargs: Any) -> None:
+        self._client = client
+        self._k = k
+        self._prefer_context = prefer_context
+        super().__init__(**kwargs)
+
+    def _retrieve(self, query_bundle: QueryBundle) -> list[NodeWithScore]:
+        query = query_bundle.query_str
+        if self._prefer_context:
+            body = self._client.context(query, search_limit=self._k)
+            rows = documents_from_context(str(body.get("context") or ""), body.get("sources"))
+        else:
+            body = self._client.search(query, limit=self._k)
+            rows = documents_from_search(body)
+        nodes: list[NodeWithScore] = []
+        for row in rows[: self._k]:
+            node = TextNode(text=row["page_content"], metadata=row["metadata"])
+            nodes.append(NodeWithScore(node=node, score=1.0))
+        return nodes

unshadow-0.2.0/src/unshadow/__init__.py

@@ -0,0 +1,11 @@
+"""Public Unshadow Python clients.
+
+``Unshadow`` is Engine HTTP (``/context``, ``/search``, ``/extract``, ``/forget-memories``, ``/profile``).
+``UnshadowBank`` is the agent bank (``/lattice/*``).
+"""
+
+from unshadow.bank import UnshadowBank
+from unshadow.client import Unshadow
+from unshadow.http import UnshadowHttpError
+
+__all__ = ["Unshadow", "UnshadowBank", "UnshadowHttpError"]

unshadow-0.2.0/src/unshadow/bank.py

@@ -0,0 +1,127 @@
+"""Agent-bank client. HTTP paths stay ``/lattice/*``."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from unshadow.http import UnshadowHttp, UnshadowHttpError
+
+
+RETAIN_MAX_CHARS = 32_000
+
+
+class UnshadowBank(UnshadowHttp):
+    def remember(
+        self,
+        text: str,
+        *,
+        conversation_key: str = "default",
+        prev_hash: str | None = None,
+        source_type: str = "manual_entry",
+        source_url: str | None = None,
+    ) -> dict[str, Any]:
+        """Delta retain. Do not pass file contents; cite ``source_url`` and link Capture."""
+        clipped = text if len(text) <= RETAIN_MAX_CHARS else text[: RETAIN_MAX_CHARS - 1]
+        body: dict[str, Any] = {
+            "text": clipped,
+            "conversation_key": conversation_key,
+            "source_type": source_type,
+        }
+        if prev_hash:
+            body["prev_hash"] = prev_hash
+        if source_url:
+            body["source_url"] = source_url
+        try:
+            return self.post("/lattice/retain", body)
+        except UnshadowHttpError as exc:
+            if exc.status != 409:
+                raise
+            err = exc.body.get("error") if isinstance(exc.body, Mapping) else None
+            expected = err.get("expected_hash") if isinstance(err, Mapping) else None
+            if not expected or expected == prev_hash:
+                raise
+            body["prev_hash"] = expected
+            return self.post("/lattice/retain", body)
+
+    def retain(
+        self,
+        text: str,
+        *,
+        conversation_key: str = "default",
+        prev_hash: str | None = None,
+        source_type: str = "manual_entry",
+        source_url: str | None = None,
+    ) -> dict[str, Any]:
+        return self.remember(
+            text,
+            conversation_key=conversation_key,
+            prev_hash=prev_hash,
+            source_type=source_type,
+            source_url=source_url,
+        )
+
+    def recall(
+        self,
+        query: str = "",
+        *,
+        purpose: str = "answer",
+        memory_ids: Sequence[str] | None = None,
+        limit: int | None = None,
+        trust: str | None = None,
+        token_budget: int | None = None,
+        format: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"query": query, "purpose": purpose}
+        if memory_ids is not None:
+            body["memory_ids"] = list(memory_ids)
+        if limit is not None:
+            body["limit"] = limit
+        if trust is not None:
+            body["trust"] = trust
+        if token_budget is not None:
+            body["token_budget"] = token_budget
+        if format is not None:
+            body["format"] = format
+        return self.post("/lattice/recall", body)
+
+    def context(
+        self,
+        query: str,
+        *,
+        trust: str = "advisory",
+        token_budget: int = 1200,
+        purpose: str = "answer",
+    ) -> dict[str, Any]:
+        return self.post(
+            "/lattice/context",
+            {
+                "query": query,
+                "trust": trust,
+                "token_budget": token_budget,
+                "purpose": purpose,
+            },
+        )
+
+    def authorize(
+        self,
+        memory_ids: Sequence[str],
+        *,
+        query: str = "",
+    ) -> dict[str, Any]:
+        """Fail-closed tool grounding. ``purpose`` is always ``tool_arg``."""
+        return self.recall(query, purpose="tool_arg", memory_ids=list(memory_ids))
+
+    def explain(self, operation_id: str) -> dict[str, Any]:
+        return self.post("/lattice/explain", {"operation_id": operation_id})
+
+    def reflect(self, query: str, **kwargs: Any) -> dict[str, Any]:
+        return self.post("/lattice/reflect", {"query": query, **kwargs})
+
+    def feedback(self, **kwargs: Any) -> dict[str, Any]:
+        return self.post("/lattice/feedback", kwargs)
+
+    def correct(self, memory_ids: Sequence[str]) -> dict[str, Any]:
+        return self.post("/lattice/correct", {"memory_ids": list(memory_ids)})
+
+    def forget(self, memory_ids: Sequence[str]) -> dict[str, Any]:
+        return self.post("/lattice/forget", {"memory_ids": list(memory_ids)})

unshadow-0.2.0/src/unshadow/client.py

@@ -0,0 +1,96 @@
+"""Unshadow Engine client. Same HTTP as the TypeScript SDK and hosted MCP."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+from urllib.parse import urlencode
+
+from unshadow.http import UnshadowHttp
+
+
+class Unshadow(UnshadowHttp):
+    def context(
+        self,
+        query: str | None = None,
+        *,
+        token_budget: int | None = None,
+        search_mode: str | None = None,
+        search_limit: int | None = None,
+        since: str | None = None,
+        until: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {}
+        if query is not None:
+            body["query"] = query
+        if token_budget is not None:
+            body["token_budget"] = token_budget
+        if search_mode is not None:
+            body["search_mode"] = search_mode
+        if search_limit is not None:
+            body["search_limit"] = search_limit
+        if since is not None:
+            body["since"] = since
+        if until is not None:
+            body["until"] = until
+        return self.post("/context", body, retry=True)
+
+    def inject_context(self, query: str, **kwargs: Any) -> dict[str, Any]:
+        """Alias of ``context`` for prompt injection."""
+        return self.context(query, **kwargs)
+
+    def search(
+        self,
+        query: str,
+        *,
+        limit: int | None = None,
+        mode: str | None = None,
+        category: str | None = None,
+        pool: int | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, str] = {"query": query}
+        if limit is not None:
+            params["limit"] = str(limit)
+        if mode is not None:
+            params["mode"] = mode
+        if category is not None:
+            params["category"] = category
+        if pool is not None:
+            params["pool"] = str(pool)
+        return self.get(f"/search?{urlencode(params)}", retry=True)
+
+    def extract(
+        self,
+        text: str,
+        *,
+        source_type: str | None = None,
+        source_url: str | None = None,
+        conversation_id: str | None = None,
+        sandbox_id: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"text": text}
+        if source_type is not None:
+            body["source_type"] = source_type
+        if source_url is not None:
+            body["source_url"] = source_url
+        if conversation_id is not None:
+            body["conversation_id"] = conversation_id
+        if sandbox_id is not None:
+            body["sandbox_id"] = sandbox_id
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self.post("/extract", body, headers=headers, retry=bool(idempotency_key))
+
+    def profile(self) -> dict[str, Any]:
+        return self.get("/profile", retry=True)
+
+    def forget(
+        self,
+        memory_ids: Sequence[str] | None = None,
+        *,
+        forget_all: bool = False,
+    ) -> dict[str, Any]:
+        if forget_all:
+            body: dict[str, Any] = {"forget_all": True}
+        else:
+            body = {"memory_ids": list(memory_ids or [])}
+        return self.post("/forget-memories", body)

unshadow-0.2.0/src/unshadow/documents.py

@@ -0,0 +1,71 @@
+"""Turn Engine search and context payloads into retriever documents."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Mapping
+
+
+_MEM = re.compile(r"\[mem:([0-9a-fA-F-]{8,})\]")
+
+
+def _fact(row: Any) -> tuple[str, dict[str, Any]] | None:
+    if not isinstance(row, Mapping):
+        return None
+    text = row.get("fact") or row.get("content") or row.get("statement") or row.get("text") or ""
+    if not isinstance(text, str) or not text.strip():
+        return None
+    metadata: dict[str, Any] = {}
+    for key in ("id", "memory_id", "category", "source_url", "source_type", "created_at", "supersedes", "superseded_by"):
+        if row.get(key) is not None:
+            metadata["id" if key == "memory_id" else key] = row[key]
+    return text, metadata
+
+
+def documents_from_search(body: Mapping[str, Any]) -> list[dict[str, Any]]:
+    memories = body.get("memories") if isinstance(body.get("memories"), list) else []
+    docs = []
+    for row in memories:
+        parsed = _fact(row)
+        if parsed is None:
+            continue
+        page, metadata = parsed
+        docs.append({"page_content": page, "metadata": metadata})
+    if docs:
+        return docs
+    facts = body.get("facts") if isinstance(body.get("facts"), list) else []
+    return [
+        {"page_content": fact, "metadata": {}}
+        for fact in facts
+        if isinstance(fact, str) and fact.strip()
+    ]
+
+
+def documents_from_context(context: str, sources: list[Mapping[str, Any]] | None = None) -> list[dict[str, Any]]:
+    rows = sources if isinstance(sources, list) else []
+    by_id: dict[str, Mapping[str, Any]] = {}
+    for row in rows:
+        if not isinstance(row, Mapping):
+            continue
+        memory_id = row.get("memory_id") or row.get("id")
+        if isinstance(memory_id, str) and memory_id:
+            by_id[memory_id] = row
+    docs: list[dict[str, Any]] = []
+    for chunk in re.split(r"\n{2,}|\n", context):
+        piece = chunk.strip()
+        if not piece:
+            continue
+        ids = _MEM.findall(piece)
+        page = _MEM.sub("", piece).strip()
+        if not page:
+            continue
+        metadata: dict[str, Any] = {"id": ids[0]} if ids else {}
+        source = by_id.get(ids[0]) if ids else None
+        if source:
+            for key in ("category", "source_type", "source_url", "supersedes", "superseded_by"):
+                if source.get(key) is not None:
+                    metadata[key] = source[key]
+        docs.append({"page_content": page, "metadata": metadata})
+    if not docs and context.strip():
+        return [{"page_content": context.strip(), "metadata": {}}]
+    return docs

unshadow-0.2.0/src/unshadow/http.py

@@ -0,0 +1,100 @@
+"""Shared HTTP for the Unshadow Python clients."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Mapping
+
+
+DEFAULT_API_URL = "https://api.unshadow.dev/v1"
+USER_AGENT = "unshadow-python/0.2.0"
+RETRY_STATUSES = {429, 500, 502, 503, 504}
+
+
+class UnshadowHttpError(Exception):
+    def __init__(self, status: int, body: Mapping[str, Any] | str) -> None:
+        self.status = status
+        self.body = body
+        super().__init__(f"Unshadow HTTP {status}: {body}")
+
+
+def _parse_body(raw: bytes) -> dict[str, Any]:
+    if not raw:
+        return {}
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return {"raw": raw.decode("utf-8", errors="replace")}
+    return data if isinstance(data, dict) else {"data": data}
+
+
+class UnshadowHttp:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_API_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self.api_key = api_key.strip()
+        self.base_url = (base_url or DEFAULT_API_URL).rstrip("/")
+        self.timeout = timeout
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        payload: Mapping[str, Any] | None = None,
+        *,
+        headers: Mapping[str, str] | None = None,
+        retry: bool = False,
+    ) -> dict[str, Any]:
+        try:
+            return self._once(method, path, payload, headers)
+        except UnshadowHttpError as exc:
+            if not retry or exc.status not in RETRY_STATUSES:
+                raise
+            time.sleep(0.2)
+            return self._once(method, path, payload, headers)
+
+    def _once(
+        self,
+        method: str,
+        path: str,
+        payload: Mapping[str, Any] | None,
+        headers: Mapping[str, str] | None,
+    ) -> dict[str, Any]:
+        url = f"{self.base_url}{path if path.startswith('/') else '/' + path}"
+        data = None if payload is None else json.dumps(dict(payload)).encode("utf-8")
+        req_headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        if data is not None:
+            req_headers["Content-Type"] = "application/json"
+        if headers:
+            req_headers.update(dict(headers))
+        req = urllib.request.Request(url, data=data, method=method.upper(), headers=req_headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return _parse_body(resp.read())
+        except urllib.error.HTTPError as exc:
+            body = _parse_body(exc.read() if exc.fp else b"")
+            raise UnshadowHttpError(int(exc.code), body) from exc
+
+    def post(
+        self,
+        path: str,
+        payload: Mapping[str, Any],
+        *,
+        headers: Mapping[str, str] | None = None,
+        retry: bool = False,
+    ) -> dict[str, Any]:
+        return self.request("POST", path, payload, headers=headers, retry=retry)
+
+    def get(self, path: str, *, retry: bool = False) -> dict[str, Any]:
+        return self.request("GET", path, retry=retry)

unshadow-0.2.0/src/unshadow.egg-info/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: unshadow
+Version: 0.2.0
+Summary: Python client for Unshadow Engine and agent banks.
+Author-email: Unshadow <support@unshadow.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://unshadow.dev
+Project-URL: Documentation, https://unshadow.dev/docs/api/sdk
+Project-URL: Repository, https://github.com/unshadow-ai/unshadow
+Project-URL: Issues, https://github.com/unshadow-ai/unshadow/issues
+Keywords: unshadow,memory,langchain,llamaindex,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.11; extra == "llamaindex"
+Dynamic: license-file
+
+# Unshadow (Python)
+
+Stdlib client for **Unshadow Engine**, plus an agent-bank client. PyPI name: `unshadow`.
+
+```bash
+pip install unshadow
+```
+
+From this repo, before the PyPI upload:
+
+```bash
+pip install ./packages/unshadow
+```
+
+LangChain is optional:
+
+```bash
+pip install "./packages/unshadow[langchain]"
+```
+
+## Engine
+
+`Unshadow` matches the TypeScript SDK: `context`, `search`, `extract`, `forget`, `profile`.
+
+```python
+from unshadow import Unshadow
+
+unshadow = Unshadow(api_key="unshadow_…")
+packed = unshadow.inject_context("What am I working on?", token_budget=1500)
+hits = unshadow.search("pnpm", limit=8, category="preference")
+unshadow.extract(
+    "User prefers pnpm",
+    source_type="ai_conversation",
+    idempotency_key="turn-1",
+)
+unshadow.forget(["11111111-1111-1111-1111-111111111111"])
+```
+
+`extract(..., idempotency_key=)` sends `Idempotency-Key`. Reads retry once on 429/5xx. `extract` retries only when that key is set. A new fact can supersede, contradict, or coexist with an older one. Search rows include `supersedes` and `superseded_by`. `UnshadowRetriever` copies `id`, `category`, `source_type`, and those lists into document metadata. Filter with `unshadow.search("editor", category="preference")`.
+
+### LangChain
+
+```python
+from langchain_unshadow import UnshadowRetriever
+from unshadow import Unshadow
+
+unshadow = Unshadow(api_key="unshadow_…")
+retriever = UnshadowRetriever(client=unshadow, k=8, prefer_context=True)
+docs = retriever.invoke("What did we decide about pnpm?")
+```
+
+`prefer_context` uses `POST /context` and splits `[mem:uuid]` lines. This is not `ConversationBufferMemory`.
+
+### LlamaIndex
+
+```bash
+pip install "./packages/unshadow[llamaindex]"
+```
+
+```python
+from llama_index_unshadow import UnshadowRetriever
+from unshadow import Unshadow
+
+unshadow = Unshadow(api_key="unshadow_…")
+retriever = UnshadowRetriever(unshadow, k=8, prefer_context=True)
+nodes = retriever.retrieve("What did we decide about pnpm?")
+```
+
+## Agent bank
+
+`UnshadowBank` is retain / recall / authorize. Those calls still use `/lattice/*`.
+
+```python
+from unshadow import UnshadowBank
+
+bank = UnshadowBank(api_key="unshadow_…")
+bank.remember("Ship on Fridays is forbidden.", conversation_key="agent-main")
+packed = bank.context("release policy")
+receipt = bank.authorize(["memory-id"], query="deploy production")
+bank.explain(packed["operation_id"])
+```
+
+| Name | HTTP |
+|------|------|
+| `remember` | `POST /lattice/retain` (delta, 32k cap, 409 retry) |
+| `explain` | `POST /lattice/explain` |
+| `authorize` | `POST /lattice/recall` with `purpose: tool_arg` |
+
+`retain` is an alias of `remember`. Hermes still uses `packages/lattice-hermes`.
+
+The bank client does not ingest files. Capture stores pages and repo notes. Link that project into the agent bank. `remember(..., source_url=...)` cites a URL.
+
+## Tests
+
+```bash
+python -m unittest discover -s packages/unshadow/tests
+```

unshadow-0.2.0/src/unshadow.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+src/langchain_unshadow/__init__.py
+src/langchain_unshadow/retriever.py
+src/llama_index_unshadow/__init__.py
+src/llama_index_unshadow/retriever.py
+src/unshadow/__init__.py
+src/unshadow/bank.py
+src/unshadow/client.py
+src/unshadow/documents.py
+src/unshadow/http.py
+src/unshadow.egg-info/PKG-INFO
+src/unshadow.egg-info/SOURCES.txt
+src/unshadow.egg-info/dependency_links.txt
+src/unshadow.egg-info/requires.txt
+src/unshadow.egg-info/top_level.txt
+tests/test_client.py
+tests/test_engine.py
+tests/test_llama.py
+tests/test_retriever.py

unshadow-0.2.0/src/unshadow.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

unshadow-0.2.0/src/unshadow.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[langchain]
+langchain-core>=0.3
+
+[llamaindex]
+llama-index-core>=0.11

unshadow-0.2.0/src/unshadow.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+langchain_unshadow
+llama_index_unshadow
+unshadow

unshadow-0.2.0/tests/test_client.py

@@ -0,0 +1,83 @@
+"""Public Unshadow Python client tests (no network)."""
+
+from __future__ import annotations
+
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+ROOT = Path(__file__).resolve().parents[1] / "src"
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from unshadow.bank import UnshadowBank
+from unshadow.http import UnshadowHttpError
+
+
+class RememberExplainAuthorizeTests(unittest.TestCase):
+    def test_remember_posts_retain_with_source_url(self) -> None:
+        client = UnshadowBank("unshadow_test", base_url="https://api.example/v1")
+        with patch.object(client, "post", return_value={"checkpoint": {"hash": "h"}}) as post:
+            client.remember(
+                "Design decision lives in the spec",
+                conversation_key="agent",
+                source_url="https://capture.example/doc",
+                source_type="link",
+            )
+        post.assert_called_once_with(
+            "/lattice/retain",
+            {
+                "text": "Design decision lives in the spec",
+                "conversation_key": "agent",
+                "source_type": "link",
+                "source_url": "https://capture.example/doc",
+            },
+        )
+
+    def test_remember_retries_on_checkpoint_mismatch(self) -> None:
+        client = UnshadowBank("unshadow_test")
+        conflict = UnshadowHttpError(409, {"error": {"expected_hash": "abc", "code": "conflict"}})
+        with patch.object(
+            client,
+            "post",
+            side_effect=[conflict, {"checkpoint": {"hash": "abc"}}],
+        ) as post:
+            out = client.remember("delta", conversation_key="s1", prev_hash="stale")
+        self.assertEqual(out["checkpoint"]["hash"], "abc")
+        self.assertEqual(post.call_count, 2)
+        self.assertEqual(post.call_args_list[1].args[1]["prev_hash"], "abc")
+
+    def test_authorize_forces_tool_arg(self) -> None:
+        client = UnshadowBank("unshadow_test")
+        with patch.object(
+            client,
+            "post",
+            return_value={"grounding_ok": False, "omitted": [{"reason": "stale"}]},
+        ) as post:
+            out = client.authorize(["m1"], query="run deploy")
+        self.assertFalse(out["grounding_ok"])
+        post.assert_called_once_with(
+            "/lattice/recall",
+            {
+                "query": "run deploy",
+                "purpose": "tool_arg",
+                "memory_ids": ["m1"],
+            },
+        )
+
+    def test_explain_posts_operation_id(self) -> None:
+        client = UnshadowBank("unshadow_test")
+        with patch.object(client, "post", return_value={"events": []}) as post:
+            client.explain("op-1")
+        post.assert_called_once_with("/lattice/explain", {"operation_id": "op-1"})
+
+    def test_retain_is_remember_alias(self) -> None:
+        client = UnshadowBank("k")
+        with patch.object(client, "remember", return_value={"ok": True}) as remember:
+            client.retain("x", conversation_key="c")
+        remember.assert_called_once()
+
+
+if __name__ == "__main__":
+    unittest.main()

unshadow-0.2.0/tests/test_engine.py

@@ -0,0 +1,92 @@
+"""Engine client tests (no network)."""
+
+from __future__ import annotations
+
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+ROOT = Path(__file__).resolve().parents[1] / "src"
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from unshadow.client import Unshadow
+from unshadow.documents import documents_from_context, documents_from_search
+from unshadow.http import UnshadowHttpError
+
+
+class EngineTests(unittest.TestCase):
+    def test_search_category_and_context(self) -> None:
+        client = Unshadow("unshadow_test", base_url="https://api.example/v1")
+        with patch.object(client, "request", return_value={"memories": []}) as request:
+            client.search("pnpm", limit=8, category="preference")
+            client.context("task", token_budget=1500)
+        self.assertEqual(request.call_args_list[0].args[0], "GET")
+        self.assertIn("category=preference", request.call_args_list[0].args[1])
+        self.assertTrue(request.call_args_list[0].kwargs["retry"])
+        self.assertEqual(request.call_args_list[1].args[:2], ("POST", "/context"))
+
+    def test_extract_sends_idempotency_header_not_body(self) -> None:
+        client = Unshadow("k", base_url="https://api.example/v1")
+        with patch.object(client, "request", return_value={"stored": 1}) as request:
+            client.extract("User prefers pnpm", source_type="ai_conversation", idempotency_key="turn-1")
+        args, kwargs = request.call_args
+        self.assertEqual(args[:2], ("POST", "/extract"))
+        self.assertNotIn("idempotency_key", args[2])
+        self.assertEqual(kwargs["headers"]["Idempotency-Key"], "turn-1")
+        self.assertTrue(kwargs["retry"])
+
+    def test_forget_posts_memory_ids(self) -> None:
+        client = Unshadow("k")
+        with patch.object(client, "post", return_value={"deleted": 1}) as post:
+            client.forget(["m1"])
+        post.assert_called_once_with("/forget-memories", {"memory_ids": ["m1"]})
+
+    def test_search_retries_once(self) -> None:
+        client = Unshadow("k", base_url="https://api.example/v1")
+        with patch.object(
+            client,
+            "_once",
+            side_effect=[UnshadowHttpError(429, "slow"), {"memories": []}],
+        ) as once:
+            out = client.get("/search?query=a", retry=True)
+        self.assertEqual(out, {"memories": []})
+        self.assertEqual(once.call_count, 2)
+
+    def test_documents_from_search_and_context(self) -> None:
+        docs = documents_from_search(
+            {
+                "memories": [
+                    {
+                        "id": "m1",
+                        "fact": "User prefers pnpm",
+                        "category": "preference",
+                        "source_type": "ai_conversation",
+                        "supersedes": ["old"],
+                        "superseded_by": [],
+                    }
+                ]
+            }
+        )
+        self.assertEqual(docs[0]["page_content"], "User prefers pnpm")
+        self.assertEqual(docs[0]["metadata"]["id"], "m1")
+        self.assertEqual(docs[0]["metadata"]["category"], "preference")
+        self.assertEqual(docs[0]["metadata"]["source_type"], "ai_conversation")
+        self.assertEqual(docs[0]["metadata"]["supersedes"], ["old"])
+        cited = documents_from_context(
+            "User prefers pnpm [mem:11111111-1111-1111-1111-111111111111]",
+            [
+                {
+                    "memory_id": "11111111-1111-1111-1111-111111111111",
+                    "category": "preference",
+                    "superseded_by": [],
+                }
+            ],
+        )
+        self.assertEqual(cited[0]["metadata"]["id"], "11111111-1111-1111-1111-111111111111")
+        self.assertEqual(cited[0]["metadata"]["category"], "preference")
+
+
+if __name__ == "__main__":
+    unittest.main()

unshadow-0.2.0/tests/test_llama.py

@@ -0,0 +1,49 @@
+"""LlamaIndex retriever tests. Skipped when llama-index-core is not installed."""
+
+from __future__ import annotations
+
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+ROOT = Path(__file__).resolve().parents[1] / "src"
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+try:
+    from llama_index.core.schema import QueryBundle
+    from llama_index_unshadow import UnshadowRetriever
+except ImportError:
+    QueryBundle = None  # type: ignore[misc, assignment]
+    UnshadowRetriever = None  # type: ignore[misc, assignment]
+
+from unshadow.client import Unshadow
+
+
+@unittest.skipIf(UnshadowRetriever is None, "llama-index-core is not installed")
+class LlamaRetrieverTests(unittest.TestCase):
+    def test_retriever_searches_engine(self) -> None:
+        client = Unshadow("k", base_url="https://api.example/v1")
+        with patch.object(
+            client,
+            "search",
+            return_value={
+                "memories": [
+                    {
+                        "id": "m1",
+                        "fact": "User prefers pnpm",
+                        "category": "preference",
+                        "source_type": "ai_conversation",
+                    }
+                ]
+            },
+        ) as search:
+            nodes = UnshadowRetriever(client=client, k=4).retrieve(QueryBundle(query_str="package manager"))
+        search.assert_called_once_with("package manager", limit=4)
+        self.assertEqual(nodes[0].node.get_content(), "User prefers pnpm")
+        self.assertEqual(nodes[0].node.metadata["category"], "preference")
+
+
+if __name__ == "__main__":
+    unittest.main()

unshadow-0.2.0/tests/test_retriever.py

@@ -0,0 +1,49 @@
+"""LangChain retriever tests. Skipped when langchain-core is not installed."""
+
+from __future__ import annotations
+
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+ROOT = Path(__file__).resolve().parents[1] / "src"
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+try:
+    from langchain_unshadow import UnshadowRetriever
+except ImportError:
+    UnshadowRetriever = None  # type: ignore[misc, assignment]
+
+from unshadow.client import Unshadow
+
+
+@unittest.skipIf(UnshadowRetriever is None, "langchain-core is not installed")
+class RetrieverTests(unittest.TestCase):
+    def test_retriever_searches_engine(self) -> None:
+        client = Unshadow("k", base_url="https://api.example/v1")
+        with patch.object(
+            client,
+            "search",
+            return_value={"memories": [{"id": "m1", "fact": "User prefers pnpm", "category": "preference"}]},
+        ) as search:
+            docs = UnshadowRetriever(client=client, k=4).invoke("package manager")
+        search.assert_called_once_with("package manager", limit=4)
+        self.assertEqual(docs[0].page_content, "User prefers pnpm")
+        self.assertEqual(docs[0].metadata["category"], "preference")
+
+    def test_prefer_context(self) -> None:
+        client = Unshadow("k")
+        with patch.object(
+            client,
+            "context",
+            return_value={"context": "pnpm [mem:11111111-1111-1111-1111-111111111111]"},
+        ):
+            docs = UnshadowRetriever(client=client, prefer_context=True).invoke("tooling")
+        self.assertEqual(docs[0].page_content, "pnpm")
+        self.assertEqual(docs[0].metadata["id"], "11111111-1111-1111-1111-111111111111")
+
+
+if __name__ == "__main__":
+    unittest.main()