cognigy-api-client 0.1.0__py3-none-any.whl

cognigy/__init__.py

@@ -0,0 +1,26 @@
+from .client import CognigyClient
+from .async_client import AsyncCognigyClient
+from .exceptions import (
+    CognigyError,
+    CognigyConfigurationError,
+    CognigyAPIError,
+    CognigyValidationError,
+)
+from . import models
+from . import resources
+
+# Re-export all models and resources
+from .models import *  # noqa: F401, F403
+from .resources import *  # noqa: F401, F403
+
+Cognigy = CognigyClient
+
+__all__ = [
+    "Cognigy",
+    "CognigyClient",
+    "AsyncCognigyClient",
+    "CognigyError",
+    "CognigyConfigurationError",
+    "CognigyAPIError",
+    "CognigyValidationError",
+] + models.__all__ + resources.__all__

cognigy/async_client.py

@@ -0,0 +1,117 @@
+import logging
+import os
+import httpx
+from typing import Optional
+from .exceptions import CognigyConfigurationError, CognigyAPIError
+
+logger = logging.getLogger(__name__)
+
+class AsyncCognigyClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: int = 60
+    ):
+        self._api_key = api_key or os.getenv("COGNIGY_API_KEY")
+        if not self._api_key:
+            raise CognigyConfigurationError(
+                "API Key is required. Provide it as an argument or set COGNIGY_API_KEY environment variable."
+            )
+
+        self._base_url = base_url or os.getenv("COGNIGY_BASE_URL", "https://api-app.cognigy.ai")
+        if "api-" not in self._base_url.lower():
+            raise CognigyConfigurationError(
+                "Invalid base URL. Base URL must contain 'api-' in the domain name."
+                "Example: 'https://api-app.cognigy.ai' if you use the 'app.cognigy.ai' domain."
+            )
+
+        self.http_client: httpx.AsyncClient = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={
+                "X-API-Key": self._api_key,
+                "Accept": "application/json",
+            },
+            timeout=timeout
+        )
+
+        # Initialize resources
+        from .resources.projects import AsyncProjectsResource
+        from .resources.flows import AsyncFlowsResource
+        from .resources.nodes import AsyncNodesResource
+        from .resources.aiagents import AsyncAIAgentsResource
+        from .resources.analytics import AsyncAnalyticsResource
+        from .resources.conversations import AsyncConversationsResource
+        from .resources.knowledge_stores import AsyncKnowledgeStoresResource
+        from .resources.knowledge_chunks import AsyncKnowledgeChunksResource
+        from .resources.knowledge_sources import AsyncKnowledgeSourcesResource
+        from .resources.knowledge_connectors import AsyncKnowledgeConnectorsResource
+        from .resources.locales import AsyncLocalesResource
+        from .resources.logs import AsyncLogsResource
+        from .resources.tasks import AsyncTasksResource
+        from .resources.search import AsyncSearchResource
+        from .resources.snapshots import AsyncSnapshotsResource
+        from .resources.extensions import AsyncExtensionsResource
+        from .resources.functions import AsyncFunctionsResource
+        from .resources.llm import AsyncLLMResource
+        from .resources.connections import AsyncConnectionsResource
+
+        self.projects: AsyncProjectsResource = AsyncProjectsResource(self)
+        self.flows: AsyncFlowsResource = AsyncFlowsResource(self)
+        self.nodes: AsyncNodesResource = AsyncNodesResource(self)
+        self.aiagents: AsyncAIAgentsResource = AsyncAIAgentsResource(self)
+        self.analytics: AsyncAnalyticsResource = AsyncAnalyticsResource(self)
+        self.conversations: AsyncConversationsResource = AsyncConversationsResource(self)
+        self.knowledge_stores: AsyncKnowledgeStoresResource = AsyncKnowledgeStoresResource(self)
+        self.knowledge_chunks: AsyncKnowledgeChunksResource = AsyncKnowledgeChunksResource(self)
+        self.knowledge_sources: AsyncKnowledgeSourcesResource = AsyncKnowledgeSourcesResource(self)
+        self.knowledge_connectors: AsyncKnowledgeConnectorsResource = AsyncKnowledgeConnectorsResource(self)
+        self.locales: AsyncLocalesResource = AsyncLocalesResource(self)
+        self.logs: AsyncLogsResource = AsyncLogsResource(self)
+        self.tasks: AsyncTasksResource = AsyncTasksResource(self)
+        self.search: AsyncSearchResource = AsyncSearchResource(self)
+        self.snapshots: AsyncSnapshotsResource = AsyncSnapshotsResource(self)
+        self.extensions: AsyncExtensionsResource = AsyncExtensionsResource(self)
+        self.functions: AsyncFunctionsResource = AsyncFunctionsResource(self)
+        self.llm: AsyncLLMResource = AsyncLLMResource(self)
+        self.connections: AsyncConnectionsResource = AsyncConnectionsResource(self)
+
+    async def close(self):
+        await self.http_client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+
+    async def _request(self, method: str, path: str, **kwargs):
+        # Serialize Pydantic model if passed as data parameter (JSON body).
+        # When ``files`` is set, ``data`` is left as multipart form fields.
+        if "data" in kwargs and "files" not in kwargs:
+            data = kwargs.pop("data")
+            if hasattr(data, "model_dump"):
+                kwargs["json"] = data.model_dump(by_alias=True, exclude_none=True)
+            else:
+                kwargs["json"] = data
+
+        response = await self.http_client.request(method, path, **kwargs)
+        if not response.is_success:
+            logger.debug("API error response: %s", response.text)
+            try:
+                response_body = response.json()
+            except Exception:
+                response_body = response.text or None
+            raise CognigyAPIError(
+                message=f"API request failed: {response.reason_phrase}",
+                status_code=response.status_code,
+                response_body=response_body
+            )
+        # Cognigy update endpoints may return 204 No Content or empty body
+        if response.status_code == 204 or not response.text.strip():
+            return None
+        try:
+            return response.json()
+        except Exception:
+            logger.debug("Failed to parse JSON response: %s", response.text)
+            raise

