gurucloud-kb 0.1.0__py3-none-any.whl

gurucloud_kb/__init__.py

@@ -0,0 +1,90 @@
+"""GuruCloud Knowledge Bank SDK.
+
+Example::
+
+    from gurucloud_kb import GuruCloudClient
+
+    client = GuruCloudClient(api_key="kb_abc123...")
+
+    # List all KBs
+    kbs = client.list_kbs()
+
+    # Work with a specific KB
+    kb = client.get_kb("my-kb-uuid")
+    results = kb.search("how does auth work?")
+
+    # Get MCP server definition for agent injection
+    mcp_def = kb.get_mcp_server_definition()
+"""
+
+from gurucloud_kb.async_client import AsyncGuruCloudClient
+from gurucloud_kb.async_kb import AsyncKnowledgeBank
+from gurucloud_kb.client import GuruCloudClient
+from gurucloud_kb.errors import (
+    APIError,
+    AuthenticationError,
+    ConnectionError,
+    GuruCloudError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+)
+from gurucloud_kb.kb import KnowledgeBank
+from gurucloud_kb.types import (
+    APIKeyInfo,
+    BatchIngestResult,
+    CategoryConfig,
+    DeduplicationEvent,
+    DeduplicationEventList,
+    DeduplicationEventSummary,
+    DimensionConfig,
+    DimensionQuery,
+    DimensionSchema,
+    EntryEventLog,
+    EntryEventLogList,
+    EntryInput,
+    EntryResult,
+    KBInfo,
+    MCPServerDefinition,
+    SchemaWarning,
+    SearchRequest,
+    SearchResult,
+)
+
+__all__ = [
+    # Sync client
+    "GuruCloudClient",
+    "KnowledgeBank",
+    # Async client
+    "AsyncGuruCloudClient",
+    "AsyncKnowledgeBank",
+    # Errors
+    "GuruCloudError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "RateLimitError",
+    "ConnectionError",
+    # Types
+    "KBInfo",
+    "DimensionConfig",
+    "CategoryConfig",
+    "DimensionSchema",
+    "SchemaWarning",
+    "EntryInput",
+    "EntryResult",
+    "DimensionQuery",
+    "SearchRequest",
+    "SearchResult",
+    "MCPServerDefinition",
+    "APIKeyInfo",
+    "BatchIngestResult",
+    "DeduplicationEvent",
+    "DeduplicationEventSummary",
+    "DeduplicationEventList",
+    "EntryEventLog",
+    "EntryEventLogList",
+]
+
+__version__ = "0.1.0"

gurucloud_kb/_async_http.py

@@ -0,0 +1,112 @@
+"""Async HTTP transport for the GuruCloud KB SDK.
+
+Wraps httpx.AsyncClient to provide:
+- Automatic Bearer token injection
+- Response envelope unwrapping  (``{"data": ...}``)
+- Typed error raising
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from gurucloud_kb.errors import (
+    APIError,
+    AuthenticationError,
+    ConnectionError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+)
+
+_DEFAULT_TIMEOUT = 30.0
+
+
+class AsyncHTTPClient:
+    """Async wrapper around httpx for the KB API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            base_url=f"{self._base_url}/api/v1/kb",
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    # ── public verbs ────────────────────────────────────────────
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        return await self._request("GET", path, params=params)
+
+    async def post(self, path: str, json: Any = None) -> Any:
+        return await self._request("POST", path, json=json)
+
+    async def put(self, path: str, json: Any = None) -> Any:
+        return await self._request("PUT", path, json=json)
+
+    async def patch(self, path: str, json: Any = None) -> Any:
+        return await self._request("PATCH", path, json=json)
+
+    async def delete(self, path: str) -> Any:
+        return await self._request("DELETE", path)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    # ── internals ───────────────────────────────────────────────
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+    ) -> Any:
+        try:
+            resp = await self._client.request(method, path, params=params, json=json)
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"Cannot reach {self._base_url}: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise ConnectionError(f"Request timed out: {exc}") from exc
+
+        if resp.status_code >= 400:
+            self._raise_for_status(resp)
+
+        # The API wraps successful responses in {"data": ...}
+        body = resp.json()
+        if isinstance(body, dict) and "data" in body:
+            return body["data"]
+        return body
+
+    @staticmethod
+    def _raise_for_status(resp: httpx.Response) -> None:
+        """Map HTTP error responses to typed SDK exceptions."""
+        try:
+            body = resp.json()
+        except Exception:
+            raise APIError(resp.status_code, "unknown", resp.text)
+
+        error = body.get("error", {})
+        code = error.get("code", "unknown") if isinstance(error, dict) else "unknown"
+        message = error.get("message", resp.text) if isinstance(error, dict) else str(error)
+
+        status = resp.status_code
+        if status == 401:
+            raise AuthenticationError(code, message)
+        if status == 403:
+            raise PermissionError(code, message)
+        if status == 404:
+            raise NotFoundError(code, message)
+        if status == 429:
+            raise RateLimitError(code, message)
+        raise APIError(status, code, message)

