kognite 0.1.0__tar.gz

kognite-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: kognite
+Version: 0.1.0
+Summary: Python SDK for Kognite — long-term memory for AI agents (hybrid semantic search, memory formation, knowledge graph)
+Author-email: Kognite <hello@kognite.dev>
+License: MIT
+Project-URL: Homepage, https://kognite.dev
+Project-URL: Repository, https://github.com/global-software-development-eu/memcore-portable-agent-memory-saas
+Keywords: kognite,agent-memory,memory,llm,rag,sdk,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# kognite
+
+Python SDK for [Kognite](https://kognite.dev) — long-term memory for AI agents.
+Hybrid semantic + full-text search, LLM memory formation, and a knowledge graph,
+behind one API key. **Zero dependencies** (stdlib only), Python 3.9+.
+
+```bash
+pip install kognite
+```
+
+## Quickstart
+
+```python
+from kognite import Kognite
+
+k = Kognite(api_key="kgn_...")
+
+# Store a memory
+k.memories.add("User prefers dark mode", kind="preference")
+
+# Hybrid search (semantic + full-text, RRF-fused)
+hits = k.memories.search("ui preferences", limit=5)["results"]
+
+# Highest precision (cross-encoder rerank — slower):
+k.memories.search("ui preferences", rerank=True)
+```
+
+## Memory formation (the good stuff)
+
+`ingest` runs the pipeline behind Kognite's published LoCoMo results: it stores
+raw messages as episodes **and** extracts atomic facts — pronouns resolved to
+names, relative dates converted to absolute ones. Prefer it over `add` for any
+multi-message context:
+
+```python
+k.memories.ingest([
+    {"speaker": "user", "timestamp": "2026-07-15", "content": "I moved to Berlin last month."},
+    {"speaker": "assistant", "content": "Noted — how are you finding it?"},
+])
+# → {"raw": 2, "extracted": 1, "stored": 3}
+```
+
+## Context assembly
+
+A token-budgeted bundle of relevant memories, ready to drop into a prompt:
+
+```python
+ctx = k.context.assemble("user's living situation", token_budget=2000)
+```
+
+## Everything else
+
+```python
+k.memories.get(memory_id)
+k.memories.forget(memory_id)      # soft-delete (+ graph cascade)
+k.memories.list(limit=50)         # newest-first paging
+k.graph.query("Berlin")           # knowledge-graph search
+k.health()
+```
+
+Errors raise `KogniteError` with `.status` (HTTP) and `.code`
+(`validation_failed`, `quota_exceeded`, `not_found`, …). Retries with
+exponential backoff on 429/5xx/network errors are built in.
+
+The tenant scope is derived server-side from your API key — the SDK has no
+scope parameter and cannot reach another tenant. Get a key in the
+[dashboard](https://app.kognite.dev), and see the live, judge-audited
+[benchmarks](https://kognite.dev/benchmarks).
+
+Self-hosted? Pass `base_url=` to the constructor.
+
+## Development
+
+`smoke_live.py` is a full live-API exercise of every method (safe: runs in the
+key's own scope and forgets everything it creates):
+
+```bash
+KOGNITE_API_KEY=kgn_... python smoke_live.py
+```

kognite-0.1.0/README.md

@@ -0,0 +1,79 @@
+# kognite
+
+Python SDK for [Kognite](https://kognite.dev) — long-term memory for AI agents.
+Hybrid semantic + full-text search, LLM memory formation, and a knowledge graph,
+behind one API key. **Zero dependencies** (stdlib only), Python 3.9+.
+
+```bash
+pip install kognite
+```
+
+## Quickstart
+
+```python
+from kognite import Kognite
+
+k = Kognite(api_key="kgn_...")
+
+# Store a memory
+k.memories.add("User prefers dark mode", kind="preference")
+
+# Hybrid search (semantic + full-text, RRF-fused)
+hits = k.memories.search("ui preferences", limit=5)["results"]
+
+# Highest precision (cross-encoder rerank — slower):
+k.memories.search("ui preferences", rerank=True)
+```
+
+## Memory formation (the good stuff)
+
+`ingest` runs the pipeline behind Kognite's published LoCoMo results: it stores
+raw messages as episodes **and** extracts atomic facts — pronouns resolved to
+names, relative dates converted to absolute ones. Prefer it over `add` for any
+multi-message context:
+
+```python
+k.memories.ingest([
+    {"speaker": "user", "timestamp": "2026-07-15", "content": "I moved to Berlin last month."},
+    {"speaker": "assistant", "content": "Noted — how are you finding it?"},
+])
+# → {"raw": 2, "extracted": 1, "stored": 3}
+```
+
+## Context assembly
+
+A token-budgeted bundle of relevant memories, ready to drop into a prompt:
+
+```python
+ctx = k.context.assemble("user's living situation", token_budget=2000)
+```
+
+## Everything else
+
+```python
+k.memories.get(memory_id)
+k.memories.forget(memory_id)      # soft-delete (+ graph cascade)
+k.memories.list(limit=50)         # newest-first paging
+k.graph.query("Berlin")           # knowledge-graph search
+k.health()
+```
+
+Errors raise `KogniteError` with `.status` (HTTP) and `.code`
+(`validation_failed`, `quota_exceeded`, `not_found`, …). Retries with
+exponential backoff on 429/5xx/network errors are built in.
+
+The tenant scope is derived server-side from your API key — the SDK has no
+scope parameter and cannot reach another tenant. Get a key in the
+[dashboard](https://app.kognite.dev), and see the live, judge-audited
+[benchmarks](https://kognite.dev/benchmarks).
+
+Self-hosted? Pass `base_url=` to the constructor.
+
+## Development
+
+`smoke_live.py` is a full live-API exercise of every method (safe: runs in the
+key's own scope and forgets everything it creates):
+
+```bash
+KOGNITE_API_KEY=kgn_... python smoke_live.py
+```

kognite-0.1.0/kognite/__init__.py

@@ -0,0 +1,22 @@
+"""
+Kognite Python SDK — long-term memory for AI agents.
+
+Usage::
+
+    from kognite import Kognite
+
+    k = Kognite(api_key="kgn_your_api_key")
+
+    k.memories.add("User prefers dark mode", kind="preference")
+    hits = k.memories.search("ui preferences")["results"]
+
+    # Memory formation (episodes + extracted atomic facts):
+    k.memories.ingest([
+        {"speaker": "user", "timestamp": "2026-07-15", "content": "I moved to Berlin last month."},
+    ])
+"""
+
+from kognite.client import Kognite, KogniteError
+
+__all__ = ["Kognite", "KogniteError"]
+__version__ = "0.1.0"

kognite-0.1.0/kognite/client.py

@@ -0,0 +1,282 @@
+"""
+Kognite Python SDK — typed client for the Kognite memory API.
+
+Zero dependencies (stdlib urllib). The scope (tenant) is derived server-side
+from the API key — there is no scope parameter anywhere in this SDK.
+
+Usage::
+
+    from kognite import Kognite
+
+    k = Kognite(api_key="kgn_...")
+    k.memories.add("User prefers dark mode", kind="preference")
+    hits = k.memories.search("ui preferences")["results"]
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+DEFAULT_BASE_URL = "https://api.kognite.dev"
+_RETRYABLE = lambda status: status == 429 or status >= 500  # noqa: E731
+
+
+class KogniteError(Exception):
+    """Raised on any non-2xx API response.
+
+    Attributes:
+        status: HTTP status code.
+        code: API error code (e.g. "validation_failed", "quota_exceeded", "not_found").
+    """
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        self.status = status
+        self.code = code
+        super().__init__(f"[{status}] {code}: {message}")
+
+
+class Kognite:
+    """Kognite API client.
+
+    Args:
+        api_key: Kognite API key (PAT) from the dashboard.
+        base_url: Override for self-hosted deployments (default https://api.kognite.dev).
+        max_retries: Retries on 429/5xx/network errors (default 3).
+        retry_base_delay: Base seconds for exponential backoff (default 0.5).
+        timeout: Per-request timeout in seconds (default 30).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 3,
+        retry_base_delay: float = 0.5,
+        timeout: float = 30.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("Kognite: api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._retry_base_delay = retry_base_delay
+        self._timeout = timeout
+        self.memories = _Memories(self)
+        self.context = _Context(self)
+        self.graph = _Graph(self)
+
+    # ── HTTP core ────────────────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        query: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = self._base_url + path
+        if query:
+            filtered = {k: v for k, v in query.items() if v is not None}
+            if filtered:
+                url += "?" + urllib.parse.urlencode(filtered)
+
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            # A real UA matters: Cloudflare (in front of api.kognite.dev)
+            # rejects the default Python-urllib agent with a 403.
+            "User-Agent": "kognite-python/0.1.0",
+        }
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+
+        last_error: Optional[Exception] = None
+        for attempt in range(self._max_retries + 1):
+            req = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(req, timeout=self._timeout) as res:
+                    if res.status == 204:
+                        return None
+                    return json.loads(res.read().decode("utf-8"))
+            except urllib.error.HTTPError as e:
+                status = e.code
+                if _RETRYABLE(status) and attempt < self._max_retries:
+                    time.sleep(random.random() * self._retry_base_delay * (2**attempt))
+                    continue
+                try:
+                    parsed = json.loads(e.read().decode("utf-8"))
+                    err = parsed.get("error") or {}
+                except Exception:
+                    err = {}
+                raise KogniteError(
+                    status, err.get("code", "http_error"), err.get("message", f"HTTP {status}")
+                ) from None
+            except (urllib.error.URLError, TimeoutError, OSError) as e:
+                last_error = e
+                if attempt < self._max_retries:
+                    time.sleep(random.random() * self._retry_base_delay * (2**attempt))
+                    continue
+        raise KogniteError(0, "network_error", str(last_error))
+
+    # ── Health ───────────────────────────────────────────────────────────────
+
+    def health(self) -> Dict[str, Any]:
+        """Liveness check (no auth required by the API)."""
+        return self._request("GET", "/api/health")
+
+
+class _Memories:
+    """Memory store — add, search, list, get, forget, batch ingest."""
+
+    def __init__(self, client: Kognite) -> None:
+        self._c = client
+
+    def add(
+        self,
+        content: str,
+        kind: Optional[str] = None,
+        confidence: Optional[float] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        source: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Store a single memory. Returns ``{"id": ..., "created_at": ...}``."""
+        body: Dict[str, Any] = {"content": content}
+        if kind is not None:
+            body["kind"] = kind
+        if confidence is not None:
+            body["confidence"] = confidence
+        if metadata is not None:
+            body["metadata"] = metadata
+        if source is not None:
+            body["source"] = source
+        if idempotency_key is not None:
+            body["idempotency_key"] = idempotency_key
+        return self._c._request("POST", "/api/memories", body)["data"]
+
+    def search(
+        self,
+        query: str,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        kind: Optional[str] = None,
+        min_confidence: Optional[float] = None,
+        rerank: bool = False,
+        rerank_n: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Hybrid semantic + full-text search.
+
+        Returns ``{"results": [...], "total": int, "capped": bool}``. Pass
+        ``rerank=True`` for the highest-precision (slower) cross-encoder path.
+        """
+        return self._c._request(
+            "GET",
+            "/api/memories",
+            query={
+                "q": query,
+                "limit": limit,
+                "offset": offset,
+                "kind": kind,
+                "min_confidence": min_confidence,
+                "rerank": 1 if rerank else None,
+                "rerank_n": rerank_n if rerank else None,
+            },
+        )
+
+    def list(
+        self,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        kind: Optional[str] = None,
+        min_confidence: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """Page through memories newest-first. Returns ``{"data": [...], "meta": {...}}``."""
+        return self._c._request(
+            "GET",
+            "/api/memories",
+            query={
+                "limit": limit,
+                "offset": offset,
+                "kind": kind,
+                "min_confidence": min_confidence,
+            },
+        )
+
+    def get(self, memory_id: str) -> Dict[str, Any]:
+        """Fetch one memory by id."""
+        return self._c._request("GET", f"/api/memories/{urllib.parse.quote(memory_id)}")["data"]
+
+    def forget(self, memory_id: str) -> None:
+        """Soft-delete a memory (and any graph nodes it alone supported)."""
+        self._c._request("DELETE", f"/api/memories/{urllib.parse.quote(memory_id)}")
+
+    def ingest(
+        self,
+        messages: List[Dict[str, Any]],
+        extract: bool = True,
+        store_raw: bool = True,
+    ) -> Dict[str, Any]:
+        """Batch conversational ingest — the memory-formation pipeline.
+
+        Stores raw messages as episodes AND extracts atomic facts (names
+        resolved, relative dates made absolute). This is what powers Kognite's
+        published LoCoMo results; prefer it over ``add`` for any multi-message
+        context. Each message: ``{"content": str, "id"?: str, "speaker"?: str,
+        "timestamp"?: str}``. Returns ``{"raw": n, "extracted": n, "stored": n}``.
+        """
+        return self._c._request(
+            "POST",
+            "/api/memories/ingest",
+            {"messages": messages, "extract": extract, "store_raw": store_raw},
+        )
+
+
+class _Context:
+    """Context assembly — a token-budgeted bundle of relevant memories."""
+
+    def __init__(self, client: Kognite) -> None:
+        self._c = client
+
+    def assemble(
+        self,
+        query: str,
+        token_budget: Optional[int] = None,
+        max_results: Optional[int] = None,
+        kinds: Optional[List[str]] = None,
+        min_confidence: Optional[float] = None,
+        include_skills: bool = False,
+        include_graph: bool = True,
+    ) -> Dict[str, Any]:
+        """Assemble a context bundle for a query, packed under a token budget."""
+        body: Dict[str, Any] = {
+            "query": query,
+            "include_skills": include_skills,
+            "include_graph": include_graph,
+        }
+        if token_budget is not None:
+            body["token_budget"] = token_budget
+        if max_results is not None:
+            body["max_results"] = max_results
+        if kinds is not None:
+            body["kinds"] = kinds
+        if min_confidence is not None:
+            body["min_confidence"] = min_confidence
+        return self._c._request("POST", "/api/context/assemble", body)["data"]
+
+
+class _Graph:
+    """Knowledge-graph overview / entity search."""
+
+    def __init__(self, client: Kognite) -> None:
+        self._c = client
+
+    def query(self, q: Optional[str] = None) -> Dict[str, Any]:
+        """Graph overview; pass ``q`` to also search entities/relationships."""
+        return self._c._request("GET", "/api/knowledge-graph", query={"q": q} if q else None)["data"]

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

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: kognite
+Version: 0.1.0
+Summary: Python SDK for Kognite — long-term memory for AI agents (hybrid semantic search, memory formation, knowledge graph)
+Author-email: Kognite <hello@kognite.dev>
+License: MIT
+Project-URL: Homepage, https://kognite.dev
+Project-URL: Repository, https://github.com/global-software-development-eu/memcore-portable-agent-memory-saas
+Keywords: kognite,agent-memory,memory,llm,rag,sdk,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# kognite
+
+Python SDK for [Kognite](https://kognite.dev) — long-term memory for AI agents.
+Hybrid semantic + full-text search, LLM memory formation, and a knowledge graph,
+behind one API key. **Zero dependencies** (stdlib only), Python 3.9+.
+
+```bash
+pip install kognite
+```
+
+## Quickstart
+
+```python
+from kognite import Kognite
+
+k = Kognite(api_key="kgn_...")
+
+# Store a memory
+k.memories.add("User prefers dark mode", kind="preference")
+
+# Hybrid search (semantic + full-text, RRF-fused)
+hits = k.memories.search("ui preferences", limit=5)["results"]
+
+# Highest precision (cross-encoder rerank — slower):
+k.memories.search("ui preferences", rerank=True)
+```
+
+## Memory formation (the good stuff)
+
+`ingest` runs the pipeline behind Kognite's published LoCoMo results: it stores
+raw messages as episodes **and** extracts atomic facts — pronouns resolved to
+names, relative dates converted to absolute ones. Prefer it over `add` for any
+multi-message context:
+
+```python
+k.memories.ingest([
+    {"speaker": "user", "timestamp": "2026-07-15", "content": "I moved to Berlin last month."},
+    {"speaker": "assistant", "content": "Noted — how are you finding it?"},
+])
+# → {"raw": 2, "extracted": 1, "stored": 3}
+```
+
+## Context assembly
+
+A token-budgeted bundle of relevant memories, ready to drop into a prompt:
+
+```python
+ctx = k.context.assemble("user's living situation", token_budget=2000)
+```
+
+## Everything else
+
+```python
+k.memories.get(memory_id)
+k.memories.forget(memory_id)      # soft-delete (+ graph cascade)
+k.memories.list(limit=50)         # newest-first paging
+k.graph.query("Berlin")           # knowledge-graph search
+k.health()
+```
+
+Errors raise `KogniteError` with `.status` (HTTP) and `.code`
+(`validation_failed`, `quota_exceeded`, `not_found`, …). Retries with
+exponential backoff on 429/5xx/network errors are built in.
+
+The tenant scope is derived server-side from your API key — the SDK has no
+scope parameter and cannot reach another tenant. Get a key in the
+[dashboard](https://app.kognite.dev), and see the live, judge-audited
+[benchmarks](https://kognite.dev/benchmarks).
+
+Self-hosted? Pass `base_url=` to the constructor.
+
+## Development
+
+`smoke_live.py` is a full live-API exercise of every method (safe: runs in the
+key's own scope and forgets everything it creates):
+
+```bash
+KOGNITE_API_KEY=kgn_... python smoke_live.py
+```

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

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+kognite/__init__.py
+kognite/client.py
+kognite.egg-info/PKG-INFO
+kognite.egg-info/SOURCES.txt
+kognite.egg-info/dependency_links.txt
+kognite.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+kognite

kognite-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kognite"
+version = "0.1.0"
+description = "Python SDK for Kognite — long-term memory for AI agents (hybrid semantic search, memory formation, knowledge graph)"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Kognite", email = "hello@kognite.dev"},
+]
+keywords = ["kognite", "agent-memory", "memory", "llm", "rag", "sdk", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.9"
+# Zero runtime dependencies — stdlib urllib only.
+dependencies = []
+
+[project.urls]
+Homepage = "https://kognite.dev"
+Repository = "https://github.com/global-software-development-eu/memcore-portable-agent-memory-saas"
+
+[tool.setuptools.packages.find]
+include = ["kognite*"]

kognite-0.1.0/setup.cfg

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