knowledge2 0.4.0__py3-none-any.whl

sdk/resources/usage.py

@@ -0,0 +1,92 @@
+"""Usage metrics resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sdk._request_options import RequestOptions
+from sdk.resources._mixin_base import RequesterMixin
+from sdk.types import UsageByCorpusResponse, UsageByKeyResponse, UsageSummaryResponse
+
+
+class UsageMixin(RequesterMixin):
+    def usage_summary(
+        self,
+        *,
+        range_value: str = "7d",
+        corpus_id: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> UsageSummaryResponse:
+        """Retrieve an aggregate usage summary.
+
+        .. note:: Requires **bearer token** auth, not an API key.
+
+        Args:
+            range_value: Time range for the summary (e.g. ``"7d"``,
+                ``"30d"``).
+            corpus_id: Optional corpus to scope the summary to.
+
+        Returns:
+            Aggregated usage statistics for the requested period.
+
+        Raises:
+            AuthenticationError: If called with an API key instead of a
+                bearer token.
+            Knowledge2Error: If the API request fails.
+        """
+        params: dict[str, Any] = {"range": range_value}
+        if corpus_id:
+            params["corpus_id"] = corpus_id
+        data = self._request(
+            "GET", "/v1/usage/summary", params=params, request_options=request_options
+        )
+        return self._maybe_validate(data, "UsageSummaryResponse")
+
+    def usage_by_corpus(
+        self,
+        *,
+        range_value: str = "7d",
+        request_options: RequestOptions | None = None,
+    ) -> UsageByCorpusResponse:
+        """Retrieve usage metrics broken down by corpus.
+
+        .. note:: Requires **bearer token** auth, not an API key.
+
+        Args:
+            range_value: Time range for the breakdown (e.g. ``"7d"``,
+                ``"30d"``).
+
+        Returns:
+            Per-corpus usage statistics for the requested period.
+
+        Raises:
+            AuthenticationError: If called with an API key instead of a
+                bearer token.
+            Knowledge2Error: If the API request fails.
+        """
+        data = self._request(
+            "GET",
+            "/v1/usage/by_corpus",
+            params={"range": range_value},
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "UsageByCorpusResponse")
+
+    def usage_by_key(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> UsageByKeyResponse:
+        """Retrieve usage metrics broken down by API key.
+
+        .. note:: Requires **bearer token** auth, not an API key.
+
+        Returns:
+            Per-key usage statistics.
+
+        Raises:
+            AuthenticationError: If called with an API key instead of a
+                bearer token.
+            Knowledge2Error: If the API request fails.
+        """
+        data = self._request("GET", "/v1/usage/by_key", request_options=request_options)
+        return self._maybe_validate(data, "UsageByKeyResponse")

sdk/types/__init__.py

@@ -0,0 +1,366 @@
+from __future__ import annotations
+
+from .a2a import (
+    A2AAgentAuthentication,
+    A2AAgentCapabilities,
+    A2AAgentCardResponse,
+    A2AAgentProvider,
+    A2AAgentSkill,
+    A2AArtifact,
+    A2ADataPart,
+    A2AJsonRpcError,
+    A2AJsonRpcResponse,
+    A2ATaskResponse,
+    A2ATaskStatus,
+    A2ATextPart,
+)
+from .agents import (
+    AgentChatResponse,
+    AgentListResponse,
+    AgentModelInfo,
+    AgentModelsResponse,
+    AgentResponse,
+    AgentRunListItem,
+    AgentRunListResponse,
+    AgentRunResponse,
+    AgentTaskTypesResponse,
+    SourceAgentInfo,
+    SubscriptionListResponse,
+    SubscriptionResponse,
+    TaskTypeInfo,
+    ToolConfigResponse,
+)
+from .audit import AuditLogActionsResponse, AuditLogItem, AuditLogListResponse
+from .auth import (
+    ApiKeyCreateResponse,
+    ApiKeyListItem,
+    ApiKeyListResponse,
+    ApiKeyRevokeResponse,
+    ApiKeyRotateResponse,
+    WhoAmIResponse,
+)
+from .chunks import ChunkListItem, ChunkListResponse
+from .common import ApiErrorDetail
+from .console import (
+    ConsoleBootstrapResponse,
+    ConsoleMeResponse,
+    ConsoleOrgResponse,
+    ConsoleProjectItem,
+    ConsoleProjectListResponse,
+    ConsoleSummaryResponse,
+    InviteAcceptResponse,
+    InviteCreateResponse,
+    InviteListItem,
+    InviteListResponse,
+    MemberRemoveResponse,
+    MemberUpdateResponse,
+    TeamListResponse,
+    TeamMember,
+)
+from .corpora import (
+    CorpusDeleteResponse,
+    CorpusListResponse,
+    CorpusResponse,
+    CorpusStatusResponse,
+)
+from .deployments import DeploymentResponse
+from .documents import (
+    ChunkingConfig,
+    DocumentBatchItem,
+    DocumentBatchUploadResponse,
+    DocumentCreateResponse,
+    DocumentDeleteResponse,
+    DocumentDetailResponse,
+    DocumentListItem,
+    DocumentListResponse,
+    DocumentManifestIngestResponse,
+    DocumentUrlIngestResponse,
+    DocumentUrlItem,
+)
+from .embeddings import (
+    EmbeddingItem,
+    EmbeddingModelInfo,
+    EmbeddingModelListResponse,
+    EmbeddingsResponse,
+)
+from .evaluation import EvalRunDetailResponse, EvalRunResponse
+from .feedback import FeedbackResponse
+from .feeds import (
+    FeedListResponse,
+    FeedResponse,
+    FeedRunResponse,
+    FeedSubscriptionResponse,
+)
+from .indexes import IndexBuildResponse, IndexCompactResponse, IndexStatusResponse
+from .jobs import (
+    JobListItem,
+    JobListResponse,
+    JobResponse,
+    JobStatusResponse,
+    ReconcileJobsResponse,
+)
+from .models import ModelDeleteResponse, ModelListResponse, ModelResponse
+from .onboarding import (
+    DatasetAnalysisDetails,
+    DatasetAnalysisRequest,
+    DatasetAnalysisResponse,
+    DatasetAnalysisSummary,
+    DocumentSummaryResponse,
+    EvaluationDetails,
+    EvaluationListResponse,
+    EvaluationMetrics,
+    EvaluationReportResponse,
+    EvaluationRequest,
+    EvaluationResponse,
+    EvaluationSummary,
+    GoldLabelChunkReference,
+    GoldLabelDocumentReference,
+    GoldLabelEntry,
+    GoldLabelListItem,
+    GoldLabelsListResponse,
+    GoldLabelsUploadRequest,
+    GoldLabelsUploadResponse,
+    LexicalStrategy,
+    OnboardingStatusResponse,
+    ResolvedLabelInfo,
+    SearcherPersona,
+    SummarizationRequest,
+    SummarizationResponse,
+    SummarizationStatusResponse,
+    SyntheticQueryBatchDetails,
+    SyntheticQueryBatchListResponse,
+    SyntheticQueryBatchResponse,
+    SyntheticQueryBatchSummary,
+    SyntheticQueryGenerationRequest,
+    SyntheticQuerySample,
+)
+from .orgs import OrgResponse
+from .pipelines import (
+    ApplyResult,
+    ArchiveResult,
+    DraftActivateResult,
+    DriftReport,
+    DriftSummary,
+    DryRunResult,
+    EntityDiff,
+    FieldDiff,
+    GraphEdge,
+    GraphNode,
+    GraphResponse,
+    PipelineSpecListResponse,
+    PipelineSpecResponse,
+    RefreshChanges,
+    RefreshResult,
+    SkippedEntity,
+    ValidationIssue,
+)
+from .projects import ProjectListResponse, ProjectResponse
+from .search import (
+    SearchBatchOptions,
+    SearchBatchResponse,
+    SearchColdStartMeta,
+    SearchGenerateOptions,
+    SearchGenerateResponse,
+    SearchGenerationConfig,
+    SearchHybridConfig,
+    SearchMeta,
+    SearchOptions,
+    SearchRerankConfig,
+    SearchResponse,
+    SearchResult,
+    SearchReturnConfig,
+)
+from .training import (
+    CancelTuningRunResponse,
+    PromoteResponse,
+    TrainingDataBuildResponse,
+    TrainingDatasetListResponse,
+    TrainingDatasetResponse,
+    TuningRunBuildResponse,
+    TuningRunDetailResponse,
+    TuningRunListResponse,
+    TuningRunLogsResponse,
+    TuningRunResponse,
+)
+from .usage import (
+    UsageByCorpusItem,
+    UsageByCorpusResponse,
+    UsageByKeyItem,
+    UsageByKeyResponse,
+    UsageSeriesPoint,
+    UsageSummaryResponse,
+)
+
+__all__ = [
+    "A2AAgentAuthentication",
+    "A2AAgentCapabilities",
+    "A2AAgentCardResponse",
+    "A2AAgentProvider",
+    "A2AAgentSkill",
+    "A2AArtifact",
+    "A2ADataPart",
+    "A2AJsonRpcError",
+    "A2AJsonRpcResponse",
+    "A2ATaskResponse",
+    "A2ATaskStatus",
+    "A2ATextPart",
+    "AgentChatResponse",
+    "AgentListResponse",
+    "AgentModelInfo",
+    "AgentModelsResponse",
+    "AgentResponse",
+    "AgentRunListItem",
+    "AgentRunListResponse",
+    "AgentRunResponse",
+    "AgentTaskTypesResponse",
+    "ApiErrorDetail",
+    "ApiKeyCreateResponse",
+    "ApiKeyListItem",
+    "ApiKeyListResponse",
+    "ApiKeyRevokeResponse",
+    "ApiKeyRotateResponse",
+    "ApplyResult",
+    "ArchiveResult",
+    "AuditLogActionsResponse",
+    "AuditLogItem",
+    "AuditLogListResponse",
+    "CancelTuningRunResponse",
+    "ChunkListItem",
+    "ChunkListResponse",
+    "ChunkingConfig",
+    "ConsoleBootstrapResponse",
+    "ConsoleMeResponse",
+    "ConsoleOrgResponse",
+    "ConsoleProjectItem",
+    "ConsoleProjectListResponse",
+    "ConsoleSummaryResponse",
+    "CorpusDeleteResponse",
+    "CorpusListResponse",
+    "CorpusResponse",
+    "CorpusStatusResponse",
+    "DatasetAnalysisDetails",
+    "DatasetAnalysisRequest",
+    "DatasetAnalysisResponse",
+    "DatasetAnalysisSummary",
+    "DeploymentResponse",
+    "DocumentBatchItem",
+    "DocumentBatchUploadResponse",
+    "DocumentCreateResponse",
+    "DocumentDeleteResponse",
+    "DocumentDetailResponse",
+    "DocumentListItem",
+    "DocumentListResponse",
+    "DocumentManifestIngestResponse",
+    "DocumentSummaryResponse",
+    "DocumentUrlIngestResponse",
+    "DocumentUrlItem",
+    "DraftActivateResult",
+    "DriftReport",
+    "DriftSummary",
+    "DryRunResult",
+    "EmbeddingItem",
+    "EmbeddingModelInfo",
+    "EmbeddingModelListResponse",
+    "EmbeddingsResponse",
+    "EntityDiff",
+    "EvalRunDetailResponse",
+    "EvalRunResponse",
+    "EvaluationDetails",
+    "EvaluationListResponse",
+    "EvaluationMetrics",
+    "EvaluationReportResponse",
+    "EvaluationRequest",
+    "EvaluationResponse",
+    "EvaluationSummary",
+    "FeedListResponse",
+    "FeedResponse",
+    "FeedRunResponse",
+    "FeedSubscriptionResponse",
+    "FeedbackResponse",
+    "FieldDiff",
+    "GoldLabelChunkReference",
+    "GoldLabelDocumentReference",
+    "GoldLabelEntry",
+    "GoldLabelListItem",
+    "GoldLabelsListResponse",
+    "GoldLabelsUploadRequest",
+    "GoldLabelsUploadResponse",
+    "GraphEdge",
+    "GraphNode",
+    "GraphResponse",
+    "IndexBuildResponse",
+    "IndexCompactResponse",
+    "IndexStatusResponse",
+    "InviteAcceptResponse",
+    "InviteCreateResponse",
+    "InviteListItem",
+    "InviteListResponse",
+    "JobListItem",
+    "JobListResponse",
+    "JobResponse",
+    "JobStatusResponse",
+    "LexicalStrategy",
+    "MemberRemoveResponse",
+    "MemberUpdateResponse",
+    "ModelDeleteResponse",
+    "ModelListResponse",
+    "ModelResponse",
+    "OnboardingStatusResponse",
+    "OrgResponse",
+    "PipelineSpecListResponse",
+    "PipelineSpecResponse",
+    "ProjectListResponse",
+    "ProjectResponse",
+    "PromoteResponse",
+    "ReconcileJobsResponse",
+    "RefreshChanges",
+    "RefreshResult",
+    "ResolvedLabelInfo",
+    "SearchBatchOptions",
+    "SearchBatchResponse",
+    "SearchColdStartMeta",
+    "SearchGenerateOptions",
+    "SearchGenerateResponse",
+    "SearchGenerationConfig",
+    "SearchHybridConfig",
+    "SearchMeta",
+    "SearchOptions",
+    "SearchRerankConfig",
+    "SearchResponse",
+    "SearchResult",
+    "SearchReturnConfig",
+    "SearcherPersona",
+    "SkippedEntity",
+    "SourceAgentInfo",
+    "SubscriptionListResponse",
+    "SubscriptionResponse",
+    "SummarizationRequest",
+    "SummarizationResponse",
+    "SummarizationStatusResponse",
+    "SyntheticQueryBatchDetails",
+    "SyntheticQueryBatchListResponse",
+    "SyntheticQueryBatchResponse",
+    "SyntheticQueryBatchSummary",
+    "SyntheticQueryGenerationRequest",
+    "SyntheticQuerySample",
+    "TaskTypeInfo",
+    "TeamListResponse",
+    "TeamMember",
+    "ToolConfigResponse",
+    "TrainingDataBuildResponse",
+    "TrainingDatasetListResponse",
+    "TrainingDatasetResponse",
+    "TuningRunBuildResponse",
+    "TuningRunDetailResponse",
+    "TuningRunListResponse",
+    "TuningRunLogsResponse",
+    "TuningRunResponse",
+    "UsageByCorpusItem",
+    "UsageByCorpusResponse",
+    "UsageByKeyItem",
+    "UsageByKeyResponse",
+    "UsageSeriesPoint",
+    "UsageSummaryResponse",
+    "ValidationIssue",
+    "WhoAmIResponse",
+]

sdk/types/a2a.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+
+class A2ATextPart(TypedDict):
+    kind: Literal["text"]
+    text: str
+
+
+class A2ADataPart(TypedDict):
+    kind: Literal["data"]
+    data: dict[str, Any]
+
+
+class A2AArtifact(TypedDict, total=False):
+    artifactId: str
+    name: str
+    parts: list[A2ATextPart | A2ADataPart]
+    metadata: dict[str, Any]
+
+
+class A2ATaskStatus(TypedDict, total=False):
+    state: str
+    timestamp: str
+    message: dict[str, Any]
+
+
+class A2ATaskResponse(TypedDict, total=False):
+    id: str
+    contextId: str
+    status: A2ATaskStatus
+    artifacts: list[A2AArtifact]
+    history: list[dict[str, Any]]
+    metadata: dict[str, Any]
+    kind: Literal["task"]
+
+
+class A2AJsonRpcError(TypedDict, total=False):
+    code: int
+    message: str
+    data: dict[str, Any]
+
+
+class A2AJsonRpcResponse(TypedDict, total=False):
+    jsonrpc: str
+    id: str | int
+    result: A2ATaskResponse
+    error: A2AJsonRpcError
+
+
+class A2AAgentSkill(TypedDict, total=False):
+    id: str
+    name: str
+    description: str
+    tags: list[str]
+    examples: list[str]
+    inputModes: list[str]
+    outputModes: list[str]
+
+
+class A2AAgentCapabilities(TypedDict, total=False):
+    streaming: bool
+    pushNotifications: bool
+    stateTransitionHistory: bool
+
+
+class A2AAgentProvider(TypedDict, total=False):
+    organization: str
+    url: str
+
+
+class A2AAgentAuthentication(TypedDict, total=False):
+    schemes: list[str]
+    credentials: str
+
+
+class A2AAgentCardResponse(TypedDict, total=False):
+    name: str
+    description: str
+    url: str
+    provider: A2AAgentProvider
+    version: str
+    capabilities: A2AAgentCapabilities
+    authentication: A2AAgentAuthentication
+    defaultInputModes: list[str]
+    defaultOutputModes: list[str]
+    skills: list[A2AAgentSkill]

sdk/types/agents.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class SourceAgentInfo(TypedDict, total=False):
+    """Source agent reference in an agent response."""
+
+    agent_id: str
+    agent_name: str
+    mode: str
+
+
+class ToolConfigResponse(TypedDict, total=False):
+    """Webhook tool configuration (secret masked in responses)."""
+
+    webhook_url: str
+    webhook_secret: str | None
+    webhook_retries: int | None
+
+
+class AgentResponse(TypedDict, total=False):
+    """A single knowledge agent record."""
+
+    id: str
+    org_id: str
+    project_id: str | None
+    name: str
+    slug: str
+    description: str | None
+    corpus_id: str | None
+    task_type: str
+    instructions: str | None
+    model: str
+    status: str
+    parent_agent_id: str | None
+    source_agents: list[SourceAgentInfo]
+    tool_config: ToolConfigResponse | None
+    created_at: str | None
+    updated_at: str | None
+
+
+class AgentListResponse(TypedDict):
+    """Paginated list of agents."""
+
+    agents: list[AgentResponse]
+    total: int
+    limit: int
+    offset: int
+
+
+class AgentChatResponse(TypedDict, total=False):
+    """Response from chatting with an agent."""
+
+    answer: str
+    model: str
+    results: list[dict[str, Any]]
+    used_sources: list[str]
+    meta: dict[str, Any] | None
+
+
+class AgentModelInfo(TypedDict, total=False):
+    """Information about an available agent model."""
+
+    id: str
+    name: str
+    provider: str
+    default: bool
+
+
+class AgentModelsResponse(TypedDict):
+    """List of available models for knowledge agents."""
+
+    models: list[AgentModelInfo]
+
+
+class TaskTypeInfo(TypedDict, total=False):
+    """Information about an available agent task type."""
+
+    id: str
+    name: str
+    description: str
+    output_schema: str | None
+    supports_chat: bool
+
+
+class AgentTaskTypesResponse(TypedDict):
+    """List of available agent task types."""
+
+    task_types: list[TaskTypeInfo]
+
+
+class AgentRunResponse(TypedDict):
+    """Response from triggering an agent task run."""
+
+    job_id: str
+    status: str
+
+
+class AgentRunListItem(TypedDict, total=False):
+    """A single agent task run in the runs list."""
+
+    job_id: str
+    status: str
+    created_at: str
+    completed_at: str | None
+    result: dict[str, Any] | None
+    error_message: str | None
+
+
+class AgentRunListResponse(TypedDict):
+    """Paginated list of agent task runs."""
+
+    runs: list[AgentRunListItem]
+    total: int
+
+
+class SubscriptionResponse(TypedDict, total=False):
+    """A feed subscription for an agent."""
+
+    id: str
+    agent_id: str
+    feed_id: str
+    feed_name: str | None
+    feed_activation_status: str | None
+    role: str
+    created_at: str
+
+
+class SubscriptionListResponse(TypedDict):
+    """List of feed subscriptions for an agent."""
+
+    subscriptions: list[SubscriptionResponse]

sdk/types/audit.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import List, Optional, TypedDict
+
+
+class AuditLogItem(TypedDict, total=False):
+    id: str
+    action: str
+    entity_type: str
+    entity_id: str | None
+    org_id: str
+    project_id: str | None
+    corpus_id: str | None
+    api_key_id: str | None
+    user_id: str | None
+    payload: dict
+    created_at: str
+
+
+class AuditLogListResponse(TypedDict):
+    logs: list[AuditLogItem]
+    total: int
+
+
+class AuditLogActionsResponse(TypedDict):
+    actions: list[str]