tetrix-sdk 0.1.1__py3-none-any.whl

tetrix_aidb/__init__.py

@@ -0,0 +1,62 @@
+"""TetrixAIDb Python SDK — AI-native database client."""
+
+__version__ = "0.1.1"
+
+from tetrix_aidb.client import TetrixClient, create_client
+from tetrix_aidb.errors import TetrixError
+from tetrix_aidb.types import (
+    Category,
+    ClientConfig,
+    DeleteBatchResponse,
+    Entity,
+    EntityContent,
+    HealthResponse,
+    IndexBatchItem,
+    IndexBatchOptions,
+    IndexBatchResponse,
+    IndexBatchResultItem,
+    ListCategoriesResponse,
+    ListEntityCategoriesResponse,
+    ListOrgsResponse,
+    ListPermissionsResponse,
+    ListTeamMembersResponse,
+    ListTeamsResponse,
+    ListUsersResponse,
+    MetricsResponse,
+    Organization,
+    Permission,
+    RelationRef,
+    Team,
+    TeamMember,
+    User,
+)
+
+__all__ = [
+    "TetrixClient",
+    "create_client",
+    "Category",
+    "ClientConfig",
+    "DeleteBatchResponse",
+    "Entity",
+    "EntityContent",
+    "HealthResponse",
+    "IndexBatchItem",
+    "IndexBatchOptions",
+    "IndexBatchResponse",
+    "IndexBatchResultItem",
+    "ListCategoriesResponse",
+    "ListEntityCategoriesResponse",
+    "ListOrgsResponse",
+    "ListPermissionsResponse",
+    "ListTeamMembersResponse",
+    "ListTeamsResponse",
+    "ListUsersResponse",
+    "MetricsResponse",
+    "Organization",
+    "Permission",
+    "RelationRef",
+    "Team",
+    "TeamMember",
+    "TetrixError",
+    "User",
+]

tetrix_aidb/client.py

