cubememory 0.1.0__tar.gz

cubememory-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: cubememory
+Version: 0.1.0
+Summary: Official Python SDK for Cube Memory — semantic search with 100% exact recall
+Author-email: Ronny Guerreiro <ynnor.guerreiro@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://cubememory.com.br
+Project-URL: Documentation, https://cubememory.com.br/docs
+Project-URL: Repository, https://github.com/cubememory/sdk-python
+Keywords: vector-search,semantic-search,rag,llm-memory,mcp,cube-memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: async
+Requires-Dist: httpx>=0.25; extra == "async"
+Provides-Extra: all
+Requires-Dist: httpx>=0.25; extra == "all"

cubememory-0.1.0/cubememory/__init__.py

@@ -0,0 +1,24 @@
+"""
+cubememory — Python SDK for Cube Memory
+Semantic search with 100% exact recall · isolated islands · self-hosted
+"""
+
+from .client import CubeClient, createCubeClient
+from .index import IndexClient, SearchResult, InsertResult
+from .memory import MemoryClient
+from .notes import NotesClient, Note, NoteDetail
+from .exceptions import CubeError
+
+__version__ = "0.1.0"
+__all__ = [
+    "CubeClient",
+    "createCubeClient",
+    "IndexClient",
+    "MemoryClient",
+    "NotesClient",
+    "SearchResult",
+    "InsertResult",
+    "Note",
+    "NoteDetail",
+    "CubeError",
+]

cubememory-0.1.0/cubememory/client.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .http import SyncHttp, AsyncHttp
+from .index import IndexClient, AsyncIndexClient
+from .memory import MemoryClient, AsyncMemoryClient
+from .notes import NotesClient, AsyncNotesClient
+
+
+class CubeClient:
+    """Synchronous Cube Memory client.
+
+    Usage::
+
+        from cubememory import CubeClient
+
+        cube = CubeClient(
+            base_url="https://cubememory.com.br/gateway",
+            api_key="cm_live_xxx",
+            project_id="proj_xxx",
+        )
+
+        # Semantic search (100% exact recall)
+        results = cube.index("my-docs").search("calçado esportivo", limit=10)
+
+        # LLM Memory
+        cube.memory.store("User prefers dark mode")
+        ctx = cube.memory.search("user preferences")
+
+        # PKM Notes
+        cube.notes.upsert("Meeting Notes", "Discussed Q3 roadmap", tags=["meeting"])
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        project_id: str = "",
+        timeout: float = 30.0,
+    ) -> None:
+        self._http = SyncHttp(base_url, api_key, project_id, timeout)
+        self.memory = MemoryClient(self._http)
+        self.notes = NotesClient(self._http)
+
+    def index(self, name: str) -> IndexClient:
+        return IndexClient(name, self._http)
+
+    def ping(self) -> bool:
+        try:
+            self._http.get("/v1/health")
+            return True
+        except Exception:
+            return False
+
+
+class AsyncCubeClient:
+    """Async Cube Memory client (requires httpx).
+
+    Usage::
+
+        from cubememory import AsyncCubeClient
+
+        cube = AsyncCubeClient(
+            base_url="https://cubememory.com.br/gateway",
+            api_key="cm_live_xxx",
+            project_id="proj_xxx",
+        )
+
+        results = await cube.index("my-docs").search("calçado esportivo")
+        await cube.memory.store("User prefers dark mode")
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        project_id: str = "",
+        timeout: float = 30.0,
+    ) -> None:
+        self._http = AsyncHttp(base_url, api_key, project_id, timeout)
+        self.memory = AsyncMemoryClient(self._http)
+        self.notes = AsyncNotesClient(self._http)
+
+    def index(self, name: str) -> AsyncIndexClient:
+        return AsyncIndexClient(name, self._http)
+
+    async def ping(self) -> bool:
+        try:
+            await self._http.get("/v1/health")
+            return True
+        except Exception:
+            return False
+
+
+def createCubeClient(
+    base_url: str,
+    api_key: str,
+    project_id: str = "",
+    *,
+    async_mode: bool = False,
+    timeout: float = 30.0,
+) -> "CubeClient | AsyncCubeClient":
+    """Factory function — similar to Supabase's createClient().
+
+    Args:
+        base_url: Gateway URL, e.g. "https://cubememory.com.br/gateway"
+        api_key:  Your API key (cm_live_xxx)
+        project_id: Your project ID (proj_xxx)
+        async_mode: Set True to get AsyncCubeClient (requires httpx)
+        timeout: Request timeout in seconds
+
+    Returns:
+        CubeClient (sync) or AsyncCubeClient (async)
+    """
+    if async_mode:
+        return AsyncCubeClient(base_url, api_key, project_id, timeout)
+    return CubeClient(base_url, api_key, project_id, timeout)

