knowledge2 0.4.0__py3-none-any.whl

sdk/resources/models.py

@@ -0,0 +1,99 @@
+"""Model resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sdk._paging import Page, SyncPager
+from sdk._request_options import RequestOptions
+from sdk._validation import require_str
+from sdk.errors import ConfirmationRequiredError
+from sdk.resources._mixin_base import RequesterMixin
+from sdk.types import ModelDeleteResponse
+
+
+class ModelsMixin(RequesterMixin):
+    def list_models(
+        self,
+        limit: int = 100,
+        offset: int = 0,
+        request_options: RequestOptions | None = None,
+    ) -> Page[dict[str, Any]]:
+        """List models accessible to the current credentials.
+
+        Args:
+            limit: Maximum number of models to return per page.
+            offset: Number of models to skip for pagination.
+
+        Returns:
+            A Page containing model records with pagination metadata.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        return self._list_page("GET", "/v1/models", items_key="models", limit=limit, offset=offset)
+
+    def iter_models(
+        self,
+        *,
+        limit: int = 100,
+        request_options: RequestOptions | None = None,
+    ) -> SyncPager[dict[str, Any]]:
+        """Lazily paginate models, yielding individual model items.
+
+        Args:
+            limit: Page size used for each underlying API request.
+
+        Yields:
+            Individual model dicts.
+
+        Raises:
+            Knowledge2Error: If any underlying API request fails.
+        """
+        return self._paginate(
+            "GET",
+            "/v1/models",
+            items_key="models",
+            limit=limit,
+        )
+
+    def delete_model(
+        self,
+        model_id: str,
+        *,
+        confirm: bool = False,
+        force: bool = False,
+        request_options: RequestOptions | None = None,
+    ) -> ModelDeleteResponse:
+        """Delete a model and its associated artifacts.
+
+        This is an irreversible operation.  You must pass ``confirm=True``
+        to acknowledge this and proceed.
+
+        Args:
+            model_id: Unique identifier of the model to delete.
+            confirm: Safety guard — must be ``True`` to execute the
+                deletion.  Raises ``ConfirmationRequiredError`` when ``False``.
+            force: If ``True``, delete even if the model is currently
+                deployed.
+
+        Returns:
+            Confirmation of the deletion.
+
+        Raises:
+            ConfirmationRequiredError: If *confirm* is not ``True``.
+            NotFoundError: If the model does not exist.
+            ConflictError: If *force* is ``False`` and the model has
+                active deployments.
+            Knowledge2Error: If the API request fails.
+        """
+        model_id = require_str(model_id, "model_id")
+        if not confirm:
+            raise ConfirmationRequiredError("model", model_id)
+        data = self._request(
+            "DELETE",
+            f"/v1/models/{model_id}",
+            params={"force": force},
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "ModelDeleteResponse")

sdk/resources/onboarding.py

