mayamemo 0.1.0__py3-none-any.whl

mayamemo/__init__.py

@@ -0,0 +1,7 @@
+"""MayaMemo Python SDK."""
+
+from .client import MayaMemo, MayaMemoError
+from .integrations import MayaMemoMemory, MayaMemoRetriever
+
+__all__ = ["MayaMemo", "MayaMemoError", "MayaMemoMemory", "MayaMemoRetriever"]
+__version__ = "0.1.0"

mayamemo/client.py

@@ -0,0 +1,284 @@
+"""MayaMemo Python SDK — thin, zero-dependency client for the MayaMemo API.
+
+    pip install -e sdk/python   (or copy the `mayamemo/` package — no deps)
+
+Quickstart:
+    from mayamemo import MayaMemo
+    client = MayaMemo(api_key="mm_sk_...", api_url="http://localhost:4000")
+    project = client.create_project("my-app")
+    client.add_memory(project["id"], "Retries go through an idempotency table", type="decision",
+                      tags=["checkout"])
+    hits = client.search_memories(project["id"], "how do we avoid double charges?")
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+__all__ = ["MayaMemo", "MayaMemoError"]
+
+__version__ = "0.1.0"
+
+
+class MayaMemoError(Exception):
+    """Branded API error: {status} {code}: {message} — request_id for support.
+
+    `details` carries any structured extras the API attached, e.g. a 409
+    DUPLICATE_MEMORY ships `{"duplicate_of": "<memory id>"}`.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        request_id: str | None = None,
+        details: dict[str, Any] | None = None,
+    ):
+        super().__init__(f"{status} {code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.details = details or {}
+
+    @property
+    def duplicate_of(self) -> str | None:
+        value = self.details.get("duplicate_of")
+        return value if isinstance(value, str) else None
+
+
+class MayaMemo:
+    """Synchronous zero-dependency client. Auth: workspace API key (mm_sk_…)."""
+
+    def __init__(self, api_key: str | None = None, api_url: str | None = None, timeout: float = 60.0):
+        self.api_key = api_key or os.environ.get("MAYAMEMO_API_KEY") or os.environ.get("MAYAMEMO_TOKEN")
+        if not self.api_key:
+            raise ValueError("api_key is required (or set MAYAMEMO_API_KEY / MAYAMEMO_TOKEN)")
+        self.api_url = (api_url or os.environ.get("MAYAMEMO_API_URL") or "http://localhost:4000").rstrip("/")
+        self.timeout = timeout
+
+    # ------------------------------------------------------------------ HTTP
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        url = f"{self.api_url}{path}"
+        if params:
+            clean = {k: v for k, v in params.items() if v is not None}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean, doseq=True)
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("Authorization", f"Bearer {self.api_key}")
+        req.add_header("Accept", "application/json")
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                raw = res.read().decode()
+                return json.loads(raw) if raw.strip() else None
+        except urllib.error.HTTPError as exc:
+            raw = exc.read().decode(errors="replace")
+            code, message, request_id, details = "HTTP_ERROR", raw[:300], None, {}
+            try:
+                err = dict((json.loads(raw) or {}).get("error") or {})
+                code = err.pop("code", code)
+                message = err.pop("message", message)
+                request_id = err.pop("request_id", None)
+                details = err
+            except ValueError:
+                pass
+            raise MayaMemoError(exc.code, code, message, request_id, details) from None
+
+    # -------------------------------------------------------------- projects
+
+    def list_projects(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/v1/projects")
+
+    def create_project(self, name: str, description: str | None = None) -> dict[str, Any]:
+        body: dict[str, Any] = {"name": name}
+        if description is not None:
+            body["description"] = description
+        return self._request("POST", "/v1/projects", body)
+
+    # -------------------------------------------------------------- memories
+
+    def add_memory(
+        self,
+        project_id: str,
+        statement: str,
+        *,
+        type: str = "fact",  # noqa: A002 - mirrors the API field name
+        tags: list[str] | None = None,
+        confidence: float | None = None,
+        importance: float | None = None,
+        authority: str | None = None,
+        source_session_id: str | None = None,
+        source_event_id: str | None = None,
+        entities: list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"project_id": project_id, "statement": statement, "type": type}
+        for key, value in (
+            ("tags", tags),
+            ("confidence", confidence),
+            ("importance", importance),
+            ("authority", authority),
+            ("source_session_id", source_session_id),
+            ("source_event_id", source_event_id),
+            ("entities", entities),
+        ):
+            if value is not None:
+                body[key] = value
+        return self._request("POST", "/v1/memories", body)
+
+    def search_memories(
+        self,
+        project_id: str,
+        query: str,
+        *,
+        tags: list[str] | None = None,
+        limit: int = 10,
+        status: str | None = None,
+    ) -> list[dict[str, Any]]:
+        body: dict[str, Any] = {"project_id": project_id, "query": query, "limit": limit}
+        if tags:
+            body["tags"] = tags
+        if status:
+            body["status"] = status
+        return self._request("POST", "/v1/memories/search", body)
+
+    def list_memories(
+        self,
+        project_id: str,
+        *,
+        tag: str | None = None,
+        type: str | None = None,  # noqa: A002
+        status: str | None = None,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        return self._request(
+            "GET",
+            "/v1/memories",
+            params={"project_id": project_id, "tag": tag, "type": type, "status": status, "limit": limit},
+        )
+
+    def patch_memory(self, memory_id: str, **changes: Any) -> dict[str, Any]:
+        return self._request("PATCH", f"/v1/memories/{memory_id}", changes)
+
+    # ----------------------------------------------------------- checkpoints
+
+    def create_checkpoint(
+        self,
+        project_id: str,
+        title: str,
+        summary: str,
+        *,
+        next_steps: list[str] | None = None,
+        blockers: list[str] | None = None,
+        agent: str | None = None,
+        session_id: str | None = None,
+        token_budget: int | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"project_id": project_id, "title": title, "summary": summary}
+        for key, value in (
+            ("next_steps", next_steps),
+            ("blockers", blockers),
+            ("agent", agent),
+            ("session_id", session_id),
+            ("token_budget", token_budget),
+        ):
+            if value is not None:
+                body[key] = value
+        return self._request("POST", "/v1/checkpoints", body)
+
+    def list_checkpoints(self, project_id: str) -> list[dict[str, Any]]:
+        data = self._request("GET", f"/v1/projects/{project_id}/checkpoints")
+        return (data or {}).get("checkpoints", [])
+
+    def resume_checkpoint(self, checkpoint_id: str, *, agent: str) -> dict[str, Any]:
+        """Resume as `agent` (any agent key). Returns checkpoint, resumed_session and briefing_markdown."""
+        return self._request("POST", f"/v1/checkpoints/{checkpoint_id}/resume", {"agent": agent})
+
+    # --------------------------------------------------------------- context
+
+    def compile_context(
+        self,
+        project_id: str,
+        title: str,
+        *,
+        description: str | None = None,
+        token_budget: int | None = None,
+        branch: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"project_id": project_id, "title": title}
+        for key, value in (("description", description), ("token_budget", token_budget), ("branch", branch)):
+            if value is not None:
+                body[key] = value
+        return self._request("POST", "/v1/context/compile", body)
+
+    # ----------------------------------------------------------------- graph
+
+    def observe_entities(
+        self,
+        project_id: str,
+        entities: list[dict[str, Any]],
+        relations: list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        """Observe code entities + relations (idempotent by kind+name).
+
+        entities: [{"kind": "file", "name": "src/cart.js"}, ...] (max 50)
+        relations: [{"source": {...}, "target": {...}, "kind": "imports"}, ...] (max 100)
+        """
+        body: dict[str, Any] = {"project_id": project_id, "entities": entities}
+        if relations:
+            body["relations"] = relations
+        return self._request("POST", "/v1/entities/observe", body)
+
+    def list_entities(
+        self,
+        project_id: str,
+        *,
+        kind: str | None = None,
+        q: str | None = None,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        data = self._request(
+            "GET",
+            f"/v1/projects/{project_id}/entities",
+            params={"kind": kind, "q": q, "limit": limit},
+        )
+        return (data or {}).get("entities", [])
+
+    def get_entity(self, entity_id: str) -> dict[str, Any]:
+        """Entity detail: relations (direction, other) + linked active memories."""
+        return self._request("GET", f"/v1/entities/{entity_id}")
+
+    def entity_neighbors(self, entity_id: str, *, depth: int = 1) -> dict[str, Any]:
+        """BFS over relations (depth 1..2): {root, nodes, edges, truncated}."""
+        return self._request("GET", f"/v1/entities/{entity_id}/neighbors", params={"depth": depth})
+
+    # ---------------------------------------------------------------- events
+
+    def list_events(self, project_id: str, *, limit: int = 50, cursor: int | None = None) -> dict[str, Any]:
+        return self._request(
+            "GET", f"/v1/projects/{project_id}/events", params={"limit": limit, "cursor": cursor}
+        )
+
+    # ----------------------------------------------------------------- misc
+
+    @classmethod
+    def public_status(cls, api_url: str | None = None, timeout: float = 15.0) -> dict[str, Any]:
+        """Public /v1/status — no API key required."""
+        url = (api_url or os.environ.get("MAYAMEMO_API_URL") or "http://localhost:4000").rstrip("/")
+        with urllib.request.urlopen(urllib.request.Request(f"{url}/v1/status"), timeout=timeout) as res:
+            return json.loads(res.read().decode())

mayamemo/integrations.py

@@ -0,0 +1,147 @@
+"""Framework adapters — LangChain-style retriever + chat memory.
+
+Duck-typed by design: if `langchain-core` is installed these subclass the real
+base classes (true drop-in); if not, they still work standalone and the module
+imports without any dependency.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .client import MayaMemo
+
+try:  # optional — real LangChain integration when present
+    from langchain_core.memory import BaseMemory as _LCBaseMemory  # type: ignore[import-not-found]
+except Exception:  # pragma: no cover - exercised implicitly everywhere langchain is absent
+    _LCBaseMemory = object  # type: ignore[assignment,misc]
+
+try:
+    from langchain_core.retrievers import BaseRetriever as _LCBaseRetriever  # type: ignore[import-not-found]
+except Exception:  # pragma: no cover
+    _LCBaseRetriever = object  # type: ignore[assignment,misc]
+
+__all__ = ["MayaMemoRetriever", "MayaMemoMemory"]
+
+
+class MayaMemoRetriever(_LCBaseRetriever):  # type: ignore[misc]
+    """Retrieve project memories as documents for RAG-style prompt building."""
+
+    def __init__(self, client: MayaMemo, project_id: str, *, limit: int = 8, tags: list[str] | None = None):
+        self._client = client
+        self._project_id = project_id
+        self._limit = limit
+        self._tags = tags
+
+    def _to_document(self, hit: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "page_content": hit.get("statement", ""),
+            "metadata": {
+                "id": hit.get("id"),
+                "type": hit.get("type"),
+                "tags": hit.get("tags", []),
+                "confidence": hit.get("confidence"),
+                "importance": hit.get("importance"),
+                "score": hit.get("score"),
+                "created_at": hit.get("createdAt"),
+            },
+        }
+
+    def invoke(self, query: Any, config: Any = None) -> list[dict[str, Any]]:
+        q = query if isinstance(query, str) else str((query or {}).get("query", ""))
+        return self._get_relevant_documents(q)
+
+    def _get_relevant_documents(self, query: str, **kwargs: Any) -> list[dict[str, Any]]:
+        hits = self._client.search_memories(
+            self._project_id, query, limit=self._limit, tags=self._tags
+        )
+        return [self._to_document(hit) for hit in hits]
+
+    def get_relevant_documents(self, query: str) -> list[dict[str, Any]]:  # legacy LangChain name
+        return self._get_relevant_documents(query)
+
+
+class MayaMemoMemory(_LCBaseMemory):  # type: ignore[misc]
+    """Chat-memory adapter: load compiles project context; save records the exchange.
+
+    The MayaMemo ledger is append-only by design — `clear()` cannot delete history;
+    it resets only local buffering (documented behavior, not a bug).
+    """
+
+    memory_variables: list[str] = ["mayamemo_context"]
+
+    def __init__(
+        self,
+        client: MayaMemo,
+        project_id: str,
+        *,
+        token_budget: int = 4000,
+        query_key: str = "input",
+        memory_type: str = "discovery",
+        tags: list[str] | None = None,
+    ):
+        self._client = client
+        self._project_id = project_id
+        self._token_budget = token_budget
+        self._query_key = query_key
+        self._memory_type = memory_type
+        self._tags = tags or ["langchain"]
+
+    # -- BaseMemory surface -------------------------------------------------
+
+    def load_memory_variables(self, inputs: dict[str, Any]) -> dict[str, Any]:
+        query = str(inputs.get(self._query_key) or inputs.get("question") or "").strip()
+        if not query:
+            return {"mayamemo_context": ""}
+        try:
+            compiled = self._client.compile_context(
+                self._project_id, query, token_budget=self._token_budget
+            )
+        except Exception:  # never break the host chain on a context hiccup
+            return {"mayamemo_context": ""}
+        lines: list[str] = []
+        for item in compiled.get("items", []):
+            reason = item.get("reason") or {}
+            preview = reason.get("preview") or item.get("statement") or ""
+            if preview:
+                lines.append(f"- [{item.get('source_type', 'item')}] {preview}")
+        return {"mayamemo_context": "\n".join(lines)}
+
+    def save_context(self, inputs: dict[str, Any], outputs: dict[str, Any]) -> None:
+        statement = self._summarize(inputs, outputs)
+        if not statement:
+            return
+        try:
+            self._client.add_memory(
+                self._project_id,
+                statement[:2000],
+                type=self._memory_type,
+                tags=self._tags,
+                authority="model",
+            )
+        except Exception:  # best-effort, like all memory capture
+            pass
+
+    def clear(self) -> None:
+        """No-op: the ledger is append-only. Kept for interface compatibility."""
+
+    # -- helpers ------------------------------------------------------------
+
+    @staticmethod
+    def _stringify(value: Any) -> str:
+        if isinstance(value, str):
+            return value
+        if isinstance(value, list):
+            return " / ".join(MayaMemoMemory._stringify(v) for v in value)
+        if isinstance(value, dict):
+            return json.dumps(value, ensure_ascii=False)
+        return str(value)
+
+    def _summarize(self, inputs: dict[str, Any], outputs: dict[str, Any]) -> str:
+        user = self._stringify(inputs.get(self._query_key) or inputs.get("question") or "")
+        reply = self._stringify(outputs.get("output") or outputs.get("answer") or outputs)
+        user, reply = user.strip(), reply.strip()
+        if not user and not reply:
+            return ""
+        return f"Exchange — user: {user[:400]} · assistant: {reply[:800]}"

mayamemo-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: mayamemo
+Version: 0.1.0
+Summary: MayaMemo Python SDK — evidence-backed context, memories and cross-agent checkpoints for AI coding agents. Zero dependencies.
+Author: MayaMemo
+License: MIT
+Project-URL: Homepage, https://github.com/Coin1511/mayamemo
+Project-URL: Repository, https://github.com/Coin1511/mayamemo/tree/main/sdk/python
+Keywords: mayamemo,ai-agents,memory,context,checkpoints,mcp
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+Dynamic: license-file
+
+# MayaMemo — Python SDK
+
+Zero-dependency Python client for the [MayaMemo](../..) API: projects, memories
+(with tags), semantic search, the context compiler, checkpoints and cross-agent resume.
+
+```bash
+# from the repo
+pip install -e sdk/python        # or: pip install -e "sdk/python[langchain]"
+```
+
+## Quickstart
+
+```python
+from mayamemo import MayaMemo
+
+client = MayaMemo(api_key="mm_sk_...", api_url="http://localhost:4000")
+
+project = client.create_project("my-app")
+
+client.add_memory(
+    project["id"],
+    "Checkout retries go through an idempotency table keyed by cart_id + attempt",
+    type="decision",
+    tags=["checkout", "billing"],
+)
+
+hits = client.search_memories(project["id"], "how do we avoid double charges?")
+print(hits[0]["statement"], hits[0]["score"])
+
+checkpoint = client.create_checkpoint(
+    project["id"], "billing groundwork",
+    "Idempotency decision captured; outbox worker noted.",
+    next_steps=["wire refund metrics"], agent="my-agent",
+)
+
+briefing = client.resume_checkpoint(checkpoint["id"], agent="another-agent")["briefing_markdown"]
+print(briefing)
+```
+
+Environment defaults: `MAYAMEMO_API_KEY` (or `MAYAMEMO_TOKEN`) and `MAYAMEMO_API_URL`
+(`http://localhost:4000`). API keys are created in the workspace (`POST /v1/keys`),
+scoped per workspace and revocable.
+
+## Framework adapters
+
+`mayamemo.integrations` ships a LangChain-style retriever and chat-memory adapter.
+They subclass the real `langchain-core` classes when it is installed (true drop-in)
+and work standalone otherwise.
+
+```python
+from mayamemo import MayaMemo, MayaMemoRetriever, MayaMemoMemory
+
+retriever = MayaMemoRetriever(client, project["id"], tags=["checkout"])
+docs = retriever.invoke("how do retries work?")        # [{page_content, metadata}, …]
+
+memory = MayaMemoMemory(client, project["id"])         # BaseMemory-compatible
+memory.load_memory_variables({"input": "how do deploys work?"})  # {"mayamemo_context": "…"}
+memory.save_context({"input": "…"}, {"output": "…"})    # recorded as a `discovery` memory
+```
+
+`MayaMemoMemory.clear()` is a no-op by design — the MayaMemo ledger is append-only
+(use retention windows or supersession; history is evidence).
+
+## Tests
+
+Live tests run against a real API (they skip without a key):
+
+```bash
+cd sdk/python
+MAYAMEMO_TEST_KEY_FILE=/path/to/.ctxkey python -m pytest tests -q
+```
+
+Each run creates its own project (`sdk-suite-<run>`) — semantic dedupe (0.92 cosine)
+correctly treats near-identical statements as duplicates, so per-run isolation keeps
+re-runs meaningful. Point the test key at a workspace with project-quota headroom
+(the runs consume project slots by design). `examples/quickstart.py` is idempotent:
+a duplicate is reported as `already captured — semantic dedupe` and reused.
+
+## Coverage
+
+`projects` · `memories` (add / search / list / patch / tags) · `compile_context` ·
+`checkpoints` (create / list / resume) · `events` · `public_status` · branded
+`MayaMemoError(status, code, message, request_id)` on every non-2xx.

mayamemo-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mayamemo/__init__.py,sha256=R_tDdarPEl2-TKTbG8zYS_t-YNi-51j9B3yABKjj5kY,234
+mayamemo/client.py,sha256=5KBQDwpjJ2vjLVhJgKFLy4sUWrBK_nDWsA_ZputDIu0,10896
+mayamemo/integrations.py,sha256=aIrUitXqvyUw7-BP3sS7CQhFss_8AbXYrDLw_Nsji9Q,5761
+mayamemo-0.1.0.dist-info/licenses/LICENSE,sha256=aqJQLMTP-zx3yi6Is0mwUPdhtiOASiamQjbzWMoA7s4,1065
+mayamemo-0.1.0.dist-info/METADATA,sha256=agMNPiUECaZJoSKRrOgH34vJ_x1lzoBZRscc_3ZkqDU,3926
+mayamemo-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mayamemo-0.1.0.dist-info/top_level.txt,sha256=JMvWa37JFkZloMR7HKZ-LpygTv6vPWJQtg-Rzmr1gZA,9
+mayamemo-0.1.0.dist-info/RECORD,,

mayamemo-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
+

mayamemo-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MayaMemo
+
+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.

mayamemo-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mayamemo