smart-knowledge 1.1.0__py3-none-any.whl

smart_knowledge/__init__.py

@@ -0,0 +1,90 @@
+"""Official Python 3.10+ SDK for the Smart Knowledge 5-Brain Autonomous Platform.
+
+Provides direct programmatic access to:
+- ask(): Grounded 5-Brain RAG Question Answering with primary citations.
+- search(): Multi-Modal Hybrid Search across Knowledge Graph, BM25, and semantic vectors.
+- agentask: Autonomous Problem Solver (PAOA) multi-step reasoning missions.
+- documents: Enterprise document ingestion pipeline with full pagination.
+"""
+
+from .client import SmartKnowledge
+from .config import ResolvedConfig
+from .errors import (
+    APIConnectionError,
+    AuthenticationError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    RateLimitError,
+    SmartKnowledgeError,
+    ValidationError,
+)
+from .types import (
+    AgentTaskProgress,
+    AgentaskDispatchOptions,
+    AgentaskDispatchResponse,
+    AgentaskResult,
+    AgentaskRunOptions,
+    AgentaskStatusResponse,
+    AskOptions,
+    AskResponse,
+    Citation,
+    ClientOptions,
+    DocumentStatusResponse,
+    DocumentUploadOptions,
+    DocumentUploadResponse,
+    FileListOptions,
+    FileRecord,
+    FileUploadInput,
+    FinOpsMetrics,
+    GraphTriplet,
+    PaginatedFilesResponse,
+    PaginationMeta,
+    RequestOptions,
+    SearchOptions,
+    SearchResponse,
+    VectorHit,
+    Bm25Hit,
+)
+
+__version__ = "1.1.0"
+
+__all__ = [
+    "SmartKnowledge",
+    "ResolvedConfig",
+    "SmartKnowledgeError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "QuotaExceededError",
+    "InternalServerError",
+    "APIConnectionError",
+    "ClientOptions",
+    "FinOpsMetrics",
+    "RequestOptions",
+    "AskOptions",
+    "AskResponse",
+    "Citation",
+    "SearchOptions",
+    "SearchResponse",
+    "GraphTriplet",
+    "VectorHit",
+    "Bm25Hit",
+    "AgentTaskProgress",
+    "AgentaskDispatchOptions",
+    "AgentaskDispatchResponse",
+    "AgentaskStatusResponse",
+    "AgentaskRunOptions",
+    "AgentaskResult",
+    "FileUploadInput",
+    "FileRecord",
+    "DocumentUploadOptions",
+    "DocumentUploadResponse",
+    "DocumentStatusResponse",
+    "PaginationMeta",
+    "FileListOptions",
+    "PaginatedFilesResponse",
+]

smart_knowledge/client.py

