kyber-runtime-sdk 1.0.1__py3-none-any.whl

kyber/memory/__init__.py

@@ -0,0 +1,140 @@
+"""Developer-facing access to Kyber Memory over gRPC."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Mapping, Optional
+
+from kyber.memory.client import MemoryClient, MemoryClientSettings
+from kyber.memory.errors import (
+    MemoryConfigurationError,
+    MemoryError,
+    MemoryRpcError,
+    MemoryValidationError,
+)
+from kyber.memory.models import MemoryItem, MemoryScope, MemoryWriteResult
+
+
+def get_memory(
+    context: Any = None,
+    *,
+    tenant_id: Optional[str] = None,
+    read_target: Optional[str] = None,
+    write_target: Optional[str] = None,
+    platform_auth: Optional[str] = None,
+    identity_token: Optional[str] = None,
+    agent_id: Optional[str] = None,
+    circuit_id: Optional[str] = None,
+    timeout_seconds: Optional[float] = None,
+    tls: Optional[bool] = None,
+    root_certificate_path: Optional[Path] = None,
+) -> MemoryClient:
+    """Build a memory client from explicit, runtime-context, or environment values.
+
+    Developers supply user_id/project_id/session_id to individual operations. Tenant,
+    agent, circuit, endpoint, and credential values are runtime-owned configuration.
+    """
+
+    tenant_id = _setting(tenant_id, context, "tenant_id", "KYBER_TENANT_ID")
+    if not tenant_id:
+        raise MemoryConfigurationError(
+            "Memory tenant identity is not configured; set KYBER_TENANT_ID"
+        )
+    if len(str(tenant_id)) > 255:
+        raise MemoryConfigurationError("tenant_id must contain at most 255 characters")
+
+    configured_timeout = _setting(
+        timeout_seconds,
+        context,
+        "memory_timeout_seconds",
+        "KYBER_MEMORY_GRPC_TIMEOUT_SECONDS",
+    )
+    try:
+        resolved_timeout = float(configured_timeout or 30.0)
+    except (TypeError, ValueError) as exc:
+        raise MemoryConfigurationError(
+            "KYBER_MEMORY_GRPC_TIMEOUT_SECONDS must be a number"
+        ) from exc
+    if resolved_timeout <= 0:
+        raise MemoryConfigurationError("Memory gRPC timeout must be greater than zero")
+
+    configured_tls = _setting(tls, context, "memory_tls", "KYBER_MEMORY_GRPC_TLS")
+    resolved_tls = _boolean(configured_tls, default=True)
+    certificate = _setting(
+        root_certificate_path,
+        context,
+        "memory_root_certificate_path",
+        "KYBER_MEMORY_GRPC_ROOT_CERTIFICATE",
+    )
+
+    return MemoryClient(
+        MemoryClientSettings(
+            tenant_id=str(tenant_id),
+            read_target=_setting(
+                read_target,
+                context,
+                "memory_read_target",
+                "KYBER_MEMORY_GRPC_TARGET",
+            ),
+            write_target=_setting(
+                write_target,
+                context,
+                "memory_write_target",
+                "KYBER_MEMORY_WRITE_GRPC_TARGET",
+            ),
+            platform_auth=_setting(
+                platform_auth,
+                context,
+                "memory_platform_auth",
+                "KYBER_MEMORY_PLATFORM_AUTH",
+            ),
+            identity_token=_setting(
+                identity_token,
+                context,
+                "identity_token",
+                "KYBER_MEMORY_IDENTITY_TOKEN",
+            ),
+            agent_id=_setting(agent_id, context, "agent_id", "KYBER_AGENT_ID"),
+            circuit_id=_setting(circuit_id, context, "circuit_id", "KYBER_CIRCUIT_ID"),
+            timeout_seconds=resolved_timeout,
+            tls=resolved_tls,
+            root_certificate_path=Path(certificate) if certificate else None,
+        )
+    )
+
+
+def _setting(explicit, context, context_name: str, environment_name: str):
+    if explicit is not None:
+        return explicit
+    if isinstance(context, Mapping):
+        value = context.get(context_name)
+    else:
+        value = getattr(context, context_name, None) if context is not None else None
+    return value if value is not None else os.environ.get(environment_name)
+
+
+def _boolean(value, *, default: bool) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    normalized = str(value).strip().lower()
+    if normalized in {"1", "true", "yes", "on"}:
+        return True
+    if normalized in {"0", "false", "no", "off"}:
+        return False
+    raise MemoryConfigurationError("KYBER_MEMORY_GRPC_TLS must be true or false")
+
+
+__all__ = [
+    "MemoryClient",
+    "MemoryConfigurationError",
+    "MemoryError",
+    "MemoryItem",
+    "MemoryRpcError",
+    "MemoryScope",
+    "MemoryValidationError",
+    "MemoryWriteResult",
+    "get_memory",
+]