cognigy/client.py

@@ -0,0 +1,117 @@
+import logging
+import os
+import httpx
+from typing import Optional
+from .exceptions import CognigyConfigurationError, CognigyAPIError
+
+logger = logging.getLogger(__name__)
+
+class CognigyClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: int = 60
+    ):
+        self._api_key = api_key or os.getenv("COGNIGY_API_KEY")
+        if not self._api_key:
+            raise CognigyConfigurationError(
+                "API Key is required. Provide it as an argument or set COGNIGY_API_KEY environment variable."
+            )
+
+        self._base_url = base_url or os.getenv("COGNIGY_BASE_URL", "https://api-app.cognigy.ai")
+        if "api-" not in self._base_url.lower() and "api.live.ai.telekomcloud.com" not in self._base_url.lower():
+            raise CognigyConfigurationError(
+                "Invalid base URL. Base URL must contain 'api-' in the domain name."
+                "Example: 'https://api-app.cognigy.ai' if you use the 'app.cognigy.ai' domain."
+            )
+        
+        self.http_client: httpx.Client = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "X-API-Key": self._api_key,
+                "Accept": "application/json",
+            },
+            timeout=timeout
+        )
+
+        # Initialize resources
+        from .resources.projects import ProjectsResource
+        from .resources.flows import FlowsResource
+        from .resources.nodes import NodesResource
+        from .resources.aiagents import AIAgentsResource
+        from .resources.analytics import AnalyticsResource
+        from .resources.conversations import ConversationsResource
+        from .resources.knowledge_stores import KnowledgeStoresResource
+        from .resources.knowledge_chunks import KnowledgeChunksResource
+        from .resources.knowledge_sources import KnowledgeSourcesResource
+        from .resources.knowledge_connectors import KnowledgeConnectorsResource
+        from .resources.locales import LocalesResource
+        from .resources.logs import LogsResource
+        from .resources.tasks import TasksResource
+        from .resources.search import SearchResource
+        from .resources.snapshots import SnapshotsResource
+        from .resources.extensions import ExtensionsResource
+        from .resources.functions import FunctionsResource
+        from .resources.llm import LLMResource
+        from .resources.connections import ConnectionsResource
+
+        self.projects: ProjectsResource = ProjectsResource(self)
+        self.flows: FlowsResource = FlowsResource(self)
+        self.nodes: NodesResource = NodesResource(self)
+        self.aiagents: AIAgentsResource = AIAgentsResource(self)
+        self.analytics: AnalyticsResource = AnalyticsResource(self)
+        self.conversations: ConversationsResource = ConversationsResource(self)
+        self.knowledge_stores: KnowledgeStoresResource = KnowledgeStoresResource(self)
+        self.knowledge_chunks: KnowledgeChunksResource = KnowledgeChunksResource(self)
+        self.knowledge_sources: KnowledgeSourcesResource = KnowledgeSourcesResource(self)
+        self.knowledge_connectors: KnowledgeConnectorsResource = KnowledgeConnectorsResource(self)
+        self.locales: LocalesResource = LocalesResource(self)
+        self.logs: LogsResource = LogsResource(self)
+        self.tasks: TasksResource = TasksResource(self)
+        self.search: SearchResource = SearchResource(self)
+        self.snapshots: SnapshotsResource = SnapshotsResource(self)
+        self.extensions: ExtensionsResource = ExtensionsResource(self)
+        self.functions: FunctionsResource = FunctionsResource(self)
+        self.llm: LLMResource = LLMResource(self)
+        self.connections: ConnectionsResource = ConnectionsResource(self)
+
+    def close(self):
+        self.http_client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def _request(self, method: str, path: str, **kwargs):
+        # Serialize Pydantic model if passed as data parameter (JSON body).
+        # When ``files`` is set, ``data`` is left as multipart form fields.
+        if "data" in kwargs and "files" not in kwargs:
+            data = kwargs.pop("data")
+            if hasattr(data, "model_dump"):
+                kwargs["json"] = data.model_dump(by_alias=True, exclude_none=True)
+            else:
+                kwargs["json"] = data
+
+        response = self.http_client.request(method, path, **kwargs)
+        if not response.is_success:
+            logger.debug("API error response: %s", response.text)
+            try:
+                response_body = response.json()
+            except Exception:
+                response_body = response.text or None
+            raise CognigyAPIError(
+                message=f"API request failed: {response.reason_phrase}",
+                status_code=response.status_code,
+                response_body=response_body
+            )
+        # Cognigy update endpoints may return 204 No Content or empty body
+        if response.status_code == 204 or not response.text.strip():
+            return None
+        try:
+            return response.json()
+        except Exception:
+            logger.debug("Failed to parse JSON response: %s", response.text)
+            raise

