gurucloud-kb 0.1.0__tar.gz

gurucloud_kb-0.1.0/.gitignore

@@ -0,0 +1,90 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+.playwright-mcp/
+.pytest_cache/
+
+# Virtual Environment
+venv/
+ENV/
+.env
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Claude Code MCP config (contains user-specific tokens)
+.mcp.json
+
+# Docker
+docker-compose.override.yml
+
+# Database
+*.sqlite3
+*.db
+
+# Project specific
+application_default_credentials.json
+*.log
+local_cache/
+local_files/
+
+# Gmail API credentials (generated via admin UI)
+credentials.json
+token.json
+
+# Logs directory
+logs/
+
+# OS specific
+.DS_Store
+Thumbs.db
+
+# Secrets and credentials
+*.pem
+*.key
+secrets/
+
+# Initialization tracking
+initialization_scripts/initialization_status.json
+
+# Certbot/Let's Encrypt files (contain sensitive account data)
+certbot/conf/accounts/
+certbot/conf/live/
+certbot/conf/renewal/
+certbot/conf/archive/
+certbot/conf/keys/
+
+# Node.js
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.npm/
+.yarn/
+
+gcloud_credentials.json
+*.glb
+*.blend
+*.blend1

gurucloud_kb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GuruCloud AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gurucloud_kb-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: gurucloud-kb
+Version: 0.1.0
+Summary: Python SDK for the GuruCloud Knowledge Bank API
+Author-email: GuruCloud AI <support@gurucloudai.com>
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# GuruCloud KB SDK
+
+Python SDK for the [GuruCloud Knowledge Bank API](https://www.gurucloudai.com/docs/kb).
+
+**Full documentation**: [gurucloudai.com/docs/kb](https://www.gurucloudai.com/docs/kb)
+**OpenAPI spec**: [gurucloudai.com/docs/kb/openapi.json](https://www.gurucloudai.com/docs/kb/openapi.json)
+
+## Installation
+
+```bash
+pip install gurucloud-kb
+```
+
+## Quick Start
+
+```python
+from gurucloud_kb import GuruCloudClient
+
+client = GuruCloudClient(api_key="kb_your_api_key")
+
+# List your Knowledge Banks
+kbs = client.list_kbs()
+
+# Work with a specific KB
+kb = client.get_kb("your-kb-uuid")
+
+# Search
+results = kb.search("how does authentication work?")
+for r in results:
+    print(r["content"], r["combined_score"])
+
+# Add an entry
+kb.add_entry({
+    "dimensions": {
+        "content": "The auth service uses JWT tokens with RS256 signing.",
+        "useful_for": "Understanding authentication architecture",
+    }
+})
+```
+
+## Async Support
+
+```python
+from gurucloud_kb import AsyncGuruCloudClient
+
+async with AsyncGuruCloudClient(api_key="kb_your_api_key") as client:
+    kb = await client.get_kb("your-kb-uuid")
+    results = await kb.search("deployment process")
+```
+
+## Key Features
+
+- **Sync & async clients** — `GuruCloudClient` and `AsyncGuruCloudClient`
+- **Knowledge Bank CRUD** — create, list, update, delete KBs
+- **Entry management** — add, update, delete, batch ingest entries
+- **Semantic search** — single-query or multi-dimensional weighted search
+- **Schema management** — get, update, validate dimension schemas
+- **MCP integration** — get MCP server definitions for agent injection
+- **Deduplication events** — inspect how entries were deduplicated
+- **Event logs** — trace entry processing lifecycle
+- **API key management** — create, list, delete API keys
+- **Typed responses** — all methods return TypedDict types for IDE autocomplete
+
+## Entry Management
+
+```python
+# List entries
+entries = kb.list_entries(limit=20, offset=0)
+
+# Get a single entry
+entry = kb.get_entry("entry-uuid")
+
+# Update an entry
+kb.update_entry("entry-uuid", {"dimensions": {"content": "Updated content"}})
+
+# Delete
+kb.delete_entry("entry-uuid")
+
+# Batch ingest with deduplication
+result = kb.ingest([
+    {"dimensions": {"content": "Fact 1", "useful_for": "Context 1"}},
+    {"dimensions": {"content": "Fact 2", "useful_for": "Context 2"}},
+], deduplicate=True)
+print(f"Ingested: {result['ingested']}")
+```
+
+## Search
+
+```python
+# Simple string search (searches the "content" dimension)
+results = kb.search("authentication flow", k=5, threshold=0.6)
+
+# Multi-dimensional weighted search
+results = kb.search({
+    "dimensions": {
+        "content": {"query_text": "JWT tokens", "weight": 0.7},
+        "useful_for": {"query_text": "security audit", "weight": 0.3},
+    },
+    "k": 10,
+    "threshold": 0.5,
+})
+```
+
+## MCP Integration
+
+```python
+# Get MCP server definition for agent injection
+mcp_def = kb.get_mcp_server_definition()
+
+# Use in agent config:
+mcp_config = {
+    "type": "http",
+    "url": mcp_def["url"],
+    "headers": {"Authorization": f"Bearer {mcp_def['token']}"}
+}
+```
+
+## Deduplication Events
+
+```python
+# List dedup events
+events = kb.list_events(action="conflict", limit=20)
+
+# Get full event details
+event = kb.get_event("event-uuid")
+print(event["reasoning"], event["action"])
+
+# Entry processing logs
+logs = kb.list_event_logs(event_type="dedup", limit=50)
+```
+
+## Error Handling
+
+```python
+from gurucloud_kb import (
+    GuruCloudError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+)
+
+try:
+    kb = client.get_kb("bad-uuid")
+except NotFoundError:
+    print("KB not found")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError:
+    print("Rate limited — slow down")
+except GuruCloudError as e:
+    print(f"API error: {e.message}")
+```
+
+## Requirements
+
+- Python 3.10+
+- `httpx` >= 0.25.0
+
+## License
+
+MIT

gurucloud_kb-0.1.0/README.md

@@ -0,0 +1,161 @@
+# GuruCloud KB SDK
+
+Python SDK for the [GuruCloud Knowledge Bank API](https://www.gurucloudai.com/docs/kb).
+
+**Full documentation**: [gurucloudai.com/docs/kb](https://www.gurucloudai.com/docs/kb)
+**OpenAPI spec**: [gurucloudai.com/docs/kb/openapi.json](https://www.gurucloudai.com/docs/kb/openapi.json)
+
+## Installation
+
+```bash
+pip install gurucloud-kb
+```
+
+## Quick Start
+
+```python
+from gurucloud_kb import GuruCloudClient
+
+client = GuruCloudClient(api_key="kb_your_api_key")
+
+# List your Knowledge Banks
+kbs = client.list_kbs()
+
+# Work with a specific KB
+kb = client.get_kb("your-kb-uuid")
+
+# Search
+results = kb.search("how does authentication work?")
+for r in results:
+    print(r["content"], r["combined_score"])
+
+# Add an entry
+kb.add_entry({
+    "dimensions": {
+        "content": "The auth service uses JWT tokens with RS256 signing.",
+        "useful_for": "Understanding authentication architecture",
+    }
+})
+```
+
+## Async Support
+
+```python
+from gurucloud_kb import AsyncGuruCloudClient
+
+async with AsyncGuruCloudClient(api_key="kb_your_api_key") as client:
+    kb = await client.get_kb("your-kb-uuid")
+    results = await kb.search("deployment process")
+```
+
+## Key Features
+
+- **Sync & async clients** — `GuruCloudClient` and `AsyncGuruCloudClient`
+- **Knowledge Bank CRUD** — create, list, update, delete KBs
+- **Entry management** — add, update, delete, batch ingest entries
+- **Semantic search** — single-query or multi-dimensional weighted search
+- **Schema management** — get, update, validate dimension schemas
+- **MCP integration** — get MCP server definitions for agent injection
+- **Deduplication events** — inspect how entries were deduplicated
+- **Event logs** — trace entry processing lifecycle
+- **API key management** — create, list, delete API keys
+- **Typed responses** — all methods return TypedDict types for IDE autocomplete
+
+## Entry Management
+
+```python
+# List entries
+entries = kb.list_entries(limit=20, offset=0)
+
+# Get a single entry
+entry = kb.get_entry("entry-uuid")
+
+# Update an entry
+kb.update_entry("entry-uuid", {"dimensions": {"content": "Updated content"}})
+
+# Delete
+kb.delete_entry("entry-uuid")
+
+# Batch ingest with deduplication
+result = kb.ingest([
+    {"dimensions": {"content": "Fact 1", "useful_for": "Context 1"}},
+    {"dimensions": {"content": "Fact 2", "useful_for": "Context 2"}},
+], deduplicate=True)
+print(f"Ingested: {result['ingested']}")
+```
+
+## Search
+
+```python
+# Simple string search (searches the "content" dimension)
+results = kb.search("authentication flow", k=5, threshold=0.6)
+
+# Multi-dimensional weighted search
+results = kb.search({
+    "dimensions": {
+        "content": {"query_text": "JWT tokens", "weight": 0.7},
+        "useful_for": {"query_text": "security audit", "weight": 0.3},
+    },
+    "k": 10,
+    "threshold": 0.5,
+})
+```
+
+## MCP Integration
+
+```python
+# Get MCP server definition for agent injection
+mcp_def = kb.get_mcp_server_definition()
+
+# Use in agent config:
+mcp_config = {
+    "type": "http",
+    "url": mcp_def["url"],
+    "headers": {"Authorization": f"Bearer {mcp_def['token']}"}
+}
+```
+
+## Deduplication Events
+
+```python
+# List dedup events
+events = kb.list_events(action="conflict", limit=20)
+
+# Get full event details
+event = kb.get_event("event-uuid")
+print(event["reasoning"], event["action"])
+
+# Entry processing logs
+logs = kb.list_event_logs(event_type="dedup", limit=50)
+```
+
+## Error Handling
+
+```python
+from gurucloud_kb import (
+    GuruCloudError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+)
+
+try:
+    kb = client.get_kb("bad-uuid")
+except NotFoundError:
+    print("KB not found")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError:
+    print("Rate limited — slow down")
+except GuruCloudError as e:
+    print(f"API error: {e.message}")
+```
+
+## Requirements
+
+- Python 3.10+
+- `httpx` >= 0.25.0
+
+## License
+
+MIT

gurucloud_kb-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gurucloud-kb"
+version = "0.1.0"
+description = "Python SDK for the GuruCloud Knowledge Bank API"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "GuruCloud AI", email = "support@gurucloudai.com" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "respx>=0.21",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gurucloud_kb"]
+
+[tool.pyright]
+pythonVersion = "3.10"
+typeCheckingMode = "strict"

gurucloud_kb-0.1.0/src/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-0.1.0/src/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)