knowledge2 0.4.0__py3-none-any.whl

sdk/models/usage.py

@@ -0,0 +1,39 @@
+"""Pydantic models for usage types."""
+
+from __future__ import annotations
+
+from sdk.models._base import K2BaseModel
+
+
+class UsageSeriesPointModel(K2BaseModel):
+    date: str
+    count: int
+
+
+class UsageSummaryResponseModel(K2BaseModel):
+    range: str | None = None
+    total_requests: int | None = None
+    daily: list[UsageSeriesPointModel] | None = None
+    latency_p50_ms: float | None = None
+    latency_p95_ms: float | None = None
+    error_rate: float | None = None
+
+
+class UsageByCorpusItemModel(K2BaseModel):
+    corpus_id: str | None = None
+    corpus_name: str | None = None
+    requests: int | None = None
+
+
+class UsageByCorpusResponseModel(K2BaseModel):
+    items: list[UsageByCorpusItemModel]
+
+
+class UsageByKeyItemModel(K2BaseModel):
+    key_id: str | None = None
+    name: str | None = None
+    requests: int | None = None
+
+
+class UsageByKeyResponseModel(K2BaseModel):
+    items: list[UsageByKeyItemModel]

sdk/namespaces.py

@@ -0,0 +1,386 @@
+"""Sub-client namespace accessors for the Knowledge2 SDK.
+
+Lightweight proxy objects that group related methods into discoverable
+namespaces without changing the existing flat API::
+
+    # Flat (existing, unchanged)
+    client.upload_document(corpus_id, file_path="doc.pdf")
+
+    # Namespaced (new, equivalent)
+    client.documents.upload(corpus_id, file_path="doc.pdf")
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from sdk._paging import Page, SyncPager
+    from sdk.client import Knowledge2
+    from sdk.types import (
+        ApiKeyCreateResponse,
+        ApiKeyListResponse,
+        ApiKeyRevokeResponse,
+        ApiKeyRotateResponse,
+        ChunkingConfig,
+        CorpusDeleteResponse,
+        CorpusResponse,
+        CorpusStatusResponse,
+        DeploymentResponse,
+        DocumentBatchUploadResponse,
+        DocumentCreateResponse,
+        DocumentDeleteResponse,
+        DocumentDetailResponse,
+        DocumentManifestIngestResponse,
+        DocumentUrlIngestResponse,
+        EmbeddingsResponse,
+        FeedbackResponse,
+        JobResponse,
+        JobStatusResponse,
+        ModelDeleteResponse,
+        ReconcileJobsResponse,
+        SearchBatchResponse,
+        SearchGenerateResponse,
+        SearchResponse,
+        TuningRunDetailResponse,
+        TuningRunLogsResponse,
+        TuningRunResponse,
+        WhoAmIResponse,
+    )
+
+
+class _Namespace:
+    """Base class for namespace proxies."""
+
+    __slots__ = ("_client",)
+
+    def __init__(self, client: Knowledge2) -> None:
+        self._client = client
+
+
+# ------------------------------------------------------------------
+# Documents
+# ------------------------------------------------------------------
+
+
+class DocumentsNamespace(_Namespace):
+    """Document operations: ``client.documents.*``"""
+
+    def upload(
+        self,
+        corpus_id: str,
+        *,
+        file_path: str | None = None,
+        file_bytes: bytes | None = None,
+        filename: str | None = None,
+        raw_text: str | None = None,
+        source_uri: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        auto_index: bool | None = None,
+        chunk_strategy: str | None = None,
+        chunking: ChunkingConfig | None = None,
+        idempotency_key: str | None = None,
+    ) -> DocumentCreateResponse:
+        return self._client.upload_document(
+            corpus_id,
+            file_path=file_path,
+            file_bytes=file_bytes,
+            filename=filename,
+            raw_text=raw_text,
+            source_uri=source_uri,
+            metadata=metadata,
+            auto_index=auto_index,
+            chunk_strategy=chunk_strategy,
+            chunking=chunking,
+            idempotency_key=idempotency_key,
+        )
+
+    def upload_batch(
+        self,
+        corpus_id: str,
+        documents: list[dict[str, Any]],
+        idempotency_key: str | None = None,
+        **kwargs: Any,
+    ) -> DocumentBatchUploadResponse:
+        return self._client.upload_documents_batch(corpus_id, documents, idempotency_key, **kwargs)
+
+    def upload_files_batch(
+        self,
+        corpus_id: str,
+        files: list[tuple[str, bytes]],
+        idempotency_key: str | None = None,
+        **kwargs: Any,
+    ) -> DocumentBatchUploadResponse:
+        return self._client.upload_files_batch(corpus_id, files, idempotency_key, **kwargs)
+
+    def upload_parallel(
+        self,
+        corpus_id: str,
+        file_paths: list[str],
+        **kwargs: Any,
+    ) -> list[DocumentCreateResponse]:
+        return self._client.upload_documents_parallel(corpus_id, file_paths, **kwargs)
+
+    def ingest_urls(
+        self,
+        corpus_id: str,
+        urls: list[dict[str, Any]],
+        idempotency_key: str | None = None,
+        **kwargs: Any,
+    ) -> DocumentUrlIngestResponse:
+        return self._client.ingest_urls(corpus_id, urls, idempotency_key, **kwargs)
+
+    def ingest_manifest(
+        self,
+        corpus_id: str,
+        manifest_uri: str,
+        max_documents: int | None = None,
+        idempotency_key: str | None = None,
+        **kwargs: Any,
+    ) -> DocumentManifestIngestResponse:
+        return self._client.ingest_manifest(
+            corpus_id, manifest_uri, max_documents, idempotency_key, **kwargs
+        )
+
+    def list(self, corpus_id: str, **kwargs: Any) -> Page[dict[str, Any]]:
+        return self._client.list_documents(corpus_id, **kwargs)
+
+    def iter(self, corpus_id: str, **kwargs: Any) -> SyncPager[dict[str, Any]]:
+        return self._client.iter_documents(corpus_id, **kwargs)
+
+    def get(self, doc_id: str) -> DocumentDetailResponse:
+        return self._client.get_document(doc_id)
+
+    def update_metadata(self, doc_id: str, metadata: dict[str, Any]) -> dict[str, Any]:
+        return self._client.update_document_metadata(doc_id, metadata)
+
+    def delete(
+        self, corpus_id: str, doc_id: str, *, confirm: bool = False, reindex: bool = False
+    ) -> DocumentDeleteResponse:
+        return self._client.delete_document(corpus_id, doc_id, confirm=confirm, reindex=reindex)
+
+    def list_chunks(
+        self, corpus_id: str, limit: int = 100, offset: int = 0
+    ) -> Page[dict[str, Any]]:
+        return self._client.list_chunks(corpus_id, limit=limit, offset=offset)
+
+    def iter_chunks(self, corpus_id: str, *, limit: int = 100) -> SyncPager[dict[str, Any]]:
+        return self._client.iter_chunks(corpus_id, limit=limit)
+
+
+# ------------------------------------------------------------------
+# Corpora
+# ------------------------------------------------------------------
+
+
+class CorporaNamespace(_Namespace):
+    """Corpus operations: ``client.corpora.*``"""
+
+    def create(self, project_id: str, name: str, description: str | None = None) -> CorpusResponse:
+        return self._client.create_corpus(project_id, name, description)
+
+    def list(self, limit: int = 100, offset: int = 0) -> Page[dict[str, Any]]:
+        return self._client.list_corpora(limit=limit, offset=offset)
+
+    def iter(self, *, limit: int = 100) -> SyncPager[dict[str, Any]]:
+        return self._client.iter_corpora(limit=limit)
+
+    def get(self, corpus_id: str) -> CorpusResponse:
+        return self._client.get_corpus(corpus_id)
+
+    def status(self, corpus_id: str) -> CorpusStatusResponse:
+        return self._client.get_corpus_status(corpus_id)
+
+    def update(self, corpus_id: str, **kwargs: Any) -> CorpusResponse:
+        return self._client.update_corpus(corpus_id, **kwargs)
+
+    def delete(
+        self, corpus_id: str, *, confirm: bool = False, force: bool = False
+    ) -> CorpusDeleteResponse:
+        return self._client.delete_corpus(corpus_id, confirm=confirm, force=force)
+
+    def list_models(
+        self, corpus_id: str, limit: int = 100, offset: int = 0
+    ) -> Page[dict[str, Any]]:
+        return self._client.list_corpus_models(corpus_id, limit=limit, offset=offset)
+
+    def iter_models(self, corpus_id: str, *, limit: int = 100) -> SyncPager[dict[str, Any]]:
+        return self._client.iter_corpus_models(corpus_id, limit=limit)
+
+
+# ------------------------------------------------------------------
+# Search
+# ------------------------------------------------------------------
+
+
+class SearchNamespace(_Namespace):
+    """Search operations: ``client.search_ns.*``"""
+
+    def query(self, corpus_id: str, query: str, **kwargs: Any) -> SearchResponse:
+        return self._client.search(corpus_id, query, **kwargs)
+
+    def batch(self, corpus_id: str, queries: list[str], **kwargs: Any) -> SearchBatchResponse:
+        return self._client.search_batch(corpus_id, queries, **kwargs)
+
+    def generate(self, corpus_id: str, query: str, **kwargs: Any) -> SearchGenerateResponse:
+        return self._client.search_generate(corpus_id, query, **kwargs)
+
+    def embeddings(
+        self, model: str, inputs: list[str], embed_type: str = "query"
+    ) -> EmbeddingsResponse:
+        return self._client.embeddings(model, inputs, embed_type)
+
+    def feedback(self, corpus_id: str, query: str, **kwargs: Any) -> FeedbackResponse:
+        return self._client.create_feedback(corpus_id, query, **kwargs)
+
+
+# ------------------------------------------------------------------
+# Models
+# ------------------------------------------------------------------
+
+
+class ModelsNamespace(_Namespace):
+    """Model operations: ``client.models_ns.*``"""
+
+    def list(self, limit: int = 100, offset: int = 0) -> Page[dict[str, Any]]:
+        return self._client.list_models(limit=limit, offset=offset)
+
+    def iter(self, *, limit: int = 100) -> SyncPager[dict[str, Any]]:
+        return self._client.iter_models(limit=limit)
+
+    def delete(
+        self, model_id: str, *, confirm: bool = False, force: bool = False
+    ) -> ModelDeleteResponse:
+        return self._client.delete_model(model_id, confirm=confirm, force=force)
+
+
+# ------------------------------------------------------------------
+# Jobs
+# ------------------------------------------------------------------
+
+
+class JobsNamespace(_Namespace):
+    """Job operations: ``client.jobs.*``"""
+
+    def get(self, job_id: str) -> JobResponse:
+        return self._client.get_job(job_id)
+
+    def list(self, **kwargs: Any) -> Page[dict[str, Any]]:
+        return self._client.list_jobs(**kwargs)
+
+    def iter(self, **kwargs: Any) -> SyncPager[dict[str, Any]]:
+        return self._client.iter_jobs(**kwargs)
+
+    def cancel(self, job_id: str) -> JobStatusResponse:
+        return self._client.cancel_job(job_id)
+
+    def retry(self, job_id: str) -> JobStatusResponse:
+        return self._client.retry_job(job_id)
+
+    def reconcile(self) -> ReconcileJobsResponse:
+        return self._client.reconcile_jobs()
+
+
+# ------------------------------------------------------------------
+# Training
+# ------------------------------------------------------------------
+
+
+class TrainingNamespace(_Namespace):
+    """Training operations: ``client.training_ns.*``"""
+
+    def build_data(self, corpus_id: str, idempotency_key: str | None = None) -> Any:
+        return self._client.build_training_data(corpus_id, idempotency_key)
+
+    def list_data(self, corpus_id: str, limit: int = 100, offset: int = 0) -> Page[dict[str, Any]]:
+        return self._client.list_training_data(corpus_id, limit=limit, offset=offset)
+
+    def iter_data(self, corpus_id: str, *, limit: int = 100) -> SyncPager[dict[str, Any]]:
+        return self._client.iter_training_data(corpus_id, limit=limit)
+
+    def list_runs(self, corpus_id: str, limit: int = 100, offset: int = 0) -> Page[dict[str, Any]]:
+        return self._client.list_tuning_runs(corpus_id, limit=limit, offset=offset)
+
+    def iter_runs(self, corpus_id: str, *, limit: int = 100) -> SyncPager[dict[str, Any]]:
+        return self._client.iter_tuning_runs(corpus_id, limit=limit)
+
+    def create_run(
+        self, corpus_id: str, idempotency_key: str | None = None, **kwargs: Any
+    ) -> TuningRunResponse:
+        return self._client.create_tuning_run(corpus_id, idempotency_key, **kwargs)
+
+    def build_and_start(
+        self, corpus_id: str, idempotency_key: str | None = None, **kwargs: Any
+    ) -> Any:
+        return self._client.build_and_start_tuning_run(corpus_id, idempotency_key, **kwargs)
+
+    def get_run(self, run_id: str) -> TuningRunDetailResponse:
+        return self._client.get_tuning_run(run_id)
+
+    def get_run_logs(self, run_id: str, tail: int = 200) -> TuningRunLogsResponse:
+        return self._client.get_tuning_run_logs(run_id, tail)
+
+    def cancel_run(self, run_id: str) -> Any:
+        return self._client.cancel_tuning_run(run_id)
+
+    def promote_run(self, run_id: str) -> Any:
+        return self._client.promote_tuning_run(run_id)
+
+    def get_eval(self, eval_id: str) -> Any:
+        return self._client.get_eval_run(eval_id)
+
+
+# ------------------------------------------------------------------
+# Deployments
+# ------------------------------------------------------------------
+
+
+class DeploymentsNamespace(_Namespace):
+    """Deployment operations: ``client.deployments.*``"""
+
+    def create(
+        self,
+        corpus_id: str,
+        model_id: str,
+        *,
+        traffic_pct: int = 100,
+        reindex: bool = True,
+    ) -> DeploymentResponse:
+        return self._client.create_deployment(
+            corpus_id, model_id, traffic_pct=traffic_pct, reindex=reindex
+        )
+
+    def list(self, corpus_id: str, limit: int = 100, offset: int = 0) -> Page[dict[str, Any]]:
+        return self._client.list_deployments(corpus_id, limit=limit, offset=offset)
+
+    def iter(self, corpus_id: str, *, limit: int = 100) -> SyncPager[dict[str, Any]]:
+        return self._client.iter_deployments(corpus_id, limit=limit)
+
+
+# ------------------------------------------------------------------
+# Auth
+# ------------------------------------------------------------------
+
+
+class AuthNamespace(_Namespace):
+    """Auth operations: ``client.auth.*``"""
+
+    def create_api_key(
+        self,
+        org_id: str,
+        name: str,
+        scopes: dict[str, Any] | None = None,
+    ) -> ApiKeyCreateResponse:
+        return self._client.create_api_key(org_id, name, scopes)
+
+    def list_api_keys(self) -> ApiKeyListResponse:
+        return self._client.list_api_keys()
+
+    def revoke_api_key(self, key_id: str) -> ApiKeyRevokeResponse:
+        return self._client.revoke_api_key(key_id)
+
+    def rotate_api_key(self, key_id: str) -> ApiKeyRotateResponse:
+        return self._client.rotate_api_key(key_id)
+
+    def whoami(self) -> WhoAmIResponse:
+        return self._client.get_whoami()

sdk/resources/__init__.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from .a2a import A2AMixin
+from .agents import AgentsMixin
+from .audit import AuditMixin
+from .auth import AuthMixin
+from .console import ConsoleMixin
+from .corpora import CorporaMixin
+from .deployments import DeploymentsMixin
+from .documents import DocumentsMixin
+from .feeds import FeedsMixin
+from .indexes import IndexesMixin
+from .jobs import JobsMixin
+from .metadata import MetadataMixin
+from .models import ModelsMixin
+from .onboarding import OnboardingMixin
+from .orgs import OrgsMixin
+from .pipelines import PipelinesMixin
+from .projects import ProjectsMixin
+from .search import SearchMixin
+from .training import TrainingMixin
+from .usage import UsageMixin
+
+__all__ = [
+    "A2AMixin",
+    "AgentsMixin",
+    "AuditMixin",
+    "AuthMixin",
+    "ConsoleMixin",
+    "CorporaMixin",
+    "DeploymentsMixin",
+    "DocumentsMixin",
+    "FeedsMixin",
+    "IndexesMixin",
+    "JobsMixin",
+    "MetadataMixin",
+    "ModelsMixin",
+    "OnboardingMixin",
+    "OrgsMixin",
+    "PipelinesMixin",
+    "ProjectsMixin",
+    "SearchMixin",
+    "TrainingMixin",
+    "UsageMixin",
+]

sdk/resources/_mixin_base.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from sdk._paging import Page, SyncPager
+
+
+@runtime_checkable
+class RequesterMixin(Protocol):
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any: ...
+
+    def _maybe_validate(self, data: Any, model_name: str) -> Any: ...
+
+    @staticmethod
+    def _idempotency_headers(idempotency_key: str | None) -> dict[str, str]: ...
+
+    def _wait_for_job(
+        self, job_id: str, *, poll_s: int = 5, timeout_s: float | None = None
+    ) -> dict[str, Any]: ...
+
+    def _list_page(
+        self,
+        method: str,
+        path: str,
+        *,
+        items_key: str,
+        params: dict[str, Any] | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> Page[dict[str, Any]]: ...
+
+    def _paginate(
+        self,
+        method: str,
+        path: str,
+        *,
+        items_key: str,
+        params: dict[str, Any] | None = None,
+        limit: int = 100,
+    ) -> SyncPager[dict[str, Any]]: ...