cognigy/exceptions.py

@@ -0,0 +1,39 @@
+class CognigyError(Exception):
+    """Base exception for all Cognigy SDK errors."""
+    pass
+
+
+class CognigyConfigurationError(CognigyError):
+    """Raised when the client is not configured correctly (e.g. missing API key)."""
+    pass
+
+
+class CognigyAPIError(CognigyError):
+    """Raised when the Cognigy API returns an error response."""
+    def __init__(self, message: str, status_code: int, response_body=None):
+        detail = ""
+        if response_body and isinstance(response_body, dict) and response_body.get("detail"):
+            detail = f" - {response_body.get('detail')}"
+        super().__init__(f"(Status: {status_code}) {message}{detail}")
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class CognigyValidationError(CognigyError):
+    """Raised when create/update data fails validation against the expected Pydantic model."""
+    def __init__(self, message: str, errors: list = None):
+        super().__init__(message)
+        self.errors = errors or []
+
+    def __str__(self) -> str:
+        if not self.errors:
+            return self.args[0] if self.args else "Validation failed."
+        lines = [self.args[0] if self.args else "Validation failed:"]
+        for err in self.errors:
+            loc = " -> ".join(str(x) for x in err.get("loc", ()))
+            msg = err.get("msg", "")
+            ctx = err.get("ctx")
+            if ctx:
+                msg = f"{msg} (context: {ctx})"
+            lines.append(f"  • {loc}: {msg}")
+        return "\n".join(lines)