@@ -0,0 +1,542 @@
+"""SDK resource for dataset onboarding operations."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from sdk._paging import Page, SyncPager
+from sdk._request_options import RequestOptions
+from sdk._validation import require_str
+from sdk.resources._mixin_base import RequesterMixin
+from sdk.types import (
+    DatasetAnalysisDetails,
+    DatasetAnalysisRequest,
+    DatasetAnalysisResponse,
+    DocumentSummaryResponse,
+    EvaluationDetails,
+    EvaluationListResponse,
+    EvaluationReportResponse,
+    EvaluationRequest,
+    EvaluationResponse,
+    GoldLabelEntry,
+    GoldLabelsUploadResponse,
+    OnboardingStatusResponse,
+    SummarizationRequest,
+    SummarizationResponse,
+    SummarizationStatusResponse,
+    SyntheticQueryBatchDetails,
+    SyntheticQueryBatchListResponse,
+    SyntheticQueryBatchResponse,
+    SyntheticQueryGenerationRequest,
+)
+
+
+class OnboardingMixin(RequesterMixin):
+    """Mixin providing dataset onboarding operations."""
+
+    # =========================================================================
+    # Dataset Analysis
+    # =========================================================================
+
+    def start_analysis(
+        self,
+        corpus_id: str,
+        *,
+        description: str | None = None,
+        auto_bootstrap: bool = True,
+        bootstrap_num_samples: int | None = None,
+        queries_per_chunk: int | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> DatasetAnalysisResponse:
+        """Start the dataset analysis pipeline for a corpus.
+
+        Args:
+            corpus_id: ID of the corpus to analyze
+            description: Optional dataset description for analysis context
+            auto_bootstrap: Automatically bootstrap if no gold labels exist
+            bootstrap_num_samples: Override bootstrap sample count
+            queries_per_chunk: Override queries per chunk
+
+        Returns:
+            DatasetAnalysisResponse with analysis_id and job_id
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        payload: dict[str, Any] = {"auto_bootstrap": auto_bootstrap}
+        if description is not None:
+            payload["description"] = description
+        if bootstrap_num_samples is not None:
+            payload["bootstrap_num_samples"] = bootstrap_num_samples
+        if queries_per_chunk is not None:
+            payload["queries_per_chunk"] = queries_per_chunk
+
+        data = self._request(
+            "POST",
+            f"/v1/corpora/{corpus_id}/onboard:analyze",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "DatasetAnalysisResponse")
+
+    def get_onboarding_status(
+        self,
+        corpus_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> OnboardingStatusResponse:
+        """Get current onboarding status for a corpus.
+
+        Args:
+            corpus_id: ID of the corpus
+
+        Returns:
+            OnboardingStatusResponse with latest analysis and counts
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        data = self._request(
+            "GET", f"/v1/corpora/{corpus_id}/onboard/status", request_options=request_options
+        )
+        return self._maybe_validate(data, "OnboardingStatusResponse")
+
+    def get_analysis(
+        self,
+        corpus_id: str,
+        analysis_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> DatasetAnalysisDetails:
+        """Get detailed results of an analysis run.
+
+        Args:
+            corpus_id: ID of the corpus
+            analysis_id: ID of the analysis run
+
+        Returns:
+            DatasetAnalysisDetails with full analysis results
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        analysis_id = require_str(analysis_id, "analysis_id")
+        data = self._request(
+            "GET",
+            f"/v1/corpora/{corpus_id}/onboard/analysis/{analysis_id}",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "DatasetAnalysisDetails")
+
+    # =========================================================================
+    # Gold Labels
+    # =========================================================================
+
+    def upload_gold_labels(
+        self,
+        corpus_id: str,
+        labels: list[GoldLabelEntry],
+        *,
+        description: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> GoldLabelsUploadResponse:
+        """Upload gold labels for a corpus.
+
+        Args:
+            corpus_id: ID of the corpus
+            labels: List of gold label entries (query-chunk pairs)
+            description: Optional description of the labels source
+
+        Returns:
+            GoldLabelsUploadResponse with resolution results
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        payload: dict[str, Any] = {"labels": labels}
+        if description is not None:
+            payload["description"] = description
+
+        data = self._request(
+            "POST",
+            f"/v1/corpora/{corpus_id}/onboard:upload-labels",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "GoldLabelsUploadResponse")
+
+    def upload_gold_labels_file(
+        self,
+        corpus_id: str,
+        file_path: str | Path,
+        *,
+        description: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> GoldLabelsUploadResponse:
+        """Upload gold labels from a JSONL file.
+
+        Args:
+            corpus_id: ID of the corpus
+            file_path: Path to JSONL file with gold labels
+            description: Optional description of the labels source
+
+        Returns:
+            GoldLabelsUploadResponse with resolution results
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        import json
+
+        labels: list[GoldLabelEntry] = []
+        with open(file_path, "r") as f:
+            for line in f:
+                if line.strip():
+                    labels.append(json.loads(line))
+
+        return self.upload_gold_labels(
+            corpus_id, labels, description=description, request_options=request_options
+        )
+
+    def list_gold_labels(
+        self,
+        corpus_id: str,
+        *,
+        limit: int = 100,
+        offset: int = 0,
+        request_options: RequestOptions | None = None,
+    ) -> Page[dict[str, Any]]:
+        """List gold labels for a corpus.
+
+        Args:
+            corpus_id: ID of the corpus
+            limit: Maximum number of labels to return
+            offset: Offset for pagination
+
+        Returns:
+            A Page containing gold label entries with pagination metadata.
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        return self._list_page(
+            "GET",
+            f"/v1/corpora/{corpus_id}/gold-labels",
+            items_key="labels",
+            limit=limit,
+            offset=offset,
+        )
+
+    def iter_gold_labels(
+        self,
+        corpus_id: str,
+        *,
+        limit: int = 100,
+        request_options: RequestOptions | None = None,
+    ) -> SyncPager[dict[str, Any]]:
+        """Iterate over gold labels, automatically paginating."""
+        corpus_id = require_str(corpus_id, "corpus_id")
+        return self._paginate(
+            "GET",
+            f"/v1/corpora/{corpus_id}/gold-labels",
+            items_key="labels",
+            limit=limit,
+        )
+
+    # =========================================================================
+    # Synthetic Query Generation
+    # =========================================================================
+
+    def generate_synthetic_queries(
+        self,
+        corpus_id: str,
+        analysis_id: str,
+        *,
+        sample_size: int = 0,
+        queries_per_chunk: int = 3,
+        use_document_context: bool = True,
+        eval_sample_size: int | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> SyntheticQueryBatchResponse:
+        """Start synthetic query generation.
+
+        Args:
+            corpus_id: ID of the corpus
+            analysis_id: ID of the analysis run to use
+            sample_size: Chunks to sample (0 = automatic bounded sample)
+            queries_per_chunk: Queries to generate per chunk
+            use_document_context: Inject document summaries into prompts
+            eval_sample_size: Override eval sample size (None = use default)
+
+        Returns:
+            SyntheticQueryBatchResponse with batch_id and job_id
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        analysis_id = require_str(analysis_id, "analysis_id")
+        payload: dict[str, Any] = {
+            "analysis_id": analysis_id,
+            "sample_size": sample_size,
+            "queries_per_chunk": queries_per_chunk,
+            "use_document_context": use_document_context,
+        }
+        if eval_sample_size is not None:
+            payload["eval_sample_size"] = eval_sample_size
+
+        data = self._request(
+            "POST",
+            f"/v1/corpora/{corpus_id}/synthetic-queries:generate",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "SyntheticQueryBatchResponse")
+
+    def list_synthetic_batches(
+        self,
+        corpus_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> SyntheticQueryBatchListResponse:
+        """List synthetic query batches for a corpus.
+
+        Args:
+            corpus_id: ID of the corpus
+
+        Returns:
+            SyntheticQueryBatchListResponse with batches list
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        data = self._request(
+            "GET",
+            f"/v1/corpora/{corpus_id}/synthetic-queries/batches",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "SyntheticQueryBatchListResponse")
+
+    def get_synthetic_batch(
+        self,
+        corpus_id: str,
+        batch_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> SyntheticQueryBatchDetails:
+        """Get details of a synthetic query batch.
+
+        Args:
+            corpus_id: ID of the corpus
+            batch_id: ID of the batch
+
+        Returns:
+            SyntheticQueryBatchDetails with full batch info
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        batch_id = require_str(batch_id, "batch_id")
+        data = self._request(
+            "GET",
+            f"/v1/corpora/{corpus_id}/synthetic-queries/batches/{batch_id}",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "SyntheticQueryBatchDetails")
+
+    def download_synthetic_queries(
+        self,
+        corpus_id: str,
+        batch_id: str,
+        output_path: str | Path,
+        request_options: RequestOptions | None = None,
+    ) -> str:
+        """Download synthetic queries from a batch.
+
+        Args:
+            corpus_id: ID of the corpus
+            batch_id: ID of the batch
+            output_path: Path to save downloaded queries
+
+        Returns:
+            Path to the downloaded file
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        batch_id = require_str(batch_id, "batch_id")
+        # Get batch details to find artifact URI
+        batch = self.get_synthetic_batch(corpus_id, batch_id, request_options=request_options)
+
+        artifact_uri = (
+            batch.get("artifact_uri")
+            if isinstance(batch, dict)
+            else getattr(batch, "artifact_uri", None)
+        )
+        if not artifact_uri:
+            raise ValueError("Batch does not have an artifact URI")
+
+        return str(artifact_uri)
+
+    # =========================================================================
+    # Evaluation
+    # =========================================================================
+
+    def evaluate_synthetic_queries(
+        self,
+        corpus_id: str,
+        batch_id: str,
+        *,
+        sample_size: int | None = None,
+        generate_report: bool = True,
+        report_formats: list[str] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> EvaluationResponse:
+        """Start evaluation of synthetic queries.
+
+        Args:
+            corpus_id: ID of the corpus
+            batch_id: ID of the synthetic query batch
+            sample_size: Sample for evaluation (None or 0 = automatic bounded sample)
+            generate_report: Generate HTML/JSON report
+            report_formats: Report formats to generate
+
+        Returns:
+            EvaluationResponse with eval_id and job_id
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        batch_id = require_str(batch_id, "batch_id")
+        payload: dict[str, Any] = {
+            "batch_id": batch_id,
+            "generate_report": generate_report,
+        }
+        if sample_size is not None:
+            payload["sample_size"] = sample_size
+        if report_formats is not None:
+            payload["report_formats"] = report_formats
+
+        data = self._request(
+            "POST",
+            f"/v1/corpora/{corpus_id}/synthetic-queries:evaluate",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "EvaluationResponse")
+
+    def list_evaluations(
+        self,
+        corpus_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> EvaluationListResponse:
+        """List evaluations for a corpus.
+
+        Args:
+            corpus_id: ID of the corpus
+
+        Returns:
+            EvaluationListResponse with evaluations list
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        data = self._request(
+            "GET", f"/v1/corpora/{corpus_id}/evaluations", request_options=request_options
+        )
+        return self._maybe_validate(data, "EvaluationListResponse")
+
+    def get_evaluation(
+        self,
+        corpus_id: str,
+        eval_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> EvaluationDetails:
+        """Get details of an evaluation.
+
+        Args:
+            corpus_id: ID of the corpus
+            eval_id: ID of the evaluation
+
+        Returns:
+            EvaluationDetails with full evaluation results
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        eval_id = require_str(eval_id, "eval_id")
+        data = self._request(
+            "GET", f"/v1/corpora/{corpus_id}/evaluations/{eval_id}", request_options=request_options
+        )
+        return self._maybe_validate(data, "EvaluationDetails")
+
+    def get_evaluation_report(
+        self,
+        corpus_id: str,
+        eval_id: str,
+        *,
+        format: str = "json",
+        request_options: RequestOptions | None = None,
+    ) -> EvaluationReportResponse:
+        """Get evaluation report.
+
+        Args:
+            corpus_id: ID of the corpus
+            eval_id: ID of the evaluation
+            format: Report format ("json" or "html")
+
+        Returns:
+            EvaluationReportResponse with report URI and metrics
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        eval_id = require_str(eval_id, "eval_id")
+        data = self._request(
+            "GET",
+            f"/v1/corpora/{corpus_id}/evaluations/{eval_id}/report",
+            params={"format": format},
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "EvaluationReportResponse")
+
+    # =========================================================================
+    # Document Summarization
+    # =========================================================================
+
+    def summarize_documents(
+        self,
+        corpus_id: str,
+        *,
+        force_regenerate: bool = False,
+        request_options: RequestOptions | None = None,
+    ) -> SummarizationResponse:
+        """Start document summarization.
+
+        Args:
+            corpus_id: ID of the corpus
+            force_regenerate: Regenerate summaries for all documents
+
+        Returns:
+            SummarizationResponse with job_id and stats
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        payload: dict[str, Any] = {"force_regenerate": force_regenerate}
+        data = self._request(
+            "POST",
+            f"/v1/corpora/{corpus_id}/documents:summarize",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "SummarizationResponse")
+
+    def get_summarization_status(
+        self,
+        corpus_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> SummarizationStatusResponse:
+        """Get summarization status for a corpus.
+
+        Args:
+            corpus_id: ID of the corpus
+
+        Returns:
+            SummarizationStatusResponse with coverage stats
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        data = self._request(
+            "GET", f"/v1/corpora/{corpus_id}/summaries/status", request_options=request_options
+        )
+        return self._maybe_validate(data, "SummarizationStatusResponse")
+
+    def get_document_summary(
+        self,
+        corpus_id: str,
+        doc_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> DocumentSummaryResponse:
+        """Get summary for a specific document.
+
+        Args:
+            corpus_id: ID of the corpus
+            doc_id: ID of the document
+
+        Returns:
+            DocumentSummaryResponse with summary and entities
+        """
+        corpus_id = require_str(corpus_id, "corpus_id")
+        doc_id = require_str(doc_id, "doc_id")
+        data = self._request(
+            "GET",
+            f"/v1/corpora/{corpus_id}/documents/{doc_id}/summary",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "DocumentSummaryResponse")

sdk/resources/orgs.py

@@ -0,0 +1,35 @@
+"""Organisation 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 OrgResponse
+
+
+class OrgsMixin(RequesterMixin):
+    def create_org(
+        self,
+        name: str,
+        contact_email: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> OrgResponse:
+        """Create a new organisation.
+
+        Args:
+            name: Display name for the organisation.
+            contact_email: Optional contact email address for the org.
+
+        Returns:
+            The newly created organisation record.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        payload: dict[str, Any] = {"name": name}
+        if contact_email is not None:
+            payload["contact_email"] = contact_email
+        data = self._request("POST", "/v1/orgs", json=payload, request_options=request_options)
+        return self._maybe_validate(data, "OrgResponse")