@@ -0,0 +1,88 @@
+"""SmartKnowledge primary client class for Python SDK."""
+
+from typing import Any, Dict, Optional, Union
+from .config import ResolvedConfig, resolve_config
+from .http import HttpClient
+from .modules.agentask import AgentaskModule
+from .modules.ask import AskModule
+from .modules.documents import DocumentsModule
+from .modules.search import SearchModule
+from .types.ask import AskOptions, AskResponse
+from .types.search import SearchOptions, SearchResponse
+
+
+class SmartKnowledge:
+    """Official Python client for the Smart Knowledge 5-Brain Autonomous Platform."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        default_headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        """Initialize the Smart Knowledge client.
+
+        :param api_key: Smart Knowledge API key (defaults to SMART_KNOWLEDGE_API_KEY environment variable).
+        :param base_url: Base URL of the API gateway (defaults to SMART_KNOWLEDGE_BASE_URL or 'https://ztrust.eu').
+        :param tenant_id: Target tenant workspace identifier (defaults to SMART_KNOWLEDGE_TENANT_ID or 'default').
+        :param timeout: Default request timeout in seconds (defaults to 60.0).
+        :param max_retries: Maximum automatic retry attempts on 429/5xx status codes (defaults to 2).
+        :param default_headers: Optional dictionary of headers to attach to every outgoing request.
+        """
+        self.config: ResolvedConfig = resolve_config(
+            api_key=api_key,
+            base_url=base_url,
+            tenant_id=tenant_id,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+        )
+        self.http = HttpClient(self.config)
+
+        self._ask_module = AskModule(self.http)
+        self._search_module = SearchModule(self.http)
+
+        # Autonomous Problem Solver (PAOA) module
+        self.agentask = AgentaskModule(self.http)
+
+        # Enterprise Document Ingestion and Library module
+        self.documents = DocumentsModule(self.http)
+
+    def ask(
+        self,
+        question_or_options: Optional[Union[str, AskOptions, Dict[str, Any]]] = None,
+        question: Optional[str] = None,
+        include_sources: bool = True,
+        timeout: Optional[float] = None,
+        options: Optional[Union[str, AskOptions, Dict[str, Any]]] = None,
+    ) -> AskResponse:
+        """Ask a question verified and grounded across the 5-Brain architecture."""
+        return self._ask_module.ask(
+            question_or_options=question_or_options,
+            question=question,
+            include_sources=include_sources,
+            timeout=timeout,
+            options=options,
+        )
+
+    def search(
+        self,
+        query_or_options: Optional[Union[str, SearchOptions, Dict[str, Any]]] = None,
+        query: Optional[str] = None,
+        decompose: bool = False,
+        limit: int = 10,
+        timeout: Optional[float] = None,
+        options: Optional[Union[str, SearchOptions, Dict[str, Any]]] = None,
+    ) -> SearchResponse:
+        """Multi-modal retrieval across Knowledge Graph triplets, BM25 keyword index, and semantic vectors."""
+        return self._search_module.search(
+            query_or_options=query_or_options,
+            query=query,
+            decompose=decompose,
+            limit=limit,
+            timeout=timeout,
+            options=options,
+        )

smart_knowledge/config.py

@@ -0,0 +1,63 @@
+"""Configuration resolver for the Smart Knowledge Python SDK."""
+
+import os
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+from .errors import ValidationError
+
+DEFAULT_BASE_URL = "https://ztrust.eu"
+DEFAULT_TENANT_ID = "default"
+DEFAULT_TIMEOUT_SEC = 60.0
+DEFAULT_MAX_RETRIES = 2
+
+
+@dataclass
+class ResolvedConfig:
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+    tenant_id: str = DEFAULT_TENANT_ID
+    timeout: float = DEFAULT_TIMEOUT_SEC
+    max_retries: int = DEFAULT_MAX_RETRIES
+    default_headers: Dict[str, str] = field(default_factory=dict)
+
+
+def resolve_config(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    timeout: Optional[float] = None,
+    max_retries: Optional[int] = None,
+    default_headers: Optional[Dict[str, str]] = None,
+) -> ResolvedConfig:
+    """Resolve and validate configuration options with environment fallbacks."""
+
+    resolved_key = (api_key or os.environ.get("SMART_KNOWLEDGE_API_KEY") or "").strip()
+    if not resolved_key:
+        raise ValidationError(
+            "Missing required API key. Pass 'api_key' to SmartKnowledge() or export SMART_KNOWLEDGE_API_KEY."
+        )
+
+    raw_base_url = (base_url or os.environ.get("SMART_KNOWLEDGE_BASE_URL") or DEFAULT_BASE_URL).strip()
+    resolved_base_url = raw_base_url.rstrip("/")
+
+    resolved_tenant = (tenant_id or os.environ.get("SMART_KNOWLEDGE_TENANT_ID") or DEFAULT_TENANT_ID).strip()
+    resolved_timeout = float(timeout if timeout is not None else DEFAULT_TIMEOUT_SEC)
+    resolved_retries = int(max_retries if max_retries is not None else DEFAULT_MAX_RETRIES)
+
+    headers = {
+        "Authorization": f"Bearer {resolved_key}",
+        "X-API-Key": resolved_key,
+        "X-Tenant-Id": resolved_tenant,
+        "User-Agent": "smart-knowledge-python-sdk/1.1.0",
+    }
+    if default_headers:
+        headers.update(default_headers)
+
+    return ResolvedConfig(
+        api_key=resolved_key,
+        base_url=resolved_base_url,
+        tenant_id=resolved_tenant,
+        timeout=resolved_timeout,
+        max_retries=resolved_retries,
+        default_headers=headers,
+    )

smart_knowledge/errors.py

@@ -0,0 +1,130 @@
+"""Custom typed error hierarchy for the Smart Knowledge SDK."""
+
+from typing import Any, Dict, Optional
+
+
+class SmartKnowledgeError(Exception):
+    """Base exception class for all Smart Knowledge errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response_body: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response_body = response_body
+        self.headers = headers or {}
+
+    def __str__(self) -> str:
+        if self.status_code:
+            return f"[{self.__class__.__name__} HTTP {self.status_code}] {self.message}"
+        return f"[{self.__class__.__name__}] {self.message}"
+
+
+class AuthenticationError(SmartKnowledgeError):
+    """Raised when authentication fails (HTTP 401: Invalid or expired API key)."""
+
+    def __init__(
+        self,
+        message: str = "Invalid, revoked, or missing Smart Knowledge API key.",
+        status_code: int = 401,
+        response_body: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_body=response_body, headers=headers)
+
+
+class PermissionDeniedError(SmartKnowledgeError):
+    """Raised when access is forbidden (HTTP 403: Role or tenant permission denied)."""
+
+    def __init__(
+        self,
+        message: str = "Forbidden: Caller does not possess required role or tenant permission.",
+        status_code: int = 403,
+        response_body: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_body=response_body, headers=headers)
+
+
+class NotFoundError(SmartKnowledgeError):
+    """Raised when a requested resource (document, task, tenant) does not exist (HTTP 404)."""
+
+    def __init__(
+        self,
+        message: str = "The requested resource was not found.",
+        status_code: int = 404,
+        response_body: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_body=response_body, headers=headers)
+
+
+class ValidationError(SmartKnowledgeError):
+    """Raised when invalid request parameters or missing required arguments are supplied."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 400,
+        response_body: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_body=response_body, headers=headers)
+
+
+class RateLimitError(SmartKnowledgeError):
+    """Raised when the rate limit is exceeded (HTTP 429). Includes retry_after_sec."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded. Please throttle your request frequency.",
+        retry_after_sec: Optional[float] = None,
+        status_code: int = 429,
+        response_body: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_body=response_body, headers=headers)
+        self.retry_after_sec = retry_after_sec
+
+
+class QuotaExceededError(SmartKnowledgeError):
+    """Raised when the tenant's monthly token or task quota is exhausted (HTTP 429)."""
+
+    def __init__(
+        self,
+        message: str = "Monthly LLM token quota exceeded for this tenant workspace.",
+        status_code: int = 429,
+        response_body: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_body=response_body, headers=headers)
+
+
+class InternalServerError(SmartKnowledgeError):
+    """Raised when the server encounters an internal error (HTTP 500/502/503/504)."""
+
+    def __init__(
+        self,
+        message: str = "Internal server error occurred within Smart Knowledge platform.",
+        status_code: int = 500,
+        response_body: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_body=response_body, headers=headers)
+
+
+class APIConnectionError(SmartKnowledgeError):
+    """Raised when an HTTP connection to the Smart Knowledge server fails or times out."""
+
+    def __init__(
+        self,
+        message: str = "Failed to establish a network connection to Smart Knowledge API.",
+        cause: Optional[Exception] = None,
+    ) -> None:
+        super().__init__(message)
+        self.__cause__ = cause