cognigy/models/__init__.py

@@ -0,0 +1,275 @@
+from .project import (
+    Project,
+    ProjectCreate,
+    ProjectUpdate,
+    HandoverConfiguration,
+    CssColor,
+    CognigyColor,
+    ProjectLocale,
+    WhisperAssistConfiguration,
+)
+from .flow import (
+    Flow,
+    FlowCreate,
+    FlowUpdate,
+    FeedbackReport,
+    FeedbackReportFinding,
+    FeedbackReportInfo,
+    LowDataIntent,
+)
+from .aiagent import (
+    AIAgent,
+    AIAgentCreate,
+    AIAgentUpdate,
+    AIAgentJob,
+    AIAgentTool,
+    AIAgentValidateNameRequest,
+    SpeakingStyle,
+    VoiceConfigs,
+    SafetySettings,
+)
+from .node import (
+    Node,
+    NodeCreate,
+    NodeMove,
+    NodeUpdate,
+    NodeMock,
+    NodeSearchMatch,
+    NodeSearchResult,
+    Chart,
+    ChartNodeSummary,
+    ChartRelation,
+)
+from .analytics import (
+    CallCounterMetric,
+    ConversationCounterMetric,
+    ChannelConversations,
+)
+from .conversation import (
+    Conversation,
+    ConversationMessage,
+)
+from .knowledge_store import (
+    KnowledgeStore,
+    KnowledgeStoreCreate,
+    KnowledgeStoreUpdate,
+    KnowledgeStoreStatus,
+)
+from .knowledge_chunk import (
+    KnowledgeChunk,
+    KnowledgeChunkCreate,
+    KnowledgeChunkUpdate,
+)
+from .knowledge_source import (
+    KnowledgeSource,
+    KnowledgeSourceCreate,
+    KnowledgeSourceUpdate,
+    KnowledgeSourceType,
+    KnowledgeSourceStatus,
+    KnowledgeSourceMetaData,
+)
+from .knowledge_connector import (
+    KnowledgeConnector,
+    KnowledgeConnectorCreate,
+    KnowledgeConnectorUpdate,
+    KnowledgeConnectorExecutionStatus,
+    ConnectorSchedule,
+)
+from .locale import (
+    Locale,
+    LocaleCreate,
+    LocaleUpdate,
+    NluLanguage,
+)
+from .log import (
+    LogEntry,
+)
+from .task import (
+    Task,
+    TaskStatus,
+)
+from .search import (
+    SearchResult,
+    SearchResultType,
+    NLUConnectorSubType,
+    EndpointSubType,
+    GenerativeAIProviderSubType,
+)
+from .snapshot import (
+    Snapshot,
+    SnapshotCreate,
+    SnapshotResource,
+    SnapshotDownloadLink,
+    SnapshotRestoreRequest,
+    SnapshotDownloadLinkRequest,
+)
+from .extension import (
+    Extension,
+    ExtensionBackgroundTask,
+    ExtensionListItem,
+    ExtensionSettingsUpdate,
+    ExtensionUpdatePackageByUrl,
+    ExtensionUploadByUrl,
+)
+from .function import (
+    Function,
+    FunctionCreate,
+    FunctionUpdate,
+)
+from .llm import (
+    LLM,
+    LLMCreate,
+    LLMCreateForOrganisation,
+    LLMCreateForProject,
+    LLMTestResult,
+    LLMUpdate,
+)
+from .connection import (
+    Connection,
+    ConnectionBatchCreateOp,
+    ConnectionBatchCreateValue,
+    ConnectionBatchDeleteOp,
+    ConnectionBatchOperation,
+    ConnectionBatchRequest,
+    ConnectionBatchResult,
+    ConnectionBatchUpdateOp,
+    ConnectionBatchUpdateValue,
+    ConnectionCreate,
+    ConnectionFieldCreate,
+    ConnectionListItem,
+    ConnectionSchemaItem,
+    ConnectionSchemaRef,
+    ConnectionUpdate,
+    ResourceLevel,
+)
+from .base import CognigyBaseModel
+
+__all__ = [
+    # Base
+    "CognigyBaseModel",
+    # Project models
+    "Project",
+    "ProjectCreate",
+    "ProjectUpdate",
+    "HandoverConfiguration",
+    "CssColor",
+    "CognigyColor",
+    "ProjectLocale",
+    "WhisperAssistConfiguration",
+    # Flow models
+    "Flow",
+    "FlowCreate",
+    "FlowUpdate",
+    "FeedbackReport",
+    "FeedbackReportFinding",
+    "FeedbackReportInfo",
+    "LowDataIntent",
+    # AI Agent models
+    "AIAgent",
+    "AIAgentCreate",
+    "AIAgentUpdate",
+    "AIAgentJob",
+    "AIAgentTool",
+    "AIAgentValidateNameRequest",
+    "SpeakingStyle",
+    "VoiceConfigs",
+    "SafetySettings",
+    # Node models
+    "Node",
+    "NodeCreate",
+    "NodeMove",
+    "NodeUpdate",
+    "NodeMock",
+    "NodeSearchMatch",
+    "NodeSearchResult",
+    "Chart",
+    "ChartNodeSummary",
+    "ChartRelation",
+    # Analytics models
+    "CallCounterMetric",
+    "ConversationCounterMetric",
+    "ChannelConversations",
+    # Conversation models
+    "Conversation",
+    "ConversationMessage",
+    # KnowledgeStore models
+    "KnowledgeStore",
+    "KnowledgeStoreCreate",
+    "KnowledgeStoreUpdate",
+    "KnowledgeStoreStatus",
+    # KnowledgeChunk models
+    "KnowledgeChunk",
+    "KnowledgeChunkCreate",
+    "KnowledgeChunkUpdate",
+    # KnowledgeSource models
+    "KnowledgeSource",
+    "KnowledgeSourceCreate",
+    "KnowledgeSourceUpdate",
+    "KnowledgeSourceType",
+    "KnowledgeSourceStatus",
+    "KnowledgeSourceMetaData",
+    # KnowledgeConnector models
+    "KnowledgeConnector",
+    "KnowledgeConnectorCreate",
+    "KnowledgeConnectorUpdate",
+    "KnowledgeConnectorExecutionStatus",
+    "ConnectorSchedule",
+    # Locale models
+    "Locale",
+    "LocaleCreate",
+    "LocaleUpdate",
+    "NluLanguage",
+    # Log models
+    "LogEntry",
+    # Task models
+    "Task",
+    "TaskStatus",
+    # Search models
+    "SearchResult",
+    "SearchResultType",
+    "NLUConnectorSubType",
+    "EndpointSubType",
+    "GenerativeAIProviderSubType",
+    # Snapshot models
+    "Snapshot",
+    "SnapshotCreate",
+    "SnapshotResource",
+    "SnapshotDownloadLink",
+    "SnapshotRestoreRequest",
+    "SnapshotDownloadLinkRequest",
+    # Extension models
+    "Extension",
+    "ExtensionBackgroundTask",
+    "ExtensionListItem",
+    "ExtensionSettingsUpdate",
+    "ExtensionUpdatePackageByUrl",
+    "ExtensionUploadByUrl",
+    # Function models
+    "Function",
+    "FunctionCreate",
+    "FunctionUpdate",
+    # LLM models
+    "LLM",
+    "LLMCreate",
+    "LLMCreateForOrganisation",
+    "LLMCreateForProject",
+    "LLMTestResult",
+    "LLMUpdate",
+    # Connection models
+    "Connection",
+    "ConnectionBatchCreateOp",
+    "ConnectionBatchCreateValue",
+    "ConnectionBatchDeleteOp",
+    "ConnectionBatchOperation",
+    "ConnectionBatchRequest",
+    "ConnectionBatchResult",
+    "ConnectionBatchUpdateOp",
+    "ConnectionBatchUpdateValue",
+    "ConnectionCreate",
+    "ConnectionFieldCreate",
+    "ConnectionListItem",
+    "ConnectionSchemaItem",
+    "ConnectionSchemaRef",
+    "ConnectionUpdate",
+    "ResourceLevel",
+]