@@ -0,0 +1,767 @@
+"""TetrixAIDb async client implementation."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from typing import Any
+from urllib.parse import urlparse
+
+from tetrix_aidb.errors import ConnectionError, TetrixError
+from tetrix_aidb.protocol import encode_frame, read_frame
+from tetrix_aidb.types import (
+    Category,
+    ClientConfig,
+    DeleteBatchResponse,
+    DeleteRequest,
+    DeleteResponse,
+    EmbedBatchRequest,
+    EmbedBatchResponse,
+    EntityContent,
+    GetRequest,
+    GetResponse,
+    HealthResponse,
+    IndexBatchItem,
+    IndexBatchOptions,
+    IndexBatchResponse,
+    IndexBatchResultItem,
+    IndexRequest,
+    IndexResponse,
+    ListCategoriesResponse,
+    ListEntityCategoriesResponse,
+    ListOrgsResponse,
+    ListPermissionsResponse,
+    ListTeamMembersResponse,
+    ListTeamsResponse,
+    ListUsersResponse,
+    MetricsResponse,
+    Organization,
+    Permission,
+    SemanticSearchRequest,
+    SemanticSearchResponse,
+    Team,
+    TeamMember,
+    UpdateRequest,
+    UpdateResponse,
+    User,
+)
+
+PROTOCOL_VERSION = "1.0"
+
+
+class TetrixClient:
+    """Async client for TetrixAIDb."""
+
+    def __init__(self, config: ClientConfig) -> None:
+        self._config = config
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._lock = asyncio.Lock()
+        self._authenticated = False
+
+    async def connect(self) -> None:
+        """Establish connection and perform AUTH handshake."""
+        parsed = urlparse(self._config.endpoint)
+
+        try:
+            if parsed.scheme == "unix":
+                self._reader, self._writer = await asyncio.open_unix_connection(parsed.path)
+            else:
+                host = parsed.hostname or "localhost"
+                port = parsed.port or 7779
+                self._reader, self._writer = await asyncio.open_connection(host, port)
+        except OSError as e:
+            raise ConnectionError(f"failed to connect to {self._config.endpoint}: {e}") from e
+
+        await self._authenticate()
+
+    async def _authenticate(self) -> None:
+        """Send AUTH handshake and validate response."""
+        auth_frame: dict[str, Any] = {
+            "protocolVersion": PROTOCOL_VERSION,
+            "op": "AUTH",
+            "username": self._config.username,
+            "password": self._config.password,
+        }
+
+        assert self._writer is not None
+        assert self._reader is not None
+
+        self._writer.write(encode_frame(auth_frame))
+        await self._writer.drain()
+        resp = await read_frame(self._reader)
+
+        if resp.get("status") != "ok":
+            err = resp.get("error", {})
+            await self.close()
+            raise TetrixError(
+                code=err.get("code", "UNAUTHENTICATED"),
+                message=err.get("message", "authentication failed"),
+                retryable=False,
+            )
+
+        self._authenticated = True
+
+    async def close(self) -> None:
+        """Close the connection."""
+        if self._writer:
+            self._writer.close()
+            await self._writer.wait_closed()
+            self._writer = None
+            self._reader = None
+        self._authenticated = False
+
+    async def _request(self, op: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """Send a request and return the response payload."""
+        if not self._writer or not self._reader:
+            await self.connect()
+
+        envelope = {
+            "protocolVersion": PROTOCOL_VERSION,
+            "requestId": str(uuid.uuid4()),
+            "op": op,
+            "payload": payload,
+        }
+
+        async with self._lock:
+            self._writer.write(encode_frame(envelope))
+            await self._writer.drain()
+            resp = await read_frame(self._reader)
+
+        if resp.get("status") == "error":
+            err = resp.get("error", {})
+            raise TetrixError(
+                code=err.get("code", "UNKNOWN"),
+                message=err.get("message", "unknown error"),
+                retryable=err.get("retryable", False),
+                details=err.get("details"),
+            )
+
+        return resp.get("payload", {})
+
+    # =================================================================
+    # Data Operations
+    # =================================================================
+
+    async def index(self, request: IndexRequest) -> IndexResponse:
+        """Create or index an entity."""
+        payload = _index_request_to_dict(request)
+        resp = await self._request("INDEX", payload)
+        return IndexResponse(
+            id=resp["id"],
+            version=resp["version"],
+            created_at=resp["createdAt"],
+            write_consistency=resp.get("writeConsistency", "strong"),
+        )
+
+    async def get(self, request: GetRequest) -> GetResponse:
+        """Retrieve an entity by ID."""
+        payload = {
+            "id": request.id,
+            "includeContent": request.include_content,
+            "includeRelations": request.include_relations,
+        }
+        resp = await self._request("GET", payload)
+        content = None
+        if resp.get("content"):
+            c = resp["content"]
+            content = EntityContent(
+                text=c.get("text", ""),
+                raw=c.get("raw"),
+                encoding=c.get("encoding"),
+            )
+        return GetResponse(entity=_dict_to_entity(resp.get("entity", {})), content=content)
+
+    async def update(self, request: UpdateRequest) -> UpdateResponse:
+        """Update an entity."""
+        payload: dict[str, Any] = {"id": request.id}
+        if request.expected_version:
+            payload["expectedVersion"] = request.expected_version
+        if request.patch:
+            patch: dict[str, Any] = {}
+            if request.patch.name:
+                patch["name"] = request.patch.name
+            if request.patch.metadata is not None:
+                patch["metadata"] = request.patch.metadata
+            if request.patch.relations is not None:
+                patch["relations"] = [
+                    {"type": r.type, "targetId": r.target_id}
+                    for r in request.patch.relations
+                ]
+            payload["patch"] = patch
+        if request.content_patch:
+            cp: dict[str, Any] = {}
+            if request.content_patch.text is not None:
+                cp["text"] = request.content_patch.text
+            if request.content_patch.raw is not None:
+                cp["raw"] = request.content_patch.raw
+            if request.content_patch.encoding is not None:
+                cp["encoding"] = request.content_patch.encoding
+            payload["contentPatch"] = cp
+        resp = await self._request("UPDATE", payload)
+        return UpdateResponse(
+            id=resp["id"],
+            version=resp["version"],
+            updated_at=resp["updatedAt"],
+        )
+
+    async def delete(self, request: DeleteRequest) -> DeleteResponse:
+        """Delete an entity."""
+        payload: dict[str, Any] = {"id": request.id, "deleteMode": request.delete_mode}
+        if request.expected_version:
+            payload["expectedVersion"] = request.expected_version
+        resp = await self._request("DELETE", payload)
+        return DeleteResponse(
+            id=resp["id"],
+            status=resp["status"],
+            deleted_at=resp["deletedAt"],
+        )
+
+    async def semantic_search(self, request: SemanticSearchRequest) -> SemanticSearchResponse:
+        """Search for entities by meaning."""
+        payload: dict[str, Any] = {"text": request.text}
+        if request.filters:
+            filters: dict[str, Any] = {}
+            if request.filters.type:
+                filters["type"] = request.filters.type
+            if request.filters.category:
+                filters["category"] = request.filters.category
+            if request.filters.owner:
+                filters["owner"] = request.filters.owner
+            if request.filters.metadata:
+                filters["metadata"] = request.filters.metadata
+            payload["filters"] = filters
+        if request.options:
+            payload["options"] = {
+                "topK": request.options.top_k,
+                "offset": request.options.offset,
+                "expandGraph": request.options.expand_graph,
+                "graphHops": request.options.graph_hops,
+                "includeContentPreview": request.options.include_content_preview,
+                "includeRelations": request.options.include_relations,
+                "useKeyword": request.options.use_keyword,
+            }
+        resp = await self._request("SEMANTIC_SEARCH", payload)
+        items = [_dict_to_search_result(item) for item in resp.get("items", [])]
+        return SemanticSearchResponse(
+            items=items,
+            total=resp.get("total", 0),
+            next_offset=resp.get("nextOffset"),
+        )
+
+    async def index_batch(
+        self,
+        items: list[IndexBatchItem],
+        options: IndexBatchOptions | None = None,
+    ) -> IndexBatchResponse:
+        """Index multiple entities in a single batch."""
+        batch_items = []
+        for item in items:
+            entry: dict[str, Any] = {
+                "entity": {
+                    "type": item.entity.type,
+                    "owner": item.entity.owner,
+                    "name": item.entity.name,
+                },
+                "content": {"text": item.content.text},
+            }
+            if item.entity.id:
+                entry["entity"]["id"] = item.entity.id
+            if item.entity.metadata:
+                entry["entity"]["metadata"] = item.entity.metadata
+            if item.entity.relations:
+                entry["entity"]["relations"] = [
+                    {"type": r.type, "targetId": r.target_id}
+                    for r in item.entity.relations
+                ]
+            if item.content.raw:
+                entry["content"]["raw"] = item.content.raw
+            if item.content.encoding:
+                entry["content"]["encoding"] = item.content.encoding
+            if item.category_ids:
+                entry["categoryIds"] = item.category_ids
+            batch_items.append(entry)
+
+        payload: dict[str, Any] = {"items": batch_items}
+        if options:
+            payload["options"] = {"writeConsistency": options.write_consistency}
+
+        resp = await self._request("INDEX_BATCH", payload)
+        results = [
+            IndexBatchResultItem(
+                id=r.get("id", ""),
+                version=r.get("version", ""),
+                error=r.get("error"),
+            )
+            for r in resp.get("results", [])
+        ]
+        return IndexBatchResponse(
+            total_count=resp.get("totalCount", 0),
+            failed_count=resp.get("failedCount", 0),
+            results=results,
+        )
+
+    async def delete_batch(self, ids: list[str], delete_mode: str = "soft") -> DeleteBatchResponse:
+        """Delete multiple entities in a single batch."""
+        payload: dict[str, Any] = {"ids": ids, "deleteMode": delete_mode}
+        resp = await self._request("DELETE_BATCH", payload)
+        return DeleteBatchResponse(
+            total_count=resp.get("totalCount", 0),
+            failed_count=resp.get("failedCount", 0),
+        )
+
+    async def list_entity_events(
+        self,
+        entity_id: str,
+        event_types: list[str] | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> dict:
+        """List events for an entity. Returns {events: [...], total: int}."""
+        payload: dict[str, Any] = {"entityId": entity_id, "limit": limit, "offset": offset}
+        if event_types:
+            payload["eventTypes"] = event_types
+        return await self._request("LIST_ENTITY_EVENTS", payload)
+
+    async def embed_batch(self, request: EmbedBatchRequest) -> EmbedBatchResponse:
+        """Generate embedding vectors for multiple texts via the daemon's embedding provider."""
+        payload: dict[str, Any] = {"texts": request.texts}
+        resp = await self._request("EMBED_BATCH", payload)
+        return EmbedBatchResponse(
+            embeddings=resp.get("embeddings", []),
+            dimensions=resp.get("dimensions", 0),
+            model=resp.get("model", ""),
+            cached=resp.get("cached", 0),
+        )
+
+    async def health(self) -> HealthResponse:
+        """Check daemon health."""
+        resp = await self._request("HEALTH", {})
+        return HealthResponse(
+            status=resp.get("status", "unknown"),
+            uptime_seconds=resp.get("uptimeSeconds", 0),
+            backends=resp.get("backends", {}),
+        )
+
+    async def metrics(self) -> MetricsResponse:
+        """Get daemon metrics."""
+        resp = await self._request("METRICS", {})
+        return MetricsResponse(data=resp)
+
+    # =================================================================
+    # IAM – Organizations
+    # =================================================================
+
+    async def create_org(self, name: str) -> Organization:
+        """Create a new organization. Requires superadmin or platform_admin."""
+        resp = await self._request("CREATE_ORG", {"name": name})
+        return Organization(id=resp["id"], name=resp["name"])
+
+    async def get_org(self, org_id: str = "") -> Organization:
+        """Get organization details. Defaults to caller's org."""
+        resp = await self._request("GET_ORG", {"orgId": org_id})
+        return Organization(
+            id=resp["id"], name=resp["name"], created_at=resp.get("createdAt", ""),
+        )
+
+    async def update_org(self, org_id: str, name: str) -> Organization:
+        """Rename an organization. Requires superadmin or platform_admin."""
+        resp = await self._request("UPDATE_ORG", {"orgId": org_id, "name": name})
+        return Organization(id=resp["id"], name=resp["name"])
+
+    async def delete_org(self, org_id: str) -> None:
+        """Delete an organization. Requires superadmin or platform_admin."""
+        await self._request("DELETE_ORG", {"orgId": org_id})
+
+    async def list_orgs(self) -> ListOrgsResponse:
+        """List all organizations. Requires superadmin or platform_admin."""
+        resp = await self._request("LIST_ORGS", {})
+        orgs = [
+            Organization(id=o["id"], name=o["name"], created_at=o.get("createdAt", ""))
+            for o in resp.get("orgs", [])
+        ]
+        return ListOrgsResponse(orgs=orgs, total=resp.get("total", 0))
+
+    # =================================================================
+    # IAM – Users
+    # =================================================================
+
+    async def create_user(
+        self,
+        username: str,
+        password: str,
+        org_id: str = "",
+        role: str = "member",
+    ) -> User:
+        """Create a user. Requires org admin."""
+        payload: dict[str, Any] = {
+            "username": username,
+            "password": password,
+            "role": role,
+        }
+        if org_id:
+            payload["orgId"] = org_id
+        resp = await self._request("CREATE_USER", payload)
+        return User(
+            id=resp["id"],
+            username=resp["username"],
+            org_id=resp["orgId"],
+            role=resp["role"],
+        )
+
+    async def get_user(self, user_id: str) -> User:
+        """Get user details. Users can always view themselves."""
+        resp = await self._request("GET_USER", {"userId": user_id})
+        return User(
+            id=resp["id"],
+            username=resp["username"],
+            org_id=resp["orgId"],
+            role=resp["role"],
+            platform_role=resp.get("platformRole", ""),
+            created_at=resp.get("createdAt", ""),
+        )
+
+    async def update_user(
+        self,
+        user_id: str,
+        role: str = "",
+        platform_role: str = "",
+    ) -> User:
+        """Update a user's role or platform role."""
+        payload: dict[str, Any] = {"userId": user_id}
+        if role:
+            payload["role"] = role
+        if platform_role:
+            payload["platformRole"] = platform_role
+        resp = await self._request("UPDATE_USER", payload)
+        return User(
+            id=resp["id"],
+            username="",
+            org_id="",
+            role=resp["role"],
+            platform_role=resp.get("platformRole", ""),
+        )
+
+    async def delete_user(self, user_id: str) -> None:
+        """Delete a user. Requires org admin."""
+        await self._request("DELETE_USER", {"userId": user_id})
+
+    async def list_users(self, org_id: str = "") -> ListUsersResponse:
+        """List users in an organization. Requires org admin."""
+        payload: dict[str, Any] = {}
+        if org_id:
+            payload["orgId"] = org_id
+        resp = await self._request("LIST_USERS", payload)
+        users = [
+            User(
+                id=u["id"],
+                username=u["username"],
+                org_id=u["orgId"],
+                role=u["role"],
+                platform_role=u.get("platformRole", ""),
+            )
+            for u in resp.get("users", [])
+        ]
+        return ListUsersResponse(users=users, total=resp.get("total", 0))
+
+    # =================================================================
+    # IAM – Teams
+    # =================================================================
+
+    async def create_team(self, name: str, org_id: str = "") -> Team:
+        """Create a team. Requires org admin."""
+        payload: dict[str, Any] = {"name": name}
+        if org_id:
+            payload["orgId"] = org_id
+        resp = await self._request("CREATE_TEAM", payload)
+        return Team(id=resp["id"], name=resp["name"], org_id=resp["orgId"])
+
+    async def get_team(self, team_id: str) -> Team:
+        """Get team details. Requires org admin."""
+        resp = await self._request("GET_TEAM", {"teamId": team_id})
+        return Team(
+            id=resp["id"],
+            name=resp["name"],
+            org_id=resp["orgId"],
+            created_at=resp.get("createdAt", ""),
+        )
+
+    async def update_team(self, team_id: str, name: str) -> Team:
+        """Rename a team. Requires org admin."""
+        resp = await self._request("UPDATE_TEAM", {"teamId": team_id, "name": name})
+        return Team(id=resp["id"], name=resp["name"], org_id="")
+
+    async def delete_team(self, team_id: str) -> None:
+        """Delete a team. Requires org admin."""
+        await self._request("DELETE_TEAM", {"teamId": team_id})
+
+    async def list_teams(self, org_id: str = "") -> ListTeamsResponse:
+        """List teams in an organization. Requires org admin."""
+        payload: dict[str, Any] = {}
+        if org_id:
+            payload["orgId"] = org_id
+        resp = await self._request("LIST_TEAMS", payload)
+        teams = [
+            Team(id=t["id"], name=t["name"], org_id=t["orgId"])
+            for t in resp.get("teams", [])
+        ]
+        return ListTeamsResponse(teams=teams, total=resp.get("total", 0))
+
+    # =================================================================
+    # IAM – Team Members
+    # =================================================================
+
+    async def add_team_member(
+        self, team_id: str, user_id: str, role: str = "member",
+    ) -> None:
+        """Add a user to a team. Requires org admin or team admin."""
+        await self._request("ADD_TEAM_MEMBER", {
+            "teamId": team_id, "userId": user_id, "role": role,
+        })
+
+    async def remove_team_member(self, team_id: str, user_id: str) -> None:
+        """Remove a user from a team. Requires org admin or team admin."""
+        await self._request("REMOVE_TEAM_MEMBER", {
+            "teamId": team_id, "userId": user_id,
+        })
+
+    async def list_team_members(self, team_id: str) -> ListTeamMembersResponse:
+        """List members of a team. Requires org admin or team admin."""
+        resp = await self._request("LIST_TEAM_MEMBERS", {"teamId": team_id})
+        members = [
+            TeamMember(
+                user_id=m["userId"], username=m["username"], role=m["role"],
+            )
+            for m in resp.get("members", [])
+        ]
+        return ListTeamMembersResponse(
+            team_id=resp.get("teamId", team_id),
+            members=members,
+            total=resp.get("total", 0),
+        )
+
+    # =================================================================
+    # IAM – Entity Permissions
+    # =================================================================
+
+    async def grant_permission(
+        self,
+        entity_id: str,
+        grantee_type: str,
+        grantee_id: str,
+        permission: str = "read",
+    ) -> None:
+        """Grant access to an entity. Any authenticated user can share."""
+        await self._request("GRANT_PERMISSION", {
+            "entityId": entity_id,
+            "granteeType": grantee_type,
+            "granteeId": grantee_id,
+            "permission": permission,
+        })
+
+    async def revoke_permission(
+        self, entity_id: str, grantee_type: str, grantee_id: str,
+    ) -> None:
+        """Revoke access to an entity."""
+        await self._request("REVOKE_PERMISSION", {
+            "entityId": entity_id,
+            "granteeType": grantee_type,
+            "granteeId": grantee_id,
+        })
+
+    async def list_permissions(self, entity_id: str) -> ListPermissionsResponse:
+        """List all permission grants on an entity."""
+        resp = await self._request("LIST_PERMISSIONS", {"entityId": entity_id})
+        perms = [
+            Permission(
+                grantee_type=p["granteeType"],
+                grantee_id=p["granteeId"],
+                permission=p["permission"],
+                granted_by=p.get("grantedBy", ""),
+            )
+            for p in resp.get("permissions", [])
+        ]
+        return ListPermissionsResponse(
+            entity_id=resp.get("entityId", entity_id),
+            permissions=perms,
+            total=resp.get("total", 0),
+        )
+
+    # =================================================================
+    # Categories
+    # =================================================================
+
+    async def create_category(
+        self, name: str, description: str = "", parent_id: str = "",
+    ) -> Category:
+        payload: dict[str, Any] = {"name": name}
+        if description:
+            payload["description"] = description
+        if parent_id:
+            payload["parentId"] = parent_id
+        resp = await self._request("CREATE_CATEGORY", payload)
+        return Category(
+            id=resp.get("id", ""),
+            name=resp.get("name", ""),
+            org_id=resp.get("orgId", ""),
+        )
+
+    async def get_category(self, category_id: str) -> Category:
+        resp = await self._request("GET_CATEGORY", {"categoryId": category_id})
+        cat = resp.get("category", {})
+        return _dict_to_category(cat)
+
+    async def update_category(
+        self,
+        category_id: str,
+        *,
+        name: str = "",
+        description: str = "",
+        parent_id: str = "",
+        clear_parent: bool = False,
+    ) -> Category:
+        payload: dict[str, Any] = {"categoryId": category_id}
+        if name:
+            payload["name"] = name
+        if description:
+            payload["description"] = description
+        if parent_id:
+            payload["parentId"] = parent_id
+        if clear_parent:
+            payload["clearParent"] = True
+        resp = await self._request("UPDATE_CATEGORY", payload)
+        return Category(
+            id=resp.get("id", ""),
+            name=resp.get("name", ""),
+            org_id="",
+        )
+
+    async def delete_category(self, category_id: str) -> None:
+        await self._request("DELETE_CATEGORY", {"categoryId": category_id})
+
+    async def list_categories(
+        self, parent_id: str = "", tree: bool = False,
+    ) -> ListCategoriesResponse:
+        payload: dict[str, Any] = {}
+        if parent_id:
+            payload["parentId"] = parent_id
+        if tree:
+            payload["tree"] = True
+        resp = await self._request("LIST_CATEGORIES", payload)
+        cats = [_dict_to_category(c) for c in resp.get("categories", [])]
+        return ListCategoriesResponse(categories=cats, total=resp.get("total", 0))
+
+    async def assign_entity_category(self, entity_id: str, category_id: str) -> None:
+        await self._request("ASSIGN_ENTITY_CATEGORY", {
+            "entityId": entity_id,
+            "categoryId": category_id,
+        })
+
+    async def unassign_entity_category(self, entity_id: str, category_id: str) -> None:
+        await self._request("UNASSIGN_ENTITY_CATEGORY", {
+            "entityId": entity_id,
+            "categoryId": category_id,
+        })
+
+    async def list_entity_categories(self, entity_id: str) -> ListEntityCategoriesResponse:
+        resp = await self._request("LIST_ENTITY_CATEGORIES", {"entityId": entity_id})
+        cats = [_dict_to_category(c) for c in resp.get("categories", [])]
+        return ListEntityCategoriesResponse(
+            entity_id=resp.get("entityId", entity_id),
+            categories=cats,
+            total=resp.get("total", 0),
+        )
+
+
+def create_client(config: ClientConfig) -> TetrixClient:
+    """Create a new TetrixAIDb client."""
+    return TetrixClient(config)
+
+
+# --- Internal helpers ---
+
+
+def _index_request_to_dict(req: IndexRequest) -> dict[str, Any]:
+    entity: dict[str, Any] = {
+        "type": req.entity.type,
+        "owner": req.entity.owner,
+        "name": req.entity.name,
+    }
+    if req.entity.id:
+        entity["id"] = req.entity.id
+    if req.entity.metadata:
+        entity["metadata"] = req.entity.metadata
+    if req.entity.relations:
+        entity["relations"] = [
+            {"type": r.type, "targetId": r.target_id} for r in req.entity.relations
+        ]
+
+    content: dict[str, Any] = {"text": req.content.text}
+    if req.content.raw:
+        content["raw"] = req.content.raw
+    if req.content.encoding:
+        content["encoding"] = req.content.encoding
+
+    result: dict[str, Any] = {
+        "entity": entity,
+        "content": content,
+        "writeConsistency": req.write_consistency,
+    }
+    if req.category_ids:
+        result["categoryIds"] = req.category_ids
+    return result
+
+
+def _dict_to_entity(d: dict[str, Any]) -> Any:
+    from tetrix_aidb.types import Entity, RelationRef
+
+    relations = [
+        RelationRef(type=r.get("type", ""), target_id=r.get("targetId", ""))
+        for r in d.get("relations", [])
+    ]
+    return Entity(
+        id=d.get("id", ""),
+        type=d.get("type", ""),
+        owner=d.get("owner", ""),
+        name=d.get("name", ""),
+        metadata=d.get("metadata", {}),
+        relations=relations,
+        version=d.get("version", ""),
+    )
+
+
+def _dict_to_search_result(d: dict[str, Any]) -> Any:
+    from tetrix_aidb.types import RelatedEntity, SearchResultItem
+
+    entity = _dict_to_entity(d.get("entity", {}))
+    related = [
+        RelatedEntity(
+            id=r.get("id", ""),
+            type=r.get("type", ""),
+            name=r.get("name", ""),
+            relation_type=r.get("relationType", ""),
+            distance=r.get("distance", 0),
+        )
+        for r in d.get("relatedEntities", [])
+    ]
+    return SearchResultItem(
+        entity=entity,
+        score=d.get("score", 0.0),
+        source=d.get("source", ""),
+        content_preview=d.get("contentPreview"),
+        related_entities=related,
+    )
+
+
+def _dict_to_category(d: dict[str, Any]) -> Category:
+    children = [_dict_to_category(c) for c in d.get("children", [])]
+    return Category(
+        id=d.get("id", ""),
+        name=d.get("name", ""),
+        description=d.get("description", ""),
+        org_id=d.get("orgId", ""),
+        parent_id=d.get("parentId", ""),
+        children=children,
+        created_at=d.get("createdAt", ""),
+        updated_at=d.get("updatedAt", ""),
+    )

