outhad-contextkit-sdk 1.0.0__tar.gz

outhad_contextkit_sdk-1.0.0/.gitignore

@@ -0,0 +1,196 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+**/node_modules/
+
+# C extensions
+*.so
+venv_test_clap/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended not to include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+pyenv/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+.ideas.md
+.todos.md
+
+# Database
+db
+test-db
+!embedchain/embedchain/core/db/
+
+.vscode
+.idea/
+
+.DS_Store
+
+notebooks/*.yaml
+.ipynb_checkpoints/
+
+!configs/*.yaml
+
+# cache db
+*.db
+
+# local directories for testing
+eval/
+qdrant_storage/
+.crossnote
+testing.ipynb
+#CHUNKING_AND_RETRIEVAL
+
+
+# Backup documentation and test data
+test_dataset/data/
+
+Readme2.md

outhad_contextkit_sdk-1.0.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Outhad
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

outhad_contextkit_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: outhad-contextkit-sdk
+Version: 1.0.0
+Summary: Thin Python client for the Outhad ContextKit cloud — paywalled by API key minted at https://contextkit.outhad.com
+Project-URL: Homepage, https://contextkit.outhad.com
+Project-URL: Documentation, https://contextkit.outhad.com/docs
+Project-URL: Source, https://github.com/outhad/contextkit
+Project-URL: Issues, https://github.com/outhad/contextkit/issues
+Author-email: Outhad <idrisitanzil@gmail.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,contextkit,long-term-memory,memory,outhad,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+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: httpx>=0.27.0
+Requires-Dist: typing-extensions>=4.8.0; python_version < '3.11'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23.7; extra == 'test'
+Requires-Dist: pytest>=8.2.2; extra == 'test'
+Requires-Dist: respx>=0.21.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# outhad-contextkit-sdk
+
+Thin Python client for the **Outhad ContextKit** cloud — long-term memory
+for AI agents, with multimodal + temporal-causal recall, personalised
+retrieval, and tenant isolation built in.
+
+This package ships **client only**. There is no local memory engine, no
+vector store driver, no LLM provider. Calls go to the Outhad ContextKit
+cloud where the heavy lifting happens — billed against the API key you
+mint at https://contextkit.outhad.com.
+
+## Install
+
+```bash
+pip install outhad-contextkit-sdk
+```
+
+## Quickstart
+
+```python
+from outhad_contextkit_sdk import MemoryClient
+
+client = MemoryClient(api_key="ock_live_...")  # or set OUTHAD_CONTEXTKIT_API_KEY
+
+client.add(
+    messages=[
+        {"role": "user", "content": "Hi, my name is Alice and I love sushi."},
+    ],
+    user_id="alice",
+)
+
+hits = client.search(query="What food does Alice like?", user_id="alice")
+for hit in hits["results"]:
+    print(hit["score"], hit["memory"])
+```
+
+## Get an API key
+
+1. Sign up at <https://contextkit.outhad.com>.
+2. Open the dashboard → **API keys**.
+3. Click **Create key**, copy the one-shot secret (looks like
+   `ock_live_<8-char-prefix>_<32-byte-secret>`).
+4. Either pass it as `MemoryClient(api_key=…)` or export it in your
+   shell as `OUTHAD_CONTEXTKIT_API_KEY`.
+
+## Auth header
+
+The SDK sends `Authorization: Token <api-key>` on every request. The
+cloud dispatcher also accepts `Bearer` and `X-API-Key` if you prefer to
+hit the HTTP API directly (e.g. from `curl`).
+
+## Host resolution
+
+| Resolution order | Default |
+|------------------|---------|
+| `host=` constructor arg | (none) |
+| `OUTHAD_CONTEXTKIT_HOST` env var | (none) |
+| Production default | `https://contextkit.outhad.com` |
+| Dev fallback (transparent retry on connection error) | `http://localhost:8000` |
+
+When the production default is unreachable (DNS failure / connection
+refused) the client transparently retries against
+`http://localhost:8000` and pins itself there for the rest of the
+session — useful while you are working against `make cloud-up` locally.
+The fallback is disabled when you pass `host=` or set
+`OUTHAD_CONTEXTKIT_HOST` explicitly.
+
+## Async
+
+```python
+from outhad_contextkit_sdk import AsyncMemoryClient
+
+async def main():
+    async with AsyncMemoryClient(api_key="ock_live_...") as client:
+        await client.add(
+            messages=[{"role": "user", "content": "I prefer dark mode."}],
+            user_id="alice",
+        )
+```
+
+## API surface
+
+* `add(messages, *, user_id, agent_id, run_id, metadata, infer)`
+* `get_all(*, user_id, agent_id, run_id, limit)`
+* `get(memory_id)`
+* `search(query, *, user_id, agent_id, run_id, filters, limit)`
+* `update(memory_id, *, text)`
+* `history(memory_id)`
+* `delete(memory_id)`
+* `delete_all(*, user_id, agent_id, run_id)`
+
+For dashboard-style operations the same client also exposes
+`list_api_keys()`, `create_api_key()`, `revoke_api_key()` — those
+require a Clerk session JWT and are intended for interactive tooling.
+
+## License
+
+Apache-2.0.

outhad_contextkit_sdk-1.0.0/README.md

@@ -0,0 +1,98 @@
+# outhad-contextkit-sdk
+
+Thin Python client for the **Outhad ContextKit** cloud — long-term memory
+for AI agents, with multimodal + temporal-causal recall, personalised
+retrieval, and tenant isolation built in.
+
+This package ships **client only**. There is no local memory engine, no
+vector store driver, no LLM provider. Calls go to the Outhad ContextKit
+cloud where the heavy lifting happens — billed against the API key you
+mint at https://contextkit.outhad.com.
+
+## Install
+
+```bash
+pip install outhad-contextkit-sdk
+```
+
+## Quickstart
+
+```python
+from outhad_contextkit_sdk import MemoryClient
+
+client = MemoryClient(api_key="ock_live_...")  # or set OUTHAD_CONTEXTKIT_API_KEY
+
+client.add(
+    messages=[
+        {"role": "user", "content": "Hi, my name is Alice and I love sushi."},
+    ],
+    user_id="alice",
+)
+
+hits = client.search(query="What food does Alice like?", user_id="alice")
+for hit in hits["results"]:
+    print(hit["score"], hit["memory"])
+```
+
+## Get an API key
+
+1. Sign up at <https://contextkit.outhad.com>.
+2. Open the dashboard → **API keys**.
+3. Click **Create key**, copy the one-shot secret (looks like
+   `ock_live_<8-char-prefix>_<32-byte-secret>`).
+4. Either pass it as `MemoryClient(api_key=…)` or export it in your
+   shell as `OUTHAD_CONTEXTKIT_API_KEY`.
+
+## Auth header
+
+The SDK sends `Authorization: Token <api-key>` on every request. The
+cloud dispatcher also accepts `Bearer` and `X-API-Key` if you prefer to
+hit the HTTP API directly (e.g. from `curl`).
+
+## Host resolution
+
+| Resolution order | Default |
+|------------------|---------|
+| `host=` constructor arg | (none) |
+| `OUTHAD_CONTEXTKIT_HOST` env var | (none) |
+| Production default | `https://contextkit.outhad.com` |
+| Dev fallback (transparent retry on connection error) | `http://localhost:8000` |
+
+When the production default is unreachable (DNS failure / connection
+refused) the client transparently retries against
+`http://localhost:8000` and pins itself there for the rest of the
+session — useful while you are working against `make cloud-up` locally.
+The fallback is disabled when you pass `host=` or set
+`OUTHAD_CONTEXTKIT_HOST` explicitly.
+
+## Async
+
+```python
+from outhad_contextkit_sdk import AsyncMemoryClient
+
+async def main():
+    async with AsyncMemoryClient(api_key="ock_live_...") as client:
+        await client.add(
+            messages=[{"role": "user", "content": "I prefer dark mode."}],
+            user_id="alice",
+        )
+```
+
+## API surface
+
+* `add(messages, *, user_id, agent_id, run_id, metadata, infer)`
+* `get_all(*, user_id, agent_id, run_id, limit)`
+* `get(memory_id)`
+* `search(query, *, user_id, agent_id, run_id, filters, limit)`
+* `update(memory_id, *, text)`
+* `history(memory_id)`
+* `delete(memory_id)`
+* `delete_all(*, user_id, agent_id, run_id)`
+
+For dashboard-style operations the same client also exposes
+`list_api_keys()`, `create_api_key()`, `revoke_api_key()` — those
+require a Clerk session JWT and are intended for interactive tooling.
+
+## License
+
+Apache-2.0.

outhad_contextkit_sdk-1.0.0/outhad_contextkit_sdk/__init__.py

@@ -0,0 +1,44 @@
+"""Outhad ContextKit — thin Python SDK.
+
+This distribution intentionally ships **only** the cloud HTTP client.
+There is no local memory engine, no vector store driver, no LLM
+provider — those live in the upstream ``outhad_contextkit`` library
+which only operators of the cloud platform need.
+
+End-user flow:
+
+1. Sign up at https://contextkit.outhad.com.
+2. Mint an API key in the dashboard.
+3. ``pip install outhad-contextkit-sdk``
+4. ``from outhad_contextkit_sdk import MemoryClient``
+
+Example::
+
+    from outhad_contextkit_sdk import MemoryClient
+
+    client = MemoryClient(api_key="ock_live_...")  # picks up env var if omitted
+    client.add(
+        messages=[{"role": "user", "content": "I love sushi"}],
+        user_id="alice",
+    )
+    hits = client.search(query="What food do I like?", user_id="alice")
+"""
+from outhad_contextkit_sdk.client.errors import APIError, AuthenticationError
+from outhad_contextkit_sdk.client.main import (
+    DEFAULT_HOST,
+    DEV_HOST,
+    AsyncMemoryClient,
+    MemoryClient,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "APIError",
+    "AsyncMemoryClient",
+    "AuthenticationError",
+    "DEFAULT_HOST",
+    "DEV_HOST",
+    "MemoryClient",
+    "__version__",
+]

outhad_contextkit_sdk-1.0.0/outhad_contextkit_sdk/client/__init__.py

@@ -0,0 +1,18 @@
+"""Public client surface for ``outhad_contextkit_sdk``."""
+
+from outhad_contextkit_sdk.client.errors import APIError, AuthenticationError
+from outhad_contextkit_sdk.client.main import (
+    DEFAULT_HOST,
+    DEV_HOST,
+    AsyncMemoryClient,
+    MemoryClient,
+)
+
+__all__ = [
+    "APIError",
+    "AsyncMemoryClient",
+    "AuthenticationError",
+    "DEFAULT_HOST",
+    "DEV_HOST",
+    "MemoryClient",
+]

outhad_contextkit_sdk-1.0.0/outhad_contextkit_sdk/client/errors.py

@@ -0,0 +1,36 @@
+"""Typed exceptions raised by the SDK."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class APIError(Exception):
+    """Raised on any non-2xx response from the cloud backend.
+
+    Attributes:
+        status: HTTP status code returned by the server.
+        body: Decoded JSON / text body, when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        if self.status is None:
+            return super().__str__()
+        return f"[{self.status}] {super().__str__()}"
+
+
+class AuthenticationError(APIError):
+    """Raised when the API key is missing, malformed, revoked or expired."""
+
+
+__all__ = ["APIError", "AuthenticationError"]

outhad_contextkit_sdk-1.0.0/outhad_contextkit_sdk/client/main.py

@@ -0,0 +1,496 @@
+"""Thin Python client for the Outhad ContextKit cloud.
+
+This module is the **only** public surface of ``outhad-contextkit-sdk``.
+It speaks HTTP to the cloud backend and never imports any model
+provider, vector store driver, or local memory engine. All authenticated
+calls require an ``ock_live_…`` / ``ock_test_…`` API key minted at
+https://contextkit.outhad.com/dashboard/api-keys.
+
+Host resolution
+---------------
+1. Explicit ``host=`` constructor arg, when provided.
+2. ``OUTHAD_CONTEXTKIT_HOST`` env var, when set.
+3. Production default (``DEFAULT_HOST = "https://contextkit.outhad.com"``).
+4. On a connection error against the production default the client
+   transparently retries against the local-dev fallback
+   (``DEV_HOST = "http://localhost:8000"``) and pins itself there for
+   the rest of the session — useful while the production deployment
+   is still spinning up. The fallback is only triggered when the
+   default URL is in use; explicit ``host=`` / env wins.
+
+Auth header
+-----------
+``Authorization: Token <api_key>`` — the format the cloud dispatcher
+already accepts (mem0-compat). Set once on the underlying httpx client
+so every request carries it.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from outhad_contextkit_sdk.client.errors import APIError, AuthenticationError
+
+logger = logging.getLogger(__name__)
+
+# Production cloud host. Override via ``host=`` arg or
+# ``OUTHAD_CONTEXTKIT_HOST`` env var. Pinned to the public dashboard
+# domain so the SDK works out of the box for paying customers.
+DEFAULT_HOST = "https://contextkit.outhad.com"
+
+# Local dev host used by ``server/docker-compose.cloud.yaml``. The
+# client falls back to this transparently when the default URL is
+# unreachable (DNS failure / connection refused) — see the docstring.
+DEV_HOST = "http://localhost:8000"
+
+# How long a single HTTP call may take, in seconds. Generous because
+# memory operations include OpenAI fact extraction on the server side.
+DEFAULT_TIMEOUT = 30.0
+
+
+def _select_host(explicit: Optional[str]) -> str:
+    if explicit:
+        return explicit.rstrip("/")
+    env = os.environ.get("OUTHAD_CONTEXTKIT_HOST")
+    if env:
+        return env.rstrip("/")
+    return DEFAULT_HOST
+
+
+def _decode_error(resp: httpx.Response) -> APIError:
+    try:
+        body = resp.json()
+        msg = (
+            body.get("detail")
+            if isinstance(body, dict) and "detail" in body
+            else str(body)
+        )
+    except Exception:
+        body = resp.text
+        msg = body
+    if resp.status_code == 401:
+        return AuthenticationError(msg, status=resp.status_code, body=body)
+    return APIError(msg, status=resp.status_code, body=body)
+
+
+def _is_connection_failure(exc: BaseException) -> bool:
+    """Heuristic — whether ``exc`` looks like the prod URL being down.
+
+    httpx raises ``httpx.ConnectError`` for DNS / connection-refused, and
+    ``httpx.ReadTimeout`` when the server hangs. We treat both as
+    "unreachable" and trigger the dev-host fallback.
+    """
+    return isinstance(
+        exc,
+        (
+            httpx.ConnectError,
+            httpx.ConnectTimeout,
+            httpx.ReadTimeout,
+            httpx.RemoteProtocolError,
+        ),
+    )
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Sync client
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class MemoryClient:
+    """Synchronous client for the Outhad ContextKit cloud.
+
+    Args:
+        api_key: ``ock_live_…`` or ``ock_test_…`` token minted at the
+            dashboard. Falls back to the ``OUTHAD_CONTEXTKIT_API_KEY``
+            env var when omitted; raises :class:`AuthenticationError`
+            when neither is provided.
+        host: Override the cloud host. Defaults to
+            :data:`DEFAULT_HOST` (production). Pass ``DEV_HOST`` for a
+            local backend.
+        timeout: Per-request timeout in seconds.
+        client: Pre-built ``httpx.Client``. When supplied,
+            ``base_url`` and ``Authorization`` headers are overwritten
+            so the rest of the SDK works as-expected.
+        allow_dev_fallback: When True (default), a connection failure
+            against the production default URL retries once against
+            ``DEV_HOST`` and pins the client to it for the session.
+            Disabled automatically when the host was set explicitly.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        host: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: Optional[httpx.Client] = None,
+        allow_dev_fallback: bool = True,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("OUTHAD_CONTEXTKIT_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError(
+                "Outhad ContextKit API key not provided. Pass api_key=… or "
+                "set OUTHAD_CONTEXTKIT_API_KEY in your environment. "
+                "Mint a key at https://contextkit.outhad.com/dashboard/api-keys.",
+                status=401,
+            )
+
+        explicit_host = host is not None or "OUTHAD_CONTEXTKIT_HOST" in os.environ
+        self.host = _select_host(host)
+        self.timeout = timeout
+        self._allow_fallback = allow_dev_fallback and not explicit_host
+        self._fell_back = False
+        self._owns_client = client is None
+
+        if client is None:
+            self._client = httpx.Client(
+                base_url=self.host,
+                timeout=self.timeout,
+                headers=self._auth_headers(),
+            )
+        else:
+            self._client = client
+            self._client.base_url = httpx.URL(self.host)
+            self._client.headers.update(self._auth_headers())
+
+        # Surface identity on construction (and trigger dev fallback
+        # when the production default is unreachable).
+        self.identity: Dict[str, Any] = self._validate()
+        self.user_email = self.identity.get("user_email")
+        self.org_id = self.identity.get("org_id")
+        self.project_id = self.identity.get("project_id")
+
+    # ----- private --------------------------------------------------------
+    def _auth_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Token {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "outhad-contextkit-sdk-python/1.0.0",
+        }
+
+    def _retarget(self, host: str) -> None:
+        self.host = host.rstrip("/")
+        self._client.base_url = httpx.URL(self.host)
+        self._fell_back = True
+
+    def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        try:
+            resp = self._client.request(method, path, **kwargs)
+        except Exception as exc:
+            if (
+                self._allow_fallback
+                and not self._fell_back
+                and self.host == DEFAULT_HOST
+                and _is_connection_failure(exc)
+            ):
+                logger.warning(
+                    "Production host %s unreachable (%s) — retrying against %s",
+                    DEFAULT_HOST,
+                    exc.__class__.__name__,
+                    DEV_HOST,
+                )
+                self._retarget(DEV_HOST)
+                return self._client.request(method, path, **kwargs)
+            raise
+        return resp
+
+    def _json(self, method: str, path: str, **kwargs) -> Any:
+        resp = self._request(method, path, **kwargs)
+        if not resp.is_success:
+            raise _decode_error(resp)
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    def _validate(self) -> Dict[str, Any]:
+        # ``GET /v1/ping/`` returns identity when a valid API key is
+        # supplied — that is the canonical handshake the cloud backend
+        # implements.
+        try:
+            resp = self._request("GET", "/v1/ping/")
+        except Exception:
+            raise
+        if resp.status_code == 401:
+            raise AuthenticationError(
+                "API key rejected — verify it on the dashboard.",
+                status=401,
+                body=resp.text,
+            )
+        if not resp.is_success:
+            raise APIError(
+                f"Failed to reach Outhad ContextKit cloud at {self.host}",
+                status=resp.status_code,
+                body=resp.text,
+            )
+        try:
+            data = resp.json()
+        except Exception:
+            data = {}
+        if isinstance(data, dict) and data.get("auth") == "invalid_api_key":
+            raise AuthenticationError(
+                "API key rejected by the cloud.",
+                status=401,
+                body=data,
+            )
+        return data if isinstance(data, dict) else {}
+
+    # ----- memory CRUD ----------------------------------------------------
+    def add(
+        self,
+        messages: List[Dict[str, str]],
+        *,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        infer: bool = True,
+    ) -> Any:
+        payload = {
+            "messages": messages,
+            "user_id": user_id,
+            "agent_id": agent_id,
+            "run_id": run_id,
+            "metadata": metadata,
+            "infer": infer,
+        }
+        return self._json("POST", "/v1/memories/", json=payload)
+
+    def get_all(
+        self,
+        *,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        limit: int = 100,
+    ) -> Any:
+        params = {
+            k: v
+            for k, v in {
+                "user_id": user_id,
+                "agent_id": agent_id,
+                "run_id": run_id,
+                "limit": limit,
+            }.items()
+            if v is not None
+        }
+        return self._json("GET", "/v1/memories/", params=params)
+
+    def get(self, memory_id: str) -> Any:
+        return self._json("GET", f"/v1/memories/{memory_id}/")
+
+    def search(
+        self,
+        query: str,
+        *,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        limit: int = 10,
+    ) -> Any:
+        payload = {
+            "query": query,
+            "user_id": user_id,
+            "agent_id": agent_id,
+            "run_id": run_id,
+            "filters": filters,
+            "limit": limit,
+        }
+        return self._json("POST", "/v1/memories/search/", json=payload)
+
+    def update(self, memory_id: str, *, text: Optional[str] = None) -> Any:
+        if text is None:
+            raise ValueError("update(): provide text=...")
+        return self._json("PUT", f"/v1/memories/{memory_id}/", json={"text": text})
+
+    def history(self, memory_id: str) -> Any:
+        return self._json("GET", f"/v1/memories/{memory_id}/history/")
+
+    def delete(self, memory_id: str) -> Any:
+        return self._json("DELETE", f"/v1/memories/{memory_id}/")
+
+    def delete_all(
+        self,
+        *,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+    ) -> Any:
+        params = {
+            k: v
+            for k, v in {
+                "user_id": user_id,
+                "agent_id": agent_id,
+                "run_id": run_id,
+            }.items()
+            if v is not None
+        }
+        return self._json("DELETE", "/v1/memories/", params=params)
+
+    # ----- API-key management (Clerk JWT only — for dashboard parity) ----
+    def list_api_keys(self) -> Any:
+        return self._json("GET", "/v1/api-keys")
+
+    def create_api_key(
+        self,
+        name: str,
+        *,
+        scopes: Optional[List[str]] = None,
+        environment: str = "live",
+    ) -> Any:
+        return self._json(
+            "POST",
+            "/v1/api-keys",
+            json={"name": name, "scopes": scopes, "environment": environment},
+        )
+
+    def revoke_api_key(self, api_key_id: str) -> Any:
+        return self._json("DELETE", f"/v1/api-keys/{api_key_id}")
+
+    # ----- lifecycle ------------------------------------------------------
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "MemoryClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Async twin
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class AsyncMemoryClient:
+    """Async equivalent of :class:`MemoryClient` (httpx.AsyncClient under the hood)."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        host: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: Optional[httpx.AsyncClient] = None,
+        allow_dev_fallback: bool = True,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("OUTHAD_CONTEXTKIT_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError(
+                "Outhad ContextKit API key not provided.",
+                status=401,
+            )
+        explicit_host = host is not None or "OUTHAD_CONTEXTKIT_HOST" in os.environ
+        self.host = _select_host(host)
+        self.timeout = timeout
+        self._allow_fallback = allow_dev_fallback and not explicit_host
+        self._fell_back = False
+        self._owns_client = client is None
+
+        headers = {
+            "Authorization": f"Token {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "outhad-contextkit-sdk-python-async/1.0.0",
+        }
+        if client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self.host, timeout=timeout, headers=headers
+            )
+        else:
+            self._client = client
+            self._client.base_url = httpx.URL(self.host)
+            self._client.headers.update(headers)
+
+    # ----- private --------------------------------------------------------
+    def _retarget(self, host: str) -> None:
+        self.host = host.rstrip("/")
+        self._client.base_url = httpx.URL(self.host)
+        self._fell_back = True
+
+    async def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        try:
+            return await self._client.request(method, path, **kwargs)
+        except Exception as exc:
+            if (
+                self._allow_fallback
+                and not self._fell_back
+                and self.host == DEFAULT_HOST
+                and _is_connection_failure(exc)
+            ):
+                logger.warning(
+                    "Production host %s unreachable (%s) — retrying against %s",
+                    DEFAULT_HOST,
+                    exc.__class__.__name__,
+                    DEV_HOST,
+                )
+                self._retarget(DEV_HOST)
+                return await self._client.request(method, path, **kwargs)
+            raise
+
+    async def _json(self, method: str, path: str, **kwargs) -> Any:
+        resp = await self._request(method, path, **kwargs)
+        if not resp.is_success:
+            raise _decode_error(resp)
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    async def validate(self) -> Dict[str, Any]:
+        resp = await self._request("GET", "/v1/ping/")
+        if resp.status_code == 401:
+            raise AuthenticationError("API key rejected.", status=401)
+        if not resp.is_success:
+            raise APIError(
+                f"Failed to reach Outhad ContextKit cloud at {self.host}",
+                status=resp.status_code,
+                body=resp.text,
+            )
+        return resp.json() if resp.content else {}
+
+    # ----- memory CRUD ----------------------------------------------------
+    async def add(self, messages, **kw) -> Any:
+        return await self._json("POST", "/v1/memories/", json={"messages": messages, **kw})
+
+    async def get_all(self, **kw) -> Any:
+        return await self._json("GET", "/v1/memories/", params=kw)
+
+    async def get(self, memory_id: str) -> Any:
+        return await self._json("GET", f"/v1/memories/{memory_id}/")
+
+    async def search(self, query: str, **kw) -> Any:
+        return await self._json("POST", "/v1/memories/search/", json={"query": query, **kw})
+
+    async def update(self, memory_id: str, *, text: str) -> Any:
+        return await self._json("PUT", f"/v1/memories/{memory_id}/", json={"text": text})
+
+    async def history(self, memory_id: str) -> Any:
+        return await self._json("GET", f"/v1/memories/{memory_id}/history/")
+
+    async def delete(self, memory_id: str) -> Any:
+        return await self._json("DELETE", f"/v1/memories/{memory_id}/")
+
+    async def delete_all(self, **kw) -> Any:
+        return await self._json("DELETE", "/v1/memories/", params=kw)
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncMemoryClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()
+
+
+__all__ = [
+    "DEFAULT_HOST",
+    "DEV_HOST",
+    "AsyncMemoryClient",
+    "MemoryClient",
+]

outhad_contextkit_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "outhad-contextkit-sdk"
+version = "1.0.0"
+description = "Thin Python client for the Outhad ContextKit cloud — paywalled by API key minted at https://contextkit.outhad.com"
+authors = [
+    { name = "Outhad", email = "idrisitanzil@gmail.com" },
+]
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.9"
+keywords = [
+    "memory",
+    "ai",
+    "agents",
+    "long-term-memory",
+    "outhad",
+    "contextkit",
+    "sdk",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+# Intentionally lean — the whole point of this distribution is "thin
+# client only". No torch, no langchain, no vector store drivers, no
+# embedders. Just an HTTP client + JSON.
+dependencies = [
+    "httpx>=0.27.0",
+    "typing-extensions>=4.8.0; python_version<'3.11'",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.2.2",
+    "pytest-asyncio>=0.23.7",
+    "respx>=0.21.0",
+]
+
+[project.urls]
+Homepage = "https://contextkit.outhad.com"
+Documentation = "https://contextkit.outhad.com/docs"
+Source = "https://github.com/outhad/contextkit"
+Issues = "https://github.com/outhad/contextkit/issues"
+
+[tool.hatch.build]
+include = [
+    "outhad_contextkit_sdk/**/*.py",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["outhad_contextkit_sdk"]