gurucloud_kb/_http.py

@@ -0,0 +1,112 @@
+"""Low-level HTTP transport for the GuruCloud KB SDK.
+
+Wraps httpx to provide:
+- Automatic Bearer token injection
+- Response envelope unwrapping  (``{"data": ...}``)
+- Typed error raising
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from gurucloud_kb.errors import (
+    APIError,
+    AuthenticationError,
+    ConnectionError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+)
+
+_DEFAULT_TIMEOUT = 30.0
+
+
+class HTTPClient:
+    """Thin wrapper around httpx for the KB API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=f"{self._base_url}/api/v1/kb",
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    # ── public verbs ────────────────────────────────────────────
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, json: Any = None) -> Any:
+        return self._request("POST", path, json=json)
+
+    def put(self, path: str, json: Any = None) -> Any:
+        return self._request("PUT", path, json=json)
+
+    def patch(self, path: str, json: Any = None) -> Any:
+        return self._request("PATCH", path, json=json)
+
+    def delete(self, path: str) -> Any:
+        return self._request("DELETE", path)
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ── internals ───────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+    ) -> Any:
+        try:
+            resp = self._client.request(method, path, params=params, json=json)
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"Cannot reach {self._base_url}: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise ConnectionError(f"Request timed out: {exc}") from exc
+
+        if resp.status_code >= 400:
+            self._raise_for_status(resp)
+
+        # The API wraps successful responses in {"data": ...}
+        body = resp.json()
+        if isinstance(body, dict) and "data" in body:
+            return body["data"]
+        return body
+
+    @staticmethod
+    def _raise_for_status(resp: httpx.Response) -> None:
+        """Map HTTP error responses to typed SDK exceptions."""
+        try:
+            body = resp.json()
+        except Exception:
+            raise APIError(resp.status_code, "unknown", resp.text)
+
+        error = body.get("error", {})
+        code = error.get("code", "unknown") if isinstance(error, dict) else "unknown"
+        message = error.get("message", resp.text) if isinstance(error, dict) else str(error)
+
+        status = resp.status_code
+        if status == 401:
+            raise AuthenticationError(code, message)
+        if status == 403:
+            raise PermissionError(code, message)
+        if status == 404:
+            raise NotFoundError(code, message)
+        if status == 429:
+            raise RateLimitError(code, message)
+        raise APIError(status, code, message)

gurucloud_kb/async_client.py