tetrix_aidb/errors.py

@@ -0,0 +1,38 @@
+"""Error types for the TetrixAIDb SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class TetrixError(Exception):
+    """Base error raised by TetrixAIDb SDK operations."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        retryable: bool = False,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.retryable = retryable
+        self.details = details or {}
+
+    def __repr__(self) -> str:
+        return f"TetrixError(code={self.code!r}, message={self.args[0]!r}, retryable={self.retryable})"
+
+
+class ConnectionError(TetrixError):
+    """Raised when the SDK cannot connect to the daemon."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(code="CONNECTION_ERROR", message=message, retryable=True)
+
+
+class TimeoutError(TetrixError):
+    """Raised when an operation exceeds the configured timeout."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(code="TIMEOUT", message=message, retryable=True)

tetrix_aidb/protocol.py

@@ -0,0 +1,29 @@
+"""Wire protocol framing: 4-byte big-endian length prefix + JSON payload."""
+
+from __future__ import annotations
+
+import json
+import struct
+from typing import Any
+
+HEADER_FORMAT = "!I"  # big-endian uint32
+HEADER_SIZE = struct.calcsize(HEADER_FORMAT)
+
+
+def encode_frame(payload: dict[str, Any]) -> bytes:
+    """Encode a payload dict into a length-prefixed JSON frame."""
+    body = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+    header = struct.pack(HEADER_FORMAT, len(body))
+    return header + body
+
+
+async def read_frame(reader: Any, max_size: int = 16 << 20) -> dict[str, Any]:
+    """Read a single length-prefixed frame from an asyncio StreamReader."""
+    header = await reader.readexactly(HEADER_SIZE)
+    (length,) = struct.unpack(HEADER_FORMAT, header)
+
+    if length > max_size:
+        raise ValueError(f"frame size {length} exceeds max {max_size}")
+
+    body = await reader.readexactly(length)
+    return json.loads(body)

