tex-sdk 0.3.0__py3-none-any.whl

tex/__init__.py

@@ -0,0 +1,20 @@
+"""Tex Python SDK.
+
+User-facing, lightweight wrapper around IntegrationBackend HTTP endpoints.
+"""
+
+from .client import AskResult, Tex
+from .config import TexConfig, TexEndpoints
+from .errors import TexAuthError, TexError, TexHTTPError
+
+__all__ = [
+    "Tex",
+    "AskResult",
+    "TexConfig",
+    "TexEndpoints",
+    "TexError",
+    "TexAuthError",
+    "TexHTTPError",
+]
+
+__version__ = "0.3.0"

tex/client.py

@@ -0,0 +1,629 @@
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Optional, Tuple, Union
+
+import httpx
+
+from .config import TexConfig
+from .errors import TexAuthError, TexHTTPError
+
+
+_CID_HEADER = "X-Correlation-ID"
+
+
+@dataclass(frozen=True)
+class AskResult:
+    """User-friendly NLQ output."""
+
+    text: str
+    evidence: List[str]
+    entities: List[str]
+    documents: List[str]
+    raw: Dict[str, Any]
+
+
+class Tex:
+    """Minimal user-facing SDK for IntegrationBackend."""
+
+    def __init__(self, config: Union[TexConfig, str], **kwargs: Any):
+        if isinstance(config, str):
+            self._config = TexConfig(base_url=config, **kwargs)
+        else:
+            self._config = config
+
+        base_url = self._config.base_url.rstrip("/")
+        try:
+            self._client = httpx.Client(
+                base_url=base_url,
+                timeout=self._config.timeout_s,
+                http2=self._config.http2,
+                headers={"Accept": "application/json"},
+            )
+        except ImportError as e:
+            # httpx requires optional dependency `h2` for HTTP/2.
+            # Fall back to HTTP/1.1 to keep the SDK lightweight by default.
+            if "h2" in str(e):
+                self._client = httpx.Client(
+                    base_url=base_url,
+                    timeout=self._config.timeout_s,
+                    http2=False,
+                    headers={"Accept": "application/json"},
+                )
+                self._config.http2 = False
+            else:
+                raise
+
+        self._access_token = self._config.access_token
+        self._refresh_token = self._config.refresh_token
+        self._tenant: Optional[Dict[str, Any]] = None
+
+        # Capture whether the caller explicitly provided user-scoping inputs.
+        # The SDK may later backfill org_id/user_id/session_id from /auth/verify; that should NOT
+        # trigger a user login flow unless the caller explicitly requested it.
+        self._explicit_org_id = self._config.org_id
+        self._explicit_user_id = self._config.user_id
+        self._explicit_session_id = self._config.session_id
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "Tex":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    # ----------------------------- Public API -----------------------------
+
+    def store_memory(
+        self,
+        content: Union[str, List[Dict[str, Any]]],
+        *,
+        type: str = "document",
+        format: str = "text",
+        metadata: Optional[Dict[str, Any]] = None,
+        options: Optional[Dict[str, Any]] = None,
+        episode_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Single ingestion entrypoint.
+
+        - type="document": content is a string
+        - type="episode": content is a string or list of chat messages
+        - type="preference": content is ignored; pass preferences via metadata["preferences"]
+        """
+
+        t = type.strip().lower()
+        if t == "document":
+            if not isinstance(content, str):
+                raise ValueError("For type='document', content must be a string")
+            payload: Dict[str, Any] = {
+                "data": content,
+                "format": format,
+                "scope": self._scope_payload(),
+                "metadata": metadata,
+                "options": options,
+            }
+            return self._post(self._config.endpoints.ingestion_document, payload)
+
+        if t == "episode":
+            messages = self._coerce_messages(content)
+            payload = {
+                "episode_id": episode_id,
+                "messages": messages,
+                "scope": self._scope_payload(),
+                "metadata": metadata,
+                "options": options,
+            }
+            return self._post(self._config.endpoints.ingestion_episode, payload)
+
+        if t in ("preference", "preferences"):
+            preferences = None
+            if metadata and isinstance(metadata, dict):
+                preferences = metadata.get("preferences")
+            if not isinstance(preferences, list) or not preferences:
+                raise ValueError("For type='preference', pass metadata={'preferences': [...]} ")
+            scope = self._scope_payload()
+            payload = {
+                "org_id": scope.get("org_id") or "_",
+                "user_id": scope.get("user_id") or "_",
+                "session_id": self._config.session_id,
+                "preferences": preferences,
+            }
+            return self._post(self._config.endpoints.ingestion_preference, payload)
+
+        raise ValueError("type must be one of: document, episode, preference")
+
+    def job(self, job_id: str) -> Dict[str, Any]:
+        path = self._config.endpoints.ingestion_status.format(job_id=job_id)
+        return self._get(path)
+
+    def query(self, query: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        payload = {"query": query, "params": params or {}}
+        return self._post(self._config.endpoints.db_query, payload)
+
+    def schema(self) -> Dict[str, Any]:
+        return self._get(self._config.endpoints.db_schema)
+
+    def ask(
+        self,
+        question: str,
+        *,
+        execute: bool = True,
+        enable_pruning: bool = True,
+        use_local_intelligence: bool = True,
+        intent_match_options: Optional[Dict[str, Any]] = None,
+        compact: bool = True,
+    ) -> AskResult:
+        payload: Dict[str, Any] = {
+            "query": question,
+            "execute": execute,
+            "enable_pruning": enable_pruning,
+            "use_local_intelligence": use_local_intelligence,
+            "compact": compact,
+        }
+        if intent_match_options is not None:
+            payload["intent_match_options"] = intent_match_options
+
+        raw = self._post(self._config.endpoints.nlq_execute, payload)
+        return self._simplify_nlq(raw)
+
+    def whoami(self) -> Dict[str, Any]:
+        """Return the tenant context as seen by IntegrationBackend (useful for debugging)."""
+        self._ensure_auth()
+        self._ensure_tenant()
+        return dict(self._tenant or {})
+
+    # ----------------------------- Search ---------------------------------
+
+    def search(
+        self,
+        query: str,
+        *,
+        top_k: int = 10,
+        min_score: Optional[float] = None,
+        label: Optional[str] = None,
+        metadata_filter: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Fast semantic vector search across all indexed nodes.
+
+        Returns ``{ results: [{ id, label, score, properties, content_preview }], total_results, query }``
+        """
+
+        payload: Dict[str, Any] = {"query": query, "top_k": top_k}
+        if min_score is not None:
+            payload["min_score"] = min_score
+        if label is not None:
+            payload["label"] = label
+        if metadata_filter is not None:
+            payload["metadata_filter"] = metadata_filter
+        return self._post(self._config.endpoints.search, payload)
+
+    # ----------------------------- Memories CRUD --------------------------
+
+    def get_memory(self, memory_id: str) -> Dict[str, Any]:
+        """Retrieve a single memory by ID."""
+        path = self._config.endpoints.memories_get.format(memory_id=memory_id)
+        return self._get(path)
+
+    def list_memories(
+        self,
+        *,
+        type: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> Dict[str, Any]:
+        """List memories with optional type filter and pagination.
+
+        Returns ``{ memories: [...], total, limit, offset }``
+        """
+
+        params: Dict[str, Any] = {"limit": limit, "offset": offset}
+        if type is not None:
+            params["type"] = type
+        return self._request("GET", self._config.endpoints.memories_list, query_params=params)
+
+    def delete_memory(self, memory_id: str) -> Dict[str, Any]:
+        """Soft-delete a memory by ID.
+
+        Returns ``{ deleted: true, memory_id }``
+        """
+
+        path = self._config.endpoints.memories_delete.format(memory_id=memory_id)
+        return self._request("DELETE", path)
+
+    def delete_memories(self, *, user_id: Optional[str] = None) -> Dict[str, Any]:
+        """Bulk soft-delete memories.
+
+        - If `user_id` is omitted, deletes the caller's own memories.
+        - If `user_id` is provided and differs from the caller, IntegrationBackend requires
+          elevated roles.
+        """
+
+        params: Dict[str, Any] = {}
+        if user_id is not None:
+            params["user_id"] = user_id
+        return self._request(
+            "DELETE",
+            self._config.endpoints.memories_list,
+            query_params=params,
+        )
+
+    def update_memory(
+        self,
+        memory_id: str,
+        *,
+        content: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        options: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Update a memory by ID."""
+
+        payload: Dict[str, Any] = {}
+        if content is not None:
+            payload["content"] = content
+        if metadata is not None:
+            payload["metadata"] = metadata
+        if options is not None:
+            payload["options"] = options
+
+        path = self._config.endpoints.memories_update.format(memory_id=memory_id)
+        return self._request("PATCH", path, json_body=payload)
+
+    # ----------------------------- Episodes -------------------------------
+
+    def list_episodes(
+        self,
+        *,
+        limit: int = 50,
+        offset: int = 0,
+        since: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """List episodic memory entries.
+
+        Returns ``{ episodes: [...], total, limit, offset }``
+        """
+
+        params: Dict[str, Any] = {"limit": limit, "offset": offset}
+        if since is not None:
+            params["since"] = since
+        return self._request("GET", self._config.endpoints.episodes_list, query_params=params)
+
+    # ----------------------------- User Profile ----------------------------
+
+    def get_profile(self, *, format: str = "text") -> Dict[str, Any]:
+        """Return synthesised user profile from preferences and episodic memories.
+
+        Returns ``{ user_id, preferences: [...], profile_text, episode_count }``
+        """
+
+        return self._request("GET", self._config.endpoints.user_profile, query_params={"format": format})
+
+    # ----------------------------- Batch Ingestion -------------------------
+
+    def batch_store(
+        self,
+        documents: Iterable[Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        """Ingest multiple documents in one call.
+
+        Each document dict should have: ``data`` (str), and optionally
+        ``format``, ``metadata``, ``options``.
+
+        Returns ``{ batch_id, total_documents, job_ids: [...] }``
+        """
+
+        payload = {"documents": list(documents)}
+        return self._post(self._config.endpoints.ingestion_batch, payload)
+
+    # ---------------------------- Internal bits ----------------------------
+
+    def _scope_payload(self) -> Dict[str, Any]:
+        # IntegrationBackend ultimately uses tenant from JWT; `scope` is still required by the request model.
+        # For API-key auth, org_id/user_id may not be provided by the user; we lazily discover via /auth/verify.
+        self._ensure_auth()
+        if not self._config.org_id or not self._config.user_id:
+            self._ensure_tenant()
+
+        org_id = self._config.org_id or (self._tenant or {}).get("org_id") or "_"
+        user_id = self._config.user_id or (self._tenant or {}).get("user_id") or "_"
+        session_id = self._config.session_id or (self._tenant or {}).get("session_id")
+
+        return {"org_id": org_id, "user_id": user_id, "session_id": session_id}
+
+    def _ensure_tenant(self) -> None:
+        if self._tenant is not None and self._tenant.get("org_id") and self._tenant.get("user_id"):
+            return
+
+        # Call /auth/verify to get tenant claims (org_id/user_id/session_id)
+        try:
+            data = self._request("GET", self._config.endpoints.auth_verify)
+            tenant = data.get("tenant") if isinstance(data, dict) else None
+            if isinstance(tenant, dict):
+                self._tenant = tenant
+                # Backfill config fields so subsequent requests avoid verify call.
+                if not self._config.org_id and isinstance(tenant.get("org_id"), str):
+                    self._config.org_id = tenant.get("org_id")
+                if not self._config.user_id and isinstance(tenant.get("user_id"), str):
+                    self._config.user_id = tenant.get("user_id")
+                if not self._config.session_id and isinstance(tenant.get("session_id"), str):
+                    self._config.session_id = tenant.get("session_id")
+                return
+        except TexHTTPError:
+            # Non-fatal: we can still send placeholder scope; backend ignores it and uses JWT tenant.
+            pass
+
+        self._tenant = self._tenant or {}
+
+    def _coerce_messages(self, content: Union[str, List[Dict[str, Any]]]) -> List[Dict[str, Any]]:
+        if isinstance(content, str):
+            return [{"role": "user", "content": content}]
+        if isinstance(content, list) and content and all(isinstance(m, dict) for m in content):
+            return content
+        raise ValueError("For type='episode', content must be a string or list of {role, content} messages")
+
+    def _simplify_nlq(self, raw: Dict[str, Any]) -> AskResult:
+        evidence: List[str] = []
+        entities: List[str] = []
+        documents: List[str] = []
+
+        intent_matches = (raw.get("intent_matches") or {}) if isinstance(raw, dict) else {}
+        matches = intent_matches.get("matches") if isinstance(intent_matches, dict) else None
+        if isinstance(matches, list):
+            for match in matches:
+                if not isinstance(match, dict):
+                    continue
+                for ev in match.get("evidence", []) or []:
+                    if isinstance(ev, dict):
+                        txt = ev.get("text")
+                        if isinstance(txt, str) and txt.strip():
+                            evidence.append(txt.strip())
+                bindings = match.get("bindings")
+                if isinstance(bindings, dict):
+                    for b in bindings.values():
+                        if isinstance(b, dict):
+                            name = b.get("entity_name") or b.get("canonical_id")
+                            if isinstance(name, str) and name.strip():
+                                entities.append(name.strip())
+                for d in match.get("documents", []) or []:
+                    if isinstance(d, dict):
+                        name = d.get("entity_name") or d.get("canonical_id")
+                        if isinstance(name, str) and name.strip():
+                            documents.append(name.strip())
+
+        evidence = list(dict.fromkeys(evidence))
+        entities = list(dict.fromkeys(entities))
+        documents = list(dict.fromkeys(documents))
+
+        lines: List[str] = []
+        if evidence:
+            lines.append("Evidence:\n" + "\n".join(f"- {e}" for e in evidence[:50]))
+        if entities:
+            lines.append("Entities:\n" + "\n".join(f"- {e}" for e in entities[:50]))
+        if documents:
+            lines.append("Documents:\n" + "\n".join(f"- {d}" for d in documents[:50]))
+        text = "\n\n".join(lines).strip() or "No evidence returned."
+
+        return AskResult(text=text, evidence=evidence, entities=entities, documents=documents, raw=raw)
+
+    def _ensure_auth(self) -> None:
+        if self._access_token:
+            return
+        ep = self._config.endpoints
+
+        if self._config.access_token:
+            self._access_token = self._config.access_token
+            self._refresh_token = self._config.refresh_token
+            return
+
+        if self._config.api_key:
+            # Exchange org API key -> JWT
+            tokens = self._post_noauth(ep.auth_token_exchange, {"api_key": self._config.api_key})
+            access = tokens.get("access_token")
+            refresh = tokens.get("refresh_token")
+            if not access:
+                raise TexAuthError("Token exchange did not return access_token", status_code=401)
+            self._access_token = access
+            self._refresh_token = refresh
+
+            # Discover org_id/user_id/session_id from /auth/verify
+            self._ensure_tenant()
+
+            # Optional: if user_id was explicitly provided by the caller, mint a user-scoped JWT via /auth/login.
+            if self._explicit_user_id:
+                org_id = self._explicit_org_id or self._config.org_id or (self._tenant or {}).get("org_id")
+                if not isinstance(org_id, str) or not org_id:
+                    raise TexAuthError("Could not determine org_id for user login", status_code=401)
+                login_tokens = self._post_noauth(
+                    ep.auth_login,
+                    {
+                        "org_id": org_id,
+                        "user_id": self._explicit_user_id,
+                        "session_id": self._explicit_session_id,
+                    },
+                )
+                self._access_token = login_tokens.get("access_token")
+                self._refresh_token = login_tokens.get("refresh_token")
+                if not self._access_token:
+                    raise TexAuthError("Login did not return access_token", status_code=401)
+                self._tenant = None
+                self._ensure_tenant()
+
+            return
+
+        if self._config.org_id and self._config.user_id:
+            tokens = self._post_noauth(
+                ep.auth_login,
+                {
+                    "org_id": self._config.org_id,
+                    "user_id": self._config.user_id,
+                    "session_id": self._config.session_id,
+                },
+            )
+            self._access_token = tokens.get("access_token")
+            self._refresh_token = tokens.get("refresh_token")
+            if not self._access_token:
+                raise TexAuthError("Login did not return access_token", status_code=401)
+            return
+
+        raise TexAuthError(
+            "No auth configured. Provide api_key, or org_id+user_id, or access_token.",
+            status_code=401,
+        )
+
+    def _refresh(self) -> None:
+        ep = self._config.endpoints
+        if self._refresh_token:
+            tokens = self._post_noauth(ep.auth_refresh, {"refresh_token": self._refresh_token})
+            self._access_token = tokens.get("access_token")
+            self._refresh_token = tokens.get("refresh_token")
+            if self._access_token:
+                return
+
+        # Fallback: re-exchange api key
+        if self._config.api_key:
+            if self._explicit_user_id:
+                org_id = self._explicit_org_id or self._config.org_id or (self._tenant or {}).get("org_id")
+                if not org_id:
+                    self._access_token = None
+                    self._refresh_token = None
+                    self._tenant = None
+                    self._ensure_auth()
+                    return
+                login_tokens = self._post_noauth(
+                    ep.auth_login,
+                    {
+                        "org_id": org_id,
+                        "user_id": self._explicit_user_id,
+                        "session_id": self._explicit_session_id,
+                    },
+                )
+                self._access_token = login_tokens.get("access_token")
+                self._refresh_token = login_tokens.get("refresh_token")
+                if self._access_token:
+                    self._tenant = None
+                    return
+
+            self._access_token = None
+            self._refresh_token = None
+            self._tenant = None
+            self._ensure_auth()
+            return
+
+        raise TexAuthError("Authentication expired and could not be refreshed", status_code=401)
+
+    def _headers(self) -> Dict[str, str]:
+        self._ensure_auth()
+        return {
+            "Authorization": f"Bearer {self._access_token}",
+            _CID_HEADER: str(uuid.uuid4()),
+        }
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json_body: Any = None,
+        query_params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        headers = self._headers()
+        try:
+            resp = self._client.request(method, path, json=json_body, params=query_params, headers=headers)
+        except httpx.TimeoutException as e:
+            raise TexHTTPError("Request timed out", details=str(e))
+        except httpx.HTTPError as e:
+            raise TexHTTPError("Network error", details=str(e))
+
+        if resp.status_code == 401:
+            self._refresh()
+            headers = self._headers()
+            resp = self._client.request(method, path, json=json_body, params=query_params, headers=headers)
+
+        request_id = resp.headers.get(_CID_HEADER)
+        if resp.status_code >= 400:
+            msg, details = self._safe_error_from_response(resp)
+            msg = self._decorate_error_message(msg, resp.status_code, details)
+            exc_cls = TexAuthError if resp.status_code in (401, 403) else TexHTTPError
+            raise exc_cls(
+                msg,
+                status_code=resp.status_code,
+                request_id=request_id,
+                response_text=(resp.text[:2000] if resp.text else None),
+                details=details,
+            )
+
+        if not resp.content:
+            return {}
+        try:
+            data = resp.json()
+            return data if isinstance(data, dict) else {"data": data}
+        except Exception:
+            return {"data": resp.text}
+
+    def _safe_error_from_response(self, resp: httpx.Response) -> Tuple[str, Any]:
+        try:
+            payload = resp.json()
+            if isinstance(payload, dict):
+                detail = payload.get("detail")
+                if isinstance(detail, str) and detail.strip():
+                    return detail, payload
+                if detail is not None:
+                    try:
+                        return json.dumps(detail, ensure_ascii=False), payload
+                    except Exception:
+                        return str(detail), payload
+
+                message = payload.get("message")
+                if isinstance(message, str) and message.strip():
+                    return message, payload
+                return "Request failed", payload
+            return "Request failed", payload
+        except Exception:
+            return "Request failed", resp.text
+
+    def _decorate_error_message(self, msg: str, status_code: int, details: Any) -> str:
+        if not isinstance(msg, str) or not msg.strip():
+            return "Request failed"
+
+        if status_code == 422:
+            lowered = msg.lower()
+            if "intentgraph validation" in lowered or "root variable must have a type" in lowered:
+                return (
+                    f"{msg.strip()}\n\n"
+                    "Hint: this is usually a planner/schema issue. Verify the DB has a non-empty schema "
+                    "and that the backend can fetch it (e.g., GET /schema-json and POST /planner/plan)."
+                )
+
+        return msg.strip()
+
+    def _get(self, path: str) -> Dict[str, Any]:
+        return self._request("GET", path)
+
+    def _post(self, path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", path, payload)
+
+    def _post_noauth(self, path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        headers = {_CID_HEADER: str(uuid.uuid4())}
+        try:
+            resp = self._client.post(path, json=payload, headers=headers)
+        except httpx.TimeoutException as e:
+            raise TexHTTPError("Request timed out", details=str(e))
+        except httpx.HTTPError as e:
+            raise TexHTTPError("Network error", details=str(e))
+
+        request_id = resp.headers.get(_CID_HEADER)
+        if resp.status_code >= 400:
+            msg, details = self._safe_error_from_response(resp)
+            msg = self._decorate_error_message(msg, resp.status_code, details)
+            raise TexAuthError(
+                msg,
+                status_code=resp.status_code,
+                request_id=request_id,
+                response_text=(resp.text[:2000] if resp.text else None),
+                details=details,
+            )
+
+        data = resp.json()
+        return data if isinstance(data, dict) else {"data": data}

tex/config.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class TexEndpoints:
+    """IntegrationBackend endpoint paths (override to match deployments)."""
+
+    # Auth
+    auth_login: str = "/auth/login"
+    auth_refresh: str = "/auth/refresh"
+    auth_token_exchange: str = "/auth/token-exchange"
+    auth_verify: str = "/auth/verify"
+
+    # Core ingestion
+    ingestion_document: str = "/ingestion/document"
+    ingestion_episode: str = "/ingestion/episode"
+    ingestion_preference: str = "/ingestion/preference"
+    ingestion_status: str = "/ingestion/status/{job_id}"
+    ingestion_batch: str = "/ingestion/batch"
+
+    # DB
+    db_query: str = "/helixdb/query"
+    db_schema: str = "/helixdb/schema"
+
+    # NLQ
+    nlq_execute: str = "/nlq/execute"
+
+    # Search
+    search: str = "/search"
+
+    # Memories CRUD
+    memories_list: str = "/memories"
+    memories_get: str = "/memories/{memory_id}"
+    memories_delete: str = "/memories/{memory_id}"
+    memories_update: str = "/memories/{memory_id}"
+
+    # Episodes
+    episodes_list: str = "/memories/episodes"
+
+    # Users
+    user_profile: str = "/users/profile"
+
+
+@dataclass
+class TexConfig:
+    """SDK configuration.
+
+    Auth options:
+    - api_key: exchanges via /auth/token-exchange
+    - org_id + user_id (+ optional session_id): obtains tokens via /auth/login
+    - access_token: directly uses provided token
+    """
+
+    base_url: str
+
+    # One of these auth modes should be set
+    api_key: Optional[str] = None
+    org_id: Optional[str] = None
+    user_id: Optional[str] = None
+    session_id: Optional[str] = None
+    access_token: Optional[str] = None
+    refresh_token: Optional[str] = None
+
+    # Transport
+    timeout_s: float = 15.0
+    http2: bool = True
+    endpoints: TexEndpoints = field(default_factory=TexEndpoints)

tex/errors.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+class TexError(RuntimeError):
+    """Base SDK error."""
+
+
+@dataclass
+class TexHTTPError(TexError):
+    message: str
+    status_code: Optional[int] = None
+    request_id: Optional[str] = None
+    response_text: Optional[str] = None
+    details: Any = None
+
+    def __str__(self) -> str:
+        base = self.message
+        if self.status_code is not None:
+            base = f"HTTP {self.status_code}: {base}"
+        if self.request_id:
+            base = f"{base} (request_id={self.request_id})"
+        return base
+
+
+class TexAuthError(TexHTTPError):
+    """Authentication/authorization error."""

tex_sdk-0.3.0.dist-info/METADATA

@@ -0,0 +1,627 @@
+Metadata-Version: 2.4
+Name: tex-sdk
+Version: 0.3.0
+Summary: Tex Python SDK for IntegrationBackend
+Author: Tex
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: http2
+Requires-Dist: h2>=4.1.0; extra == "http2"
+
+# Tex SDK (Python)
+
+Tex is a lightweight Python client for Tex’s IntegrationBackend HTTP API.
+
+This README is intentionally implementation-grounded: it documents exactly what the SDK does today based on the code in:
+
+- `tex/__init__.py` (public exports)
+- `tex/config.py` (endpoint paths + config)
+- `tex/client.py` (client behavior, auth, retries, request/response handling)
+- `tex/errors.py` (error types)
+
+If you are reading this inside the repo, those files are the source of truth.
+
+## What you get
+
+- One client class: `Tex`
+- Three auth modes (API key, org+user login, or direct access token)
+- Minimal, predictable return values: most methods return JSON as `dict`
+- Friendly NLQ output via `AskResult`
+- Typed package (`tex/py.typed`) for mypy/pyright
+
+## Install
+
+```bash
+pip install tex-sdk
+```
+
+Optional: enable HTTP/2 (requires `h2`):
+
+```bash
+pip install "tex-sdk[http2]"
+```
+
+Python requirement (from `pyproject.toml`): Python 3.9+
+
+## Quick start
+
+Important: the SDK’s `base_url` must point at IntegrationBackend (the FastAPI gateway), not HelixDB directly.
+
+### 1) API key auth (recommended)
+
+This is the simplest and most “production-like” flow.
+
+```python
+from tex import Tex
+
+tx = Tex("http://localhost:8000", api_key="sk_live_...")
+
+tx.store_memory(
+    "Hello from Tex SDK.",
+    type="document",
+    metadata={"source": "quickstart"},
+)
+
+answer = tx.ask("What did I just store?")
+print(answer.text)
+```
+
+### 2) Org + user login (dev / testing)
+
+If your IntegrationBackend allows `/auth/login` for a given org+user, you can use:
+
+```python
+from tex import Tex
+
+tx = Tex(
+    "http://localhost:8000",
+    org_id="org_123",
+    user_id="user_456",
+    session_id="s1",  # optional
+)
+
+tx.store_memory("I like espresso.", type="document")
+print(tx.ask("What do I like?").text)
+```
+
+### 3) Direct access token (bring-your-own JWT)
+
+If you already obtained an access token (e.g., out-of-band), pass it directly:
+
+```python
+from tex import Tex
+
+tx = Tex("http://localhost:8000", access_token="eyJ...")
+print(tx.whoami())
+```
+
+## The public API surface
+
+The package exports (see `tex/__init__.py`):
+
+- `Tex`
+- `AskResult`
+- `TexConfig`, `TexEndpoints`
+- `TexError`, `TexAuthError`, `TexHTTPError`
+
+## Concepts
+
+### Multi-tenant scope
+
+IntegrationBackend is multi-tenant. Requests typically belong to a tenant:
+
+- `org_id`
+- `user_id`
+- `session_id` (optional)
+
+In the SDK, “scope” is included in ingestion payloads via `Tex._scope_payload()`. Internally:
+
+- The backend ultimately trusts the JWT for tenant claims.
+- The SDK still sends `scope` because the request models expect it.
+- When using API keys, the SDK attempts to discover tenant claims by calling `GET /auth/verify`.
+
+If tenant discovery fails, the SDK may send placeholders (`"_"`) for `org_id`/`user_id`; the backend is expected to ignore these and use the JWT tenant instead.
+
+### Correlation IDs
+
+Each request includes a unique `X-Correlation-ID` header generated per request (see `tex/client.py`).
+
+- This is useful for tracing requests through your logs.
+- When available, the SDK also exposes this as `request_id` on raised exceptions.
+
+## Authentication: exact behavior
+
+This section mirrors `Tex._ensure_auth()` and `Tex._refresh()` in `tex/client.py`.
+
+### Auth modes (in priority order)
+
+When the SDK needs auth, it chooses the first available:
+
+1) If `access_token` is already present in memory → use it.
+2) If `TexConfig.access_token` is provided → use it.
+3) Else if `api_key` is provided:
+   - `POST /auth/token-exchange` with `{ "api_key": "..." }` → get `access_token` (+ optional `refresh_token`)
+   - `GET /auth/verify` to discover tenant claims
+   - If you also explicitly provided `user_id`, the SDK then calls `POST /auth/login` to mint a user-scoped token.
+4) Else if `org_id` + `user_id` is provided:
+   - `POST /auth/login` with `{ org_id, user_id, session_id }`
+5) Otherwise → raise `TexAuthError` (“No auth configured...”).
+
+### Refresh + retry
+
+All authenticated requests go through `_request()`.
+
+- If a request returns HTTP 401:
+  - The SDK attempts `_refresh()` and retries the request once.
+- Refresh rules:
+  - If `refresh_token` exists: `POST /auth/refresh`.
+  - Else if `api_key` exists: re-exchange the API key (and, if `user_id` was set, re-login).
+  - Otherwise: raise `TexAuthError`.
+
+## Configuration
+
+### `TexConfig`
+
+You can construct the client with either:
+
+- A `base_url` string: `Tex("http://localhost:8000", api_key=...)`
+- A `TexConfig` object: `Tex(TexConfig(base_url=..., api_key=...))`
+
+Fields (see `tex/config.py`):
+
+- `base_url`: IntegrationBackend URL, e.g. `http://localhost:8000`
+- Auth fields: `api_key`, `org_id`, `user_id`, `session_id`, `access_token`, `refresh_token`
+- Transport: `timeout_s` (default 15s), `http2` (default True)
+- `endpoints`: a `TexEndpoints` instance
+
+### `TexEndpoints`
+
+`TexEndpoints` contains the path strings the SDK calls (all relative to `base_url`).
+
+Defaults (see `tex/config.py`):
+
+- Auth:
+  - `auth_login`: `/auth/login`
+  - `auth_refresh`: `/auth/refresh`
+  - `auth_token_exchange`: `/auth/token-exchange`
+  - `auth_verify`: `/auth/verify`
+- Ingestion:
+  - `ingestion_document`: `/ingestion/document`
+  - `ingestion_episode`: `/ingestion/episode`
+  - `ingestion_preference`: `/ingestion/preference`
+  - `ingestion_status`: `/ingestion/status/{job_id}`
+  - `ingestion_batch`: `/ingestion/batch`
+- DB:
+  - `db_query`: `/helixdb/query`
+  - `db_schema`: `/helixdb/schema`
+- NLQ: `nlq_execute`: `/nlq/execute`
+- Search: `search`: `/search`
+- Memories CRUD: `memories_list`, `memories_get`, `memories_delete`, `memories_update`
+- Episodes: `episodes_list`: `/memories/episodes`
+- Users: `user_profile`: `/users/profile`
+
+If your deployment uses different routes/prefixes, override:
+
+```python
+from tex import Tex, TexConfig, TexEndpoints
+
+endpoints = TexEndpoints(
+    # example override
+    db_query="/db/query",
+    db_schema="/db/schema",
+)
+
+tx = Tex(TexConfig(base_url="https://api.example.com", api_key="sk_live_...", endpoints=endpoints))
+```
+
+## API reference (method-by-method)
+
+All examples assume:
+
+```python
+from tex import Tex
+
+tx = Tex("http://localhost:8000", api_key="sk_live_...")
+```
+
+### `Tex.store_memory(...)`
+
+Single ingestion entrypoint. Behavior depends on `type`.
+
+Signature (from `tex/client.py`):
+
+- `content`: `str` or `list[dict]` (depending on `type`)
+- `type`: one of `"document"`, `"episode"`, `"preference"`
+- `format`: for documents, default `"text"`
+- `metadata`: optional dict
+- `options`: optional dict (passed through)
+- `episode_id`: only for episode ingestion
+
+#### Document ingestion (`type="document"`)
+
+```python
+resp = tx.store_memory(
+    "A short document to ingest.",
+    type="document",
+    format="text",
+    metadata={"source": "docs"},
+)
+print(resp)
+```
+
+Notes:
+
+- For `type="document"`, `content` must be a string or the SDK raises `ValueError`.
+- The request payload includes `scope` derived from your auth.
+
+#### Episode ingestion (`type="episode"`)
+
+Episodes represent chat-like messages.
+
+You can pass a single string (it becomes one `{"role":"user","content":...}` message):
+
+```python
+resp = tx.store_memory(
+    "Today I called Alice and discussed the plan.",
+    type="episode",
+)
+```
+
+Or pass a message list:
+
+```python
+messages = [
+    {"role": "user", "content": "Book a table for two."},
+    {"role": "assistant", "content": "Which restaurant?"},
+    {"role": "user", "content": "Somewhere near downtown."},
+]
+
+resp = tx.store_memory(messages, type="episode", episode_id="ep_001")
+```
+
+If you pass an invalid structure, the SDK raises `ValueError`.
+
+#### Preference ingestion (`type="preference"`)
+
+Preference ingestion expects preferences in `metadata["preferences"]`.
+
+```python
+resp = tx.store_memory(
+    "ignored",
+    type="preference",
+    metadata={
+        "preferences": [
+            {"key": "drink", "value": "espresso", "confidence": 0.9},
+        ]
+    },
+)
+```
+
+Important:
+
+- For `type="preference"`, the SDK ignores `content` and requires a non-empty list at `metadata["preferences"]`.
+- The SDK sends `{ org_id, user_id, session_id, preferences }` using discovered scope.
+
+### `Tex.job(job_id)`
+
+Fetch background ingestion status.
+
+```python
+status = tx.job("job_...")
+print(status)
+```
+
+Internally calls `GET /ingestion/status/{job_id}`.
+
+### `Tex.batch_store(documents)`
+
+Ingest multiple documents in one call.
+
+Each document dict should contain:
+
+- `data` (str)
+- optional `format`, `metadata`, `options`
+
+```python
+resp = tx.batch_store(
+    [
+        {"data": "doc 1", "metadata": {"source": "batch"}},
+        {"data": "doc 2", "format": "text"},
+    ]
+)
+print(resp)
+```
+
+Return shape depends on IntegrationBackend; the SDK returns the JSON response.
+
+### `Tex.search(query, ...)`
+
+Fast semantic search.
+
+```python
+resp = tx.search("espresso", top_k=5)
+print(resp)
+```
+
+Optional parameters:
+
+- `min_score`: float
+- `label`: string label filter
+- `metadata_filter`: dict
+
+### `Tex.ask(question, ...)` → `AskResult`
+
+Natural language query execution.
+
+```python
+ans = tx.ask("What did I store recently?")
+print(ans.text)
+```
+
+Return type is `AskResult`:
+
+- `text`: human-readable summary assembled from evidence/bindings/documents
+- `evidence`: list of evidence strings
+- `entities`: list of extracted/bound entity names
+- `documents`: list of document identifiers
+- `raw`: the full JSON response dict
+
+Parameters (passed through to `/nlq/execute`):
+
+- `execute` (default True)
+- `enable_pruning` (default True)
+- `use_local_intelligence` (default True)
+- `intent_match_options` (optional dict)
+- `compact` (default True)
+
+### `Tex.query(query, params=None)`
+
+Execute a DB query via IntegrationBackend.
+
+```python
+resp = tx.query(
+    "MATCH (n) RETURN n LIMIT $limit",
+    params={"limit": 5},
+)
+print(resp)
+```
+
+This calls `POST /helixdb/query` by default (see `TexEndpoints.db_query`).
+
+### `Tex.schema()`
+
+Fetch the database schema.
+
+```python
+schema = tx.schema()
+print(schema)
+```
+
+This calls `GET /helixdb/schema` by default.
+
+### `Tex.whoami()`
+
+Returns the tenant context as seen by IntegrationBackend (great for debugging auth/scope).
+
+```python
+print(tx.whoami())
+```
+
+Internally, it ensures auth, then calls `GET /auth/verify` (unless already cached).
+
+### Memories CRUD
+
+These map to `/memories` endpoints.
+
+#### `Tex.get_memory(memory_id)`
+
+```python
+mem = tx.get_memory("mem_...")
+print(mem)
+```
+
+#### `Tex.list_memories(type=None, limit=50, offset=0)`
+
+```python
+resp = tx.list_memories(limit=20, offset=0)
+print(resp)
+
+docs = tx.list_memories(type="document", limit=20)
+print(docs)
+```
+
+#### `Tex.update_memory(memory_id, content=None, metadata=None, options=None)`
+
+```python
+resp = tx.update_memory(
+    "mem_...",
+    content="updated content",
+    metadata={"tag": "updated"},
+)
+print(resp)
+```
+
+#### `Tex.delete_memory(memory_id)`
+
+```python
+resp = tx.delete_memory("mem_...")
+print(resp)
+```
+
+#### `Tex.delete_memories(user_id=None)`
+
+Bulk delete.
+
+- If `user_id` is omitted, deletes the caller’s memories.
+- If `user_id` is provided and differs from caller, IntegrationBackend may require elevated roles.
+
+```python
+resp = tx.delete_memories()
+print(resp)
+```
+
+### Episodes
+
+#### `Tex.list_episodes(limit=50, offset=0, since=None)`
+
+```python
+resp = tx.list_episodes(limit=10)
+print(resp)
+```
+
+### User profile
+
+#### `Tex.get_profile(format="text")`
+
+Returns a synthesized profile derived from preferences and episodic memories.
+
+```python
+profile = tx.get_profile(format="text")
+print(profile)
+```
+
+## Errors and exception handling
+
+Errors are defined in `tex/errors.py`.
+
+### `TexHTTPError`
+
+Raised for non-auth HTTP failures (status >= 400 excluding 401/403) and network/timeout errors.
+
+Fields:
+
+- `message` (str)
+- `status_code` (optional int)
+- `request_id` (optional str; pulled from `X-Correlation-ID` response header if present)
+- `response_text` (optional str; truncated to 2000 chars)
+- `details` (any; parsed JSON when possible)
+
+### `TexAuthError`
+
+Subclass of `TexHTTPError`, raised for auth issues:
+
+- “No auth configured”
+- token exchange/login failures
+- HTTP 401/403 responses
+
+### Typical pattern
+
+```python
+from tex import Tex, TexAuthError, TexHTTPError
+
+tx = Tex("http://localhost:8000", api_key="sk_live_...")
+
+try:
+    print(tx.whoami())
+except TexAuthError as e:
+    # Wrong key, missing roles, expired/invalid refresh, etc.
+    print("auth failed", str(e), e.status_code)
+except TexHTTPError as e:
+    # Non-auth HTTP errors (422, 500, network issues)
+    print("request failed", str(e), e.status_code)
+```
+
+## Request/response handling details
+
+This mirrors `Tex._request()` and `_post_noauth()`.
+
+- JSON responses are returned as Python dicts.
+- If the response body is valid JSON but not a dict (e.g., a list), the SDK wraps it as `{ "data": <payload> }`.
+- If the response is not JSON, the SDK returns `{ "data": "<text>" }`.
+- For error responses, the SDK tries to extract `detail` or `message` from JSON. Otherwise: “Request failed”.
+
+Special hint for HTTP 422:
+
+- If the error mentions “IntentGraph validation” / “root variable must have a type”, the SDK appends a hint suggesting schema/planner issues.
+
+## Running the smoketest script (repo)
+
+The repo includes a minimal end-to-end tester:
+
+- `tools/tex_sdk_smoketest.py`
+
+It is designed to work:
+
+- When installed from PyPI (`pip install tex-sdk`)
+- When run directly from this repo (it falls back to adding the repo root to `sys.path`)
+
+### Environment variables
+
+- `TEX_BASE_URL` (default: `http://localhost:8000`)
+- `TEX_TIMEOUT_S` (default: `30`)
+
+Auth (set exactly one of the following groups):
+
+1) API key:
+
+- `TEX_API_KEY=sk_live_...`
+
+2) Org+user login:
+
+- `TEX_ORG_ID=...`
+- `TEX_USER_ID=...`
+- `TEX_SESSION_ID=...` (optional)
+
+3) Direct token:
+
+- `TEX_ACCESS_TOKEN=eyJ...`
+
+### Run
+
+```powershell
+$env:TEX_BASE_URL = "http://localhost:8000"
+$env:TEX_API_KEY = "sk_live_..."
+
+python tools/tex_sdk_smoketest.py
+```
+
+The script performs:
+
+- `GET /health` (unauth quick check)
+- `whoami()`
+- `store_memory(type="document")`
+- polls `job(job_id)` (if job_id returned)
+- `search(...)`
+- `ask(...)`
+
+## Migration notes (in-repo users)
+
+Inside this repo, there is also an `sdk/` package that re-exports everything from `tex/` as a compatibility shim.
+
+- New code should import from `tex`.
+- Old code importing `sdk` will continue to work (see `sdk/__init__.py`).
+
+## Troubleshooting
+
+### “Connection refused” / health check fails
+
+- Ensure IntegrationBackend is running (default: `http://localhost:8000/health`).
+- The SDK does not start services; it only calls HTTP endpoints.
+
+### HTTP 401 / 403
+
+- Verify you’re using the correct auth mode.
+- For API key auth: ensure the key is valid and belongs to the tenant you expect.
+- For org+user login: ensure `/auth/login` is enabled for that org/user.
+
+### HTTP 422 (validation errors)
+
+- Usually means your request payload doesn’t match backend expectations.
+- For NLQ/planner-related validation errors, confirm the DB schema is available and the planner can fetch it.
+
+### HTTP/2 import error (`h2`)
+
+If you see an ImportError mentioning `h2`, install:
+
+```bash
+pip install "tex-sdk[http2]"
+```
+
+Or disable HTTP/2:
+
+```python
+from tex import Tex
+
+tx = Tex("http://localhost:8000", api_key="sk_live_...", http2=False)
+```

tex_sdk-0.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+tex/__init__.py,sha256=ZqTfS02rhX7tzl2k6zNb5gZskYdZ-gDMuS6D6KysvtY,415
+tex/client.py,sha256=1kAUK99Qi6zcPklKZIubV8oAhLr4JDvEC7T50SZIyjs,25340
+tex/config.py,sha256=AvPyt_WEfPOZDpSryNsF9GFSN0O2qDFD23j6LBj95dc,1938
+tex/errors.py,sha256=NlE63BYFPnukvrZufmrSU63k9HV61wcL_U0ykRbSHgA,733
+tex/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tex_sdk-0.3.0.dist-info/METADATA,sha256=Y8YROV55tlLA2ErCHVzH1dKsI33FFnIV63PSSs7xVy8,16178
+tex_sdk-0.3.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+tex_sdk-0.3.0.dist-info/top_level.txt,sha256=-u3o-lc05yHetpTLGtM13couqCEEb_mzuJMXYFS5SZs,4
+tex_sdk-0.3.0.dist-info/RECORD,,

tex_sdk-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tex_sdk-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tex