@@ -0,0 +1,187 @@
+"""AsyncGuruCloudClient — async entry point for the SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from gurucloud_kb._async_http import AsyncHTTPClient
+from gurucloud_kb.async_kb import AsyncKnowledgeBank
+from gurucloud_kb.types import (
+    APIKeyInfo,
+    DimensionSchema,
+    KBInfo,
+    MCPServerDefinition,
+)
+
+_DEFAULT_BASE_URL = "https://www.gurucloudai.com"
+
+
+class AsyncGuruCloudClient:
+    """Async client for the GuruCloud Knowledge Bank API.
+
+    Authenticate with a KB API key (``kb_...``).
+
+    Example::
+
+        from gurucloud_kb import AsyncGuruCloudClient
+
+        async with AsyncGuruCloudClient(api_key="kb_abc123...") as client:
+            kb = await client.get_kb("my-kb-uuid")
+            results = await kb.search("how does auth work?")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        """Initialize the async client.
+
+        Args:
+            api_key: KB API key (starts with ``kb_``).
+            base_url: GuruCloud API base URL.
+            timeout: Request timeout in seconds.
+        """
+        if not api_key.startswith("kb_"):
+            raise ValueError("API key must start with 'kb_'")
+
+        self._http = AsyncHTTPClient(base_url=base_url, api_key=api_key, timeout=timeout)
+
+    # ── Knowledge Bank operations ───────────────────────────────
+
+    async def list_kbs(self) -> list[KBInfo]:
+        """List all Knowledge Banks owned by the authenticated user."""
+        return await self._http.get("/banks")
+
+    async def get_kb(self, kb_id: str) -> AsyncKnowledgeBank:
+        """Get a Knowledge Bank by ID, returning an :class:`AsyncKnowledgeBank` object.
+
+        Args:
+            kb_id: Knowledge Bank UUID.
+
+        Returns:
+            An :class:`AsyncKnowledgeBank` instance.
+        """
+        info: KBInfo = await self._http.get(f"/banks/{kb_id}")
+        return AsyncKnowledgeBank(self._http, info)
+
+    async def create_kb(
+        self,
+        name: str,
+        *,
+        description: str = "",
+        dimension_schema: DimensionSchema | None = None,
+    ) -> AsyncKnowledgeBank:
+        """Create a new Knowledge Bank.
+
+        Args:
+            name: Human-readable KB name.
+            description: Optional description.
+            dimension_schema: Optional custom schema (uses default if omitted).
+
+        Returns:
+            An :class:`AsyncKnowledgeBank` instance for the new KB.
+        """
+        payload: dict[str, Any] = {"name": name, "description": description}
+        if dimension_schema is not None:
+            payload["dimension_schema"] = dimension_schema
+
+        info: KBInfo = await self._http.post("/banks", json=payload)
+        return AsyncKnowledgeBank(self._http, info)
+
+    async def update_kb(
+        self,
+        kb_id: str,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> KBInfo:
+        """Update a KB's name and/or description.
+
+        Args:
+            kb_id: Knowledge Bank UUID.
+            name: New name (optional).
+            description: New description (optional).
+
+        Returns:
+            Updated KB info.
+        """
+        updates: dict[str, str] = {}
+        if name is not None:
+            updates["name"] = name
+        if description is not None:
+            updates["description"] = description
+        return await self._http.patch(f"/banks/{kb_id}", json=updates)
+
+    async def delete_kb(self, kb_id: str) -> dict[str, Any]:
+        """Delete a Knowledge Bank and all associated resources.
+
+        Requires ``admin`` scope on the API key.
+        """
+        return await self._http.delete(f"/banks/{kb_id}")
+
+    # ── MCP server definition ───────────────────────────────────
+
+    async def get_mcp_server_definition(self, kb_id: str) -> MCPServerDefinition:
+        """Get the MCP server definition for a KB, including a PAT.
+
+        Args:
+            kb_id: Knowledge Bank UUID.
+
+        Returns:
+            Full MCP server definition with token for agent injection.
+        """
+        return await self._http.post(f"/banks/{kb_id}/mcp-server-definition")
+
+    # ── API key management ──────────────────────────────────────
+
+    async def create_api_key(
+        self,
+        name: str,
+        *,
+        scopes: list[str] | None = None,
+        expires_at: str | None = None,
+        rate_limit_per_hour: int = 1000,
+    ) -> APIKeyInfo:
+        """Create a new API key.
+
+        Args:
+            name: Human-readable label.
+            scopes: Granted scopes (default: ``["read", "write"]``).
+            expires_at: Optional ISO 8601 expiry timestamp.
+            rate_limit_per_hour: Rate limit (default: 1000).
+
+        Returns:
+            API key info including the raw key.
+        """
+        payload: dict[str, Any] = {"name": name, "rate_limit_per_hour": rate_limit_per_hour}
+        if scopes is not None:
+            payload["scopes"] = scopes
+        if expires_at is not None:
+            payload["expires_at"] = expires_at
+        return await self._http.post("/api-keys", json=payload)
+
+    async def list_api_keys(self) -> list[APIKeyInfo]:
+        """List all API keys (keys are masked)."""
+        return await self._http.get("/api-keys")
+
+    async def delete_api_key(self, key_id: str) -> dict[str, Any]:
+        """Delete an API key."""
+        return await self._http.delete(f"/api-keys/{key_id}")
+
+    # ── lifecycle ───────────────────────────────────────────────
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._http.close()
+
+    async def __aenter__(self) -> AsyncGuruCloudClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return f"AsyncGuruCloudClient(base_url={self._http._base_url!r})"