tetrix_aidb/types.py

@@ -0,0 +1,354 @@
+"""Core types matching the TetrixAIDb protocol specification."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ClientConfig:
+    endpoint: str
+    username: str
+    password: str
+    timeout_ms: int = 5000
+    max_connections: int = 256
+
+
+@dataclass
+class RelationRef:
+    type: str
+    target_id: str
+
+
+@dataclass
+class Entity:
+    id: str = ""
+    type: str = ""
+    owner: str = ""
+    name: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+    relations: list[RelationRef] = field(default_factory=list)
+    version: str = ""
+
+
+@dataclass
+class EntityContent:
+    text: str = ""
+    raw: str | None = None
+    encoding: str | None = None
+
+
+@dataclass
+class IndexRequest:
+    entity: Entity
+    content: EntityContent
+    idempotency_key: str | None = None
+    category_ids: list[str] | None = None
+    write_consistency: str = "strong"
+
+
+@dataclass
+class IndexResponse:
+    id: str
+    version: str
+    created_at: str
+    write_consistency: str
+
+
+@dataclass
+class GetRequest:
+    id: str
+    include_content: bool = True
+    include_relations: bool = True
+
+
+@dataclass
+class GetResponse:
+    entity: Entity
+    content: EntityContent | None = None
+
+
+@dataclass
+class UpdatePatch:
+    name: str | None = None
+    metadata: dict[str, Any] | None = None
+    relations: list[RelationRef] | None = None
+
+
+@dataclass
+class ContentPatch:
+    text: str | None = None
+    raw: str | None = None
+    encoding: str | None = None
+
+
+@dataclass
+class UpdateRequest:
+    id: str
+    expected_version: str | None = None
+    patch: UpdatePatch | None = None
+    content_patch: ContentPatch | None = None
+    write_consistency: str = "strong"
+
+
+@dataclass
+class UpdateResponse:
+    id: str
+    version: str
+    updated_at: str
+
+
+@dataclass
+class DeleteRequest:
+    id: str
+    expected_version: str | None = None
+    delete_mode: str = "soft"
+
+
+@dataclass
+class DeleteResponse:
+    id: str
+    status: str
+    deleted_at: str
+
+
+@dataclass
+class IndexBatchItem:
+    entity: Entity
+    content: EntityContent
+    idempotency_key: str | None = None
+    category_ids: list[str] | None = None
+
+
+@dataclass
+class IndexBatchOptions:
+    write_consistency: str = "strong"
+
+
+@dataclass
+class IndexBatchResultItem:
+    id: str
+    version: str
+    error: str | None = None
+
+
+@dataclass
+class IndexBatchResponse:
+    total_count: int
+    failed_count: int
+    results: list[IndexBatchResultItem]
+
+
+@dataclass
+class DeleteBatchResponse:
+    total_count: int
+    failed_count: int
+
+
+@dataclass
+class HealthResponse:
+    status: str
+    uptime_seconds: int
+    backends: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class MetricsResponse:
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SearchOptions:
+    top_k: int = 20
+    offset: int = 0
+    expand_graph: bool = False
+    graph_hops: int = 1
+    include_content_preview: bool = True
+    include_relations: bool = False
+    use_keyword: bool = True
+
+
+@dataclass
+class SearchFilters:
+    type: list[str] | None = None
+    category: list[str] | None = None
+    owner: list[str] | None = None
+    metadata: dict[str, Any] | None = None
+
+
+@dataclass
+class SemanticSearchRequest:
+    text: str
+    filters: SearchFilters | None = None
+    options: SearchOptions | None = None
+
+
+@dataclass
+class RelatedEntity:
+    id: str
+    type: str
+    name: str
+    relation_type: str
+    distance: int
+
+
+@dataclass
+class SearchResultItem:
+    entity: Entity
+    score: float
+    source: str  # "vector" | "keyword" | "hybrid"
+    content_preview: str | None = None
+    related_entities: list[RelatedEntity] = field(default_factory=list)
+
+
+@dataclass
+class SemanticSearchResponse:
+    items: list[SearchResultItem]
+    total: int
+    next_offset: int | None = None
+
+
+# =====================================================================
+# IAM – Organizations
+# =====================================================================
+
+
+@dataclass
+class Organization:
+    id: str
+    name: str
+    created_at: str = ""
+
+
+@dataclass
+class ListOrgsResponse:
+    orgs: list[Organization]
+    total: int
+
+
+# =====================================================================
+# IAM – Users
+# =====================================================================
+
+
+@dataclass
+class User:
+    id: str
+    username: str
+    org_id: str
+    role: str
+    platform_role: str = ""
+    created_at: str = ""
+
+
+@dataclass
+class ListUsersResponse:
+    users: list[User]
+    total: int
+
+
+# =====================================================================
+# IAM – Teams
+# =====================================================================
+
+
+@dataclass
+class Team:
+    id: str
+    name: str
+    org_id: str
+    created_at: str = ""
+
+
+@dataclass
+class ListTeamsResponse:
+    teams: list[Team]
+    total: int
+
+
+# =====================================================================
+# IAM – Team Members
+# =====================================================================
+
+
+@dataclass
+class TeamMember:
+    user_id: str
+    username: str
+    role: str
+
+
+@dataclass
+class ListTeamMembersResponse:
+    team_id: str
+    members: list[TeamMember]
+    total: int
+
+
+# =====================================================================
+# IAM – Entity Permissions
+# =====================================================================
+
+
+@dataclass
+class Permission:
+    grantee_type: str  # "user" | "team"
+    grantee_id: str
+    permission: str  # "read" | "write"
+    granted_by: str = ""
+
+
+@dataclass
+class ListPermissionsResponse:
+    entity_id: str
+    permissions: list[Permission]
+    total: int
+
+
+# =====================================================================
+# EMBED_BATCH
+# =====================================================================
+
+
+@dataclass
+class EmbedBatchRequest:
+    texts: list[str]
+
+
+@dataclass
+class EmbedBatchResponse:
+    embeddings: list[list[float]]
+    dimensions: int
+    model: str = ""
+    cached: int = 0
+
+
+# =====================================================================
+# Categories
+# =====================================================================
+
+
+@dataclass
+class Category:
+    id: str
+    name: str
+    org_id: str
+    description: str = ""
+    parent_id: str = ""
+    children: list["Category"] = field(default_factory=list)
+    created_at: str = ""
+    updated_at: str = ""
+
+
+@dataclass
+class ListCategoriesResponse:
+    categories: list[Category]
+    total: int
+
+
+@dataclass
+class ListEntityCategoriesResponse:
+    entity_id: str
+    categories: list[Category]
+    total: int

tetrix_sdk-0.1.1.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: tetrix-sdk
+Version: 0.1.1
+Summary: TetrixAIDb Python SDK — AI-native database client
+Project-URL: Repository, https://github.com/deskree-inc/tetrix-ee
+License-Expression: MIT
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TetrixAIDb Python SDK
+
+Async Python client for [TetrixAIDb](https://github.com/deskree-inc/tetrix-ee), the AI-native database daemon that unifies vector, keyword, graph, and object storage behind a single binary protocol.
+
+## Installation
+
+```bash
+pip install tetrix-aidb
+```
+
+Requires Python 3.11+.
+
+## Quick Start
+
+```python
+import asyncio
+from tetrix_aidb import ClientConfig, TetrixClient
+
+async def main():
+    client = TetrixClient(ClientConfig(
+        endpoint="tcp://localhost:7779",
+        username="admin",
+        password="secret",
+    ))
+    await client.connect()
+
+    health = await client.health()
+    print(f"Status: {health.status}")
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+## Features
+
+- Async-first API built on `asyncio`
+- TCP, TLS, and Unix socket transports
+- Auth-on-connect with automatic session handling
+- Entity indexing, semantic search, and batch operations
+- IAM operations: organizations, users, teams, permissions
+- Category management
+- Typed request/response models
+
+## License
+
+MIT

tetrix_sdk-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+tetrix_aidb/__init__.py,sha256=JagoVNgSnYp-bNaa8gr9d3uL0_A-5lyKkHfV4IWn_F8,1336
+tetrix_aidb/client.py,sha256=FYHRvlr3TQmu-BCBoq1s4xQD3g3wCOMNcz8XJVtUSCw,27839
+tetrix_aidb/errors.py,sha256=ZXqaw_4w8rMQd2sRSuxTCRWuQxZzK_aRcYCSGNnHwtU,1079
+tetrix_aidb/protocol.py,sha256=GPRYGoHpCAYeyYZc1hS98o7qYOTGBww7Z1uNNWnDc04,951
+tetrix_aidb/types.py,sha256=RN2DSwYGKg_sC3vSWJsY1H_fjrDfHQFUW3e6M9AfdqU,6590
+tetrix_sdk-0.1.1.dist-info/METADATA,sha256=KlzCn7Wanwn2ZR-sE244DqdM917OiguCmo-1bk-2WoA,1460
+tetrix_sdk-0.1.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tetrix_sdk-0.1.1.dist-info/RECORD,,

tetrix_sdk-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any