cubememory-0.1.0/cubememory/exceptions.py

@@ -0,0 +1,8 @@
+class CubeError(Exception):
+    def __init__(self, status: int, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+    def __repr__(self) -> str:
+        return f"CubeError(status={self.status}, message={self.message!r})"

cubememory-0.1.0/cubememory/http.py

@@ -0,0 +1,82 @@
+"""HTTP client — sync (requests) + async (httpx) backends."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .exceptions import CubeError
+
+try:
+    import httpx
+    _HAS_HTTPX = True
+except ImportError:
+    _HAS_HTTPX = False
+
+try:
+    import requests as _requests
+    _HAS_REQUESTS = True
+except ImportError:
+    _HAS_REQUESTS = False
+
+
+class SyncHttp:
+    def __init__(self, base_url: str, api_key: str, project_id: str, timeout: float = 30.0) -> None:
+        if not _HAS_REQUESTS:
+            raise ImportError("Install 'requests' for sync usage: pip install cubememory[sync]")
+        self._base = base_url.rstrip("/")
+        self._headers = {
+            "Authorization": f"Bearer {api_key}",
+            "X-Project-Id": project_id,
+            "Content-Type": "application/json",
+        }
+        self._timeout = timeout
+
+    def get(self, path: str) -> Any:
+        r = _requests.get(f"{self._base}{path}", headers=self._headers, timeout=self._timeout)
+        if not r.ok:
+            raise CubeError(r.status_code, r.text)
+        return r.json()
+
+    def post(self, path: str, body: Dict[str, Any]) -> Any:
+        r = _requests.post(f"{self._base}{path}", json=body, headers=self._headers, timeout=self._timeout)
+        if not r.ok:
+            raise CubeError(r.status_code, r.text)
+        return r.json()
+
+    def delete(self, path: str) -> None:
+        r = _requests.delete(f"{self._base}{path}", headers=self._headers, timeout=self._timeout)
+        if not r.ok:
+            raise CubeError(r.status_code, r.text)
+
+
+class AsyncHttp:
+    def __init__(self, base_url: str, api_key: str, project_id: str, timeout: float = 30.0) -> None:
+        if not _HAS_HTTPX:
+            raise ImportError("Install 'httpx' for async usage: pip install cubememory[async]")
+        self._base = base_url.rstrip("/")
+        self._headers = {
+            "Authorization": f"Bearer {api_key}",
+            "X-Project-Id": project_id,
+            "Content-Type": "application/json",
+        }
+        self._timeout = timeout
+
+    async def get(self, path: str) -> Any:
+        async with httpx.AsyncClient(timeout=self._timeout) as c:
+            r = await c.get(f"{self._base}{path}", headers=self._headers)
+            if not r.is_success:
+                raise CubeError(r.status_code, r.text)
+            return r.json()
+
+    async def post(self, path: str, body: Dict[str, Any]) -> Any:
+        async with httpx.AsyncClient(timeout=self._timeout) as c:
+            r = await c.post(f"{self._base}{path}", json=body, headers=self._headers)
+            if not r.is_success:
+                raise CubeError(r.status_code, r.text)
+            return r.json()
+
+    async def delete(self, path: str) -> None:
+        async with httpx.AsyncClient(timeout=self._timeout) as c:
+            r = await c.delete(f"{self._base}{path}", headers=self._headers)
+            if not r.is_success:
+                raise CubeError(r.status_code, r.text)

cubememory-0.1.0/cubememory/index.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+
+from .http import SyncHttp, AsyncHttp
+
+
+@dataclass
+class SearchResult:
+    id: str
+    score: float
+    text_preview: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def _from(cls, d: Dict[str, Any]) -> "SearchResult":
+        return cls(
+            id=d.get("id", ""),
+            score=d.get("score", 0.0),
+            text_preview=d.get("text_preview", ""),
+            metadata=d.get("metadata", {}),
+        )
+
+
+@dataclass
+class InsertResult:
+    status: str
+    id: str
+    docs_total: Optional[int] = None
+
+    @classmethod
+    def _from(cls, d: Dict[str, Any]) -> "InsertResult":
+        return cls(status=d.get("status", "ok"), id=d.get("id", ""), docs_total=d.get("docs_total"))
+
+
+# ─── Sync ─────────────────────────────────────────────────────────────────────
+
+class IndexClient:
+    def __init__(self, name: str, http: SyncHttp) -> None:
+        self._name = name
+        self._http = http
+
+    def insert(self, id: str, text: str, metadata: Optional[Dict[str, Any]] = None) -> InsertResult:
+        body: Dict[str, Any] = {"id": id, "text": text}
+        if metadata:
+            body["metadata"] = metadata
+        return InsertResult._from(self._http.post(f"/v1/indexes/{self._name}/insert", body))
+
+    def insert_many(self, docs: List[Dict[str, Any]]) -> Dict[str, Any]:
+        return self._http.post(f"/v1/indexes/{self._name}/batch", {"docs": docs})
+
+    def search(
+        self,
+        query: str,
+        limit: int = 10,
+        threshold: Optional[float] = None,
+        filter: Optional[Dict[str, Any]] = None,
+    ) -> List[SearchResult]:
+        body: Dict[str, Any] = {"query": query, "limit": limit}
+        if threshold is not None:
+            body["threshold"] = threshold
+        if filter:
+            body["filter"] = filter
+        data = self._http.post(f"/v1/indexes/{self._name}/search", body)
+        return [SearchResult._from(r) for r in data.get("results", [])]
+
+    def get(self, id: str) -> Optional[Dict[str, Any]]:
+        try:
+            return self._http.get(f"/v1/indexes/{self._name}/docs/{id}")
+        except Exception:
+            return None
+
+    def delete(self, id: str) -> None:
+        self._http.delete(f"/v1/indexes/{self._name}/docs/{id}")
+
+    def stats(self) -> Dict[str, Any]:
+        return self._http.get(f"/v1/indexes/{self._name}/stats")
+
+
+# ─── Async ────────────────────────────────────────────────────────────────────
+
+class AsyncIndexClient:
+    def __init__(self, name: str, http: AsyncHttp) -> None:
+        self._name = name
+        self._http = http
+
+    async def insert(self, id: str, text: str, metadata: Optional[Dict[str, Any]] = None) -> InsertResult:
+        body: Dict[str, Any] = {"id": id, "text": text}
+        if metadata:
+            body["metadata"] = metadata
+        return InsertResult._from(await self._http.post(f"/v1/indexes/{self._name}/insert", body))
+
+    async def insert_many(self, docs: List[Dict[str, Any]]) -> Dict[str, Any]:
+        return await self._http.post(f"/v1/indexes/{self._name}/batch", {"docs": docs})
+
+    async def search(
+        self,
+        query: str,
+        limit: int = 10,
+        threshold: Optional[float] = None,
+        filter: Optional[Dict[str, Any]] = None,
+    ) -> List[SearchResult]:
+        body: Dict[str, Any] = {"query": query, "limit": limit}
+        if threshold is not None:
+            body["threshold"] = threshold
+        if filter:
+            body["filter"] = filter
+        data = await self._http.post(f"/v1/indexes/{self._name}/search", body)
+        return [SearchResult._from(r) for r in data.get("results", [])]
+
+    async def get(self, id: str) -> Optional[Dict[str, Any]]:
+        try:
+            return await self._http.get(f"/v1/indexes/{self._name}/docs/{id}")
+        except Exception:
+            return None
+
+    async def delete(self, id: str) -> None:
+        await self._http.delete(f"/v1/indexes/{self._name}/docs/{id}")
+
+    async def stats(self) -> Dict[str, Any]:
+        return await self._http.get(f"/v1/indexes/{self._name}/stats")

cubememory-0.1.0/cubememory/memory.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional
+
+from .http import SyncHttp, AsyncHttp
+from .index import SearchResult
+
+
+class MemoryClient:
+    def __init__(self, http: SyncHttp) -> None:
+        self._http = http
+
+    def store(self, text: str, layer: Literal["long-term", "short-term"] = "long-term") -> Dict[str, Any]:
+        return self._http.post("/v1/memory", {"text": text, "layer": layer})
+
+    def search(self, query: str, limit: int = 5) -> List[SearchResult]:
+        data = self._http.post("/v1/memory/search", {"query": query, "limit": limit})
+        return [SearchResult._from(r) for r in data.get("results", [])]
+
+    def list(self, limit: int = 20) -> List[Dict[str, Any]]:
+        data = self._http.get(f"/v1/memory?limit={limit}")
+        return data.get("memories", [])
+
+    def delete(self, id: str) -> None:
+        self._http.delete(f"/v1/memory/{id}")
+
+
+class AsyncMemoryClient:
+    def __init__(self, http: AsyncHttp) -> None:
+        self._http = http
+
+    async def store(self, text: str, layer: Literal["long-term", "short-term"] = "long-term") -> Dict[str, Any]:
+        return await self._http.post("/v1/memory", {"text": text, "layer": layer})
+
+    async def search(self, query: str, limit: int = 5) -> List[SearchResult]:
+        data = await self._http.post("/v1/memory/search", {"query": query, "limit": limit})
+        return [SearchResult._from(r) for r in data.get("results", [])]
+
+    async def list(self, limit: int = 20) -> List[Dict[str, Any]]:
+        data = await self._http.get(f"/v1/memory?limit={limit}")
+        return data.get("memories", [])
+
+    async def delete(self, id: str) -> None:
+        await self._http.delete(f"/v1/memory/{id}")

cubememory-0.1.0/cubememory/notes.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from .http import SyncHttp, AsyncHttp
+
+
+@dataclass
+class Note:
+    id: str
+    title: str
+    tags: List[str] = field(default_factory=list)
+    text_preview: str = ""
+    updated_at: Optional[float] = None
+    score: Optional[float] = None
+    matched_section: Optional[str] = None
+
+    @classmethod
+    def _from(cls, d: Dict[str, Any]) -> "Note":
+        return cls(
+            id=d.get("id", ""),
+            title=d.get("title", "Untitled"),
+            tags=d.get("tags", []),
+            text_preview=d.get("text_preview", ""),
+            updated_at=d.get("updated_at"),
+            score=d.get("score"),
+            matched_section=d.get("matched_section"),
+        )
+
+
+@dataclass
+class NoteDetail(Note):
+    text: str = ""
+    tiptap_json: Optional[str] = None
+    related_notes: List[Dict[str, Any]] = field(default_factory=list)
+
+    @classmethod
+    def _from(cls, d: Dict[str, Any]) -> "NoteDetail":  # type: ignore[override]
+        return cls(
+            id=d.get("id", ""),
+            title=d.get("title", "Untitled"),
+            tags=d.get("tags", []),
+            text_preview=d.get("text_preview", ""),
+            updated_at=d.get("updated_at"),
+            text=d.get("text", ""),
+            tiptap_json=d.get("tiptap_json"),
+            related_notes=d.get("related_notes", []),
+        )
+
+
+class NotesClient:
+    def __init__(self, http: SyncHttp) -> None:
+        self._http = http
+
+    def upsert(
+        self,
+        title: str,
+        text: str,
+        id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"title": title, "text": text}
+        if id:
+            body["id"] = id
+        if tags:
+            body["tags"] = tags
+        return self._http.post("/v1/notes", body)
+
+    def list(self) -> List[Note]:
+        data = self._http.get("/v1/notes")
+        return [Note._from(n) for n in data.get("notes", [])]
+
+    def get(self, id: str) -> NoteDetail:
+        return NoteDetail._from(self._http.get(f"/v1/notes/{id}"))
+
+    def search(self, query: str, limit: int = 10) -> List[Note]:
+        data = self._http.post("/v1/notes/search", {"query": query, "limit": limit})
+        return [Note._from(n) for n in data.get("results", [])]
+
+    def delete(self, id: str) -> None:
+        self._http.delete(f"/v1/notes/{id}")
+
+
+class AsyncNotesClient:
+    def __init__(self, http: AsyncHttp) -> None:
+        self._http = http
+
+    async def upsert(
+        self,
+        title: str,
+        text: str,
+        id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"title": title, "text": text}
+        if id:
+            body["id"] = id
+        if tags:
+            body["tags"] = tags
+        return await self._http.post("/v1/notes", body)
+
+    async def list(self) -> List[Note]:
+        data = await self._http.get("/v1/notes")
+        return [Note._from(n) for n in data.get("notes", [])]
+
+    async def get(self, id: str) -> NoteDetail:
+        return NoteDetail._from(await self._http.get(f"/v1/notes/{id}"))
+
+    async def search(self, query: str, limit: int = 10) -> List[Note]:
+        data = await self._http.post("/v1/notes/search", {"query": query, "limit": limit})
+        return [Note._from(n) for n in data.get("results", [])]
+
+    async def delete(self, id: str) -> None:
+        await self._http.delete(f"/v1/notes/{id}")

cubememory-0.1.0/cubememory.egg-info/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: cubememory
+Version: 0.1.0
+Summary: Official Python SDK for Cube Memory — semantic search with 100% exact recall
+Author-email: Ronny Guerreiro <ynnor.guerreiro@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://cubememory.com.br
+Project-URL: Documentation, https://cubememory.com.br/docs
+Project-URL: Repository, https://github.com/cubememory/sdk-python
+Keywords: vector-search,semantic-search,rag,llm-memory,mcp,cube-memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: async
+Requires-Dist: httpx>=0.25; extra == "async"
+Provides-Extra: all
+Requires-Dist: httpx>=0.25; extra == "all"

cubememory-0.1.0/cubememory.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+pyproject.toml
+cubememory/__init__.py
+cubememory/client.py
+cubememory/exceptions.py
+cubememory/http.py
+cubememory/index.py
+cubememory/memory.py
+cubememory/notes.py
+cubememory.egg-info/PKG-INFO
+cubememory.egg-info/SOURCES.txt
+cubememory.egg-info/dependency_links.txt
+cubememory.egg-info/requires.txt
+cubememory.egg-info/top_level.txt

cubememory-0.1.0/cubememory.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cubememory-0.1.0/cubememory.egg-info/requires.txt

@@ -0,0 +1,7 @@
+requests>=2.28
+
+[all]
+httpx>=0.25
+
+[async]
+httpx>=0.25

cubememory-0.1.0/cubememory.egg-info/top_level.txt

@@ -0,0 +1 @@
+cubememory

cubememory-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cubememory"
+version = "0.1.0"
+description = "Official Python SDK for Cube Memory — semantic search with 100% exact recall"
+license = "MIT"
+authors = [{ name = "Ronny Guerreiro", email = "ynnor.guerreiro@gmail.com" }]
+keywords = ["vector-search", "semantic-search", "rag", "llm-memory", "mcp", "cube-memory"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "requests>=2.28",
+]
+
+[project.optional-dependencies]
+async = ["httpx>=0.25"]
+all = ["httpx>=0.25"]
+
+[project.urls]
+Homepage = "https://cubememory.com.br"
+Documentation = "https://cubememory.com.br/docs"
+Repository = "https://github.com/cubememory/sdk-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["cubememory"]

cubememory-0.1.0/setup.cfg

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