smart_knowledge/http.py

@@ -0,0 +1,163 @@
+"""HTTP transport layer for the Smart Knowledge Python SDK."""
+
+import random
+import time
+from typing import Any, Dict, Optional, Union
+import requests
+from .config import ResolvedConfig
+from .errors import (
+    APIConnectionError,
+    AuthenticationError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    RateLimitError,
+    SmartKnowledgeError,
+    ValidationError,
+)
+
+
+class HttpClient:
+    """Connection-pooled, resilient HTTP transport layer."""
+
+    def __init__(self, config: ResolvedConfig) -> None:
+        self.config = config
+        self.session = requests.Session()
+        self.session.headers.update(config.default_headers)
+
+    def build_url(self, path: str) -> str:
+        clean_path = path if path.startswith("/") else f"/{path}"
+        return f"{self.config.base_url}{clean_path}"
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Any] = None,
+        data: Optional[Any] = None,
+        files: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        url = self.build_url(path)
+        effective_timeout = timeout if timeout is not None else self.config.timeout
+        req_headers = dict(self.session.headers)
+        if headers:
+            req_headers.update(headers)
+
+        # Filter None params
+        filtered_params = {k: v for k, v in (params or {}).items() if v is not None} or None
+
+        attempt = 0
+        max_retries = self.config.max_retries
+
+        while True:
+            attempt += 1
+            try:
+                response = self.session.request(
+                    method=method.upper(),
+                    url=url,
+                    params=filtered_params,
+                    json=json_data,
+                    data=data,
+                    files=files,
+                    headers=req_headers,
+                    timeout=effective_timeout,
+                )
+
+                if response.status_code == 204:
+                    return None
+
+                if 200 <= response.status_code < 300:
+                    content_type = response.headers.get("content-type", "")
+                    if "application/json" in content_type:
+                        return response.json()
+                    return response.text
+
+                # Parse error body
+                error_body: Any = None
+                try:
+                    error_body = response.json()
+                except Exception:
+                    error_body = response.text
+
+                error_msg = self._extract_error_message(error_body) or f"HTTP {response.status_code}: {response.reason}"
+
+                # Check retryable status codes
+                if response.status_code in (429, 502, 503, 504) and attempt <= max_retries:
+                    retry_after = self._get_retry_after(response.headers, attempt)
+                    time.sleep(retry_after)
+                    continue
+
+                self._raise_for_status(response.status_code, error_msg, error_body, dict(response.headers))
+
+            except requests.exceptions.Timeout as e:
+                if attempt <= max_retries:
+                    time.sleep(1.0 * (2 ** (attempt - 1)) + random.uniform(0.1, 0.5))
+                    continue
+                raise APIConnectionError(f"Request timed out after {effective_timeout}s: {e}", cause=e)
+
+            except requests.exceptions.RequestException as e:
+                if isinstance(e, requests.exceptions.HTTPError):
+                    # Already handled above
+                    raise
+                if attempt <= max_retries:
+                    time.sleep(1.0 * (2 ** (attempt - 1)) + random.uniform(0.1, 0.5))
+                    continue
+                raise APIConnectionError(f"Network connection failed: {e}", cause=e)
+
+    def _extract_error_message(self, body: Any) -> Optional[str]:
+        if isinstance(body, dict):
+            if "error" in body:
+                err = body["error"]
+                if isinstance(err, str):
+                    return err
+                if isinstance(err, dict) and "message" in err:
+                    return str(err["message"])
+            if "message" in body:
+                return str(body["message"])
+            if "detail" in body:
+                return str(body["detail"])
+        elif isinstance(body, str) and body.strip():
+            return body.strip()
+        return None
+
+    def _get_retry_after(self, headers: Any, attempt: int) -> float:
+        if "Retry-After" in headers:
+            try:
+                return float(headers["Retry-After"])
+            except ValueError:
+                pass
+        backoff = 1.0 * (2 ** (attempt - 1))
+        jitter = random.uniform(0.1, 0.5)
+        return min(backoff + jitter, 15.0)
+
+    def _raise_for_status(
+        self,
+        status_code: int,
+        message: str,
+        body: Any,
+        headers: Dict[str, str],
+    ) -> None:
+        if status_code == 401:
+            raise AuthenticationError(message, status_code=status_code, response_body=body, headers=headers)
+        elif status_code == 403:
+            raise PermissionDeniedError(message, status_code=status_code, response_body=body, headers=headers)
+        elif status_code == 404:
+            raise NotFoundError(message, status_code=status_code, response_body=body, headers=headers)
+        elif status_code == 400:
+            raise ValidationError(message, status_code=status_code, response_body=body, headers=headers)
+        elif status_code == 429:
+            lower_msg = message.lower()
+            if "quota" in lower_msg or "monthly" in lower_msg:
+                raise QuotaExceededError(message, status_code=status_code, response_body=body, headers=headers)
+            retry_sec = self._get_retry_after(headers, 1)
+            raise RateLimitError(
+                message, retry_after_sec=retry_sec, status_code=status_code, response_body=body, headers=headers
+            )
+        elif status_code >= 500:
+            raise InternalServerError(message, status_code=status_code, response_body=body, headers=headers)
+        else:
+            raise SmartKnowledgeError(message, status_code=status_code, response_body=body, headers=headers)

smart_knowledge/modules/__init__.py

@@ -0,0 +1,13 @@
+"""Modules for Smart Knowledge Python SDK."""
+
+from .ask import AskModule
+from .search import SearchModule
+from .agentask import AgentaskModule
+from .documents import DocumentsModule
+
+__all__ = [
+    "AskModule",
+    "SearchModule",
+    "AgentaskModule",
+    "DocumentsModule",
+]