knowledge2 0.4.0__py3-none-any.whl

sdk/errors.py

@@ -0,0 +1,178 @@
+"""Knowledge2 SDK exception hierarchy.
+
+All SDK exceptions inherit from :class:`Knowledge2Error`, so callers can
+use ``except Knowledge2Error`` as a catch-all.
+
+Hierarchy::
+
+    Knowledge2Error (base)
+    ├── APIError (HTTP errors from the API)
+    │   ├── BadRequestError (400)
+    │   ├── AuthenticationError (401)
+    │   ├── PermissionDeniedError (403)
+    │   ├── NotFoundError (404)
+    │   ├── ConflictError (409)
+    │   ├── ValidationError (422)
+    │   ├── RateLimitError (429)
+    │   └── ServerError (500, 502, 503, 504)
+    ├── APIConnectionError (network / DNS failures)
+    ├── APITimeoutError (request timeout)
+    └── ConfirmationRequiredError (client-side deletion guard)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class Knowledge2Error(Exception):
+    """Base exception for all Knowledge2 SDK errors."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+    @property
+    def retryable(self) -> bool:
+        """Whether the operation that caused this error can be retried."""
+        return False
+
+
+class APIError(Knowledge2Error):
+    """Error returned by the Knowledge2 API (HTTP 4xx / 5xx)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: str | None = None,
+        details: Any = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.details = details
+        self.request_id = request_id
+
+
+class BadRequestError(APIError):
+    """HTTP 400 — the request was malformed or missing required fields."""
+
+    @property
+    def retryable(self) -> bool:
+        return False
+
+
+class AuthenticationError(APIError):
+    """HTTP 401 — invalid or missing API key / bearer token."""
+
+    @property
+    def retryable(self) -> bool:
+        return False
+
+
+class PermissionDeniedError(APIError):
+    """HTTP 403 — the API key lacks the required scopes, or the requested feature is not enabled for the organization."""
+
+    @property
+    def retryable(self) -> bool:
+        return False
+
+
+class NotFoundError(APIError):
+    """HTTP 404 — the requested resource does not exist."""
+
+    @property
+    def retryable(self) -> bool:
+        return False
+
+
+class ConflictError(APIError):
+    """HTTP 409 — resource conflict (e.g. duplicate idempotency key)."""
+
+    @property
+    def retryable(self) -> bool:
+        return False
+
+
+class ValidationError(APIError):
+    """HTTP 422 — request validation failed."""
+
+    @property
+    def retryable(self) -> bool:
+        return False
+
+
+class RateLimitError(APIError):
+    """HTTP 429 — too many requests.
+
+    The :attr:`retry_after` attribute contains the server-suggested
+    wait time in seconds (from the ``Retry-After`` header), or *None*
+    if the header was absent.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int = 429,
+        retry_after: float | None = None,
+        code: str | None = None,
+        details: Any = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            code=code,
+            details=details,
+            request_id=request_id,
+        )
+        self.retry_after = retry_after
+
+    @property
+    def retryable(self) -> bool:
+        return True
+
+
+class ServerError(APIError):
+    """HTTP 500 / 502 / 503 / 504 — server-side failure."""
+
+    @property
+    def retryable(self) -> bool:
+        return True
+
+
+class APIConnectionError(Knowledge2Error):
+    """Network connectivity failure (DNS, connection refused, etc.)."""
+
+    @property
+    def retryable(self) -> bool:
+        return True
+
+
+class APITimeoutError(Knowledge2Error):
+    """The request timed out."""
+
+    @property
+    def retryable(self) -> bool:
+        return True
+
+
+class ConfirmationRequiredError(Knowledge2Error):
+    """Raised when a destructive operation requires explicit confirmation.
+
+    Delete methods require ``confirm=True`` as a safety guard.
+    This exception is part of the :class:`Knowledge2Error` hierarchy,
+    so ``except Knowledge2Error`` catch-alls will handle it.
+    """
+
+    def __init__(self, resource_type: str, resource_id: str) -> None:
+        self.resource_type = resource_type
+        self.resource_id = resource_id
+        super().__init__(
+            f"{resource_type.capitalize()} {resource_id!r} deletion is irreversible. "
+            f"Pass confirm=True to proceed."
+        )

sdk/examples/auth_factory.py

@@ -0,0 +1,34 @@
+"""Bearer token factory example — dynamic auth for OAuth/OIDC workloads.
+
+Usage:
+    K2_API_HOST=http://localhost:8000 python -m sdk.examples.auth_factory
+"""
+
+import os
+
+
+def get_oauth_token() -> str:
+    """Simulate an OAuth token fetch (replace with your real provider)."""
+    # In production: call your OAuth provider here
+    return os.environ.get("K2_BEARER_TOKEN", "demo-token")
+
+
+def main() -> None:
+    from sdk import Knowledge2
+
+    client = Knowledge2(
+        api_host=os.environ.get("K2_API_HOST", "https://api.knowledge2.ai"),
+        bearer_token_factory=get_oauth_token,
+        token_cache_ttl=300,  # cache for 5 minutes
+    )
+
+    # Pre-flight check
+    if not client.is_authenticated():
+        print("No auth configured!")
+        return
+
+    print(f"Authenticated: {client.is_authenticated()}")
+
+
+if __name__ == "__main__":
+    main()

sdk/examples/batch_operations.py

@@ -0,0 +1,57 @@
+"""Batch workflow: upload multiple docs, build indexes with wait, batch search, iterate results."""
+
+from __future__ import annotations
+
+import os
+
+from sdk import Knowledge2, Knowledge2Error
+
+try:
+    api_key = os.environ.get("K2_API_KEY")
+    if not api_key:
+        raise SystemExit("K2_API_KEY is required")
+
+    client = Knowledge2(api_key=api_key)
+    corpus_id = os.environ.get("K2_CORPUS_ID", "corpus-123")
+
+    # Upload multiple documents with idempotency key
+    docs = [
+        {"source_uri": "doc://a", "raw_text": "Content A."},
+        {"source_uri": "doc://b", "raw_text": "Content B."},
+        {"source_uri": "doc://c", "raw_text": "Content C."},
+    ]
+    upload = client.upload_documents_batch(
+        corpus_id,
+        docs,
+        idempotency_key="batch-demo-abc123",
+        wait=True,
+    )
+    print("Upload job:", upload.get("job_id"))
+
+    # Build indexes with wait and idempotency
+    index_job = client.build_indexes(
+        corpus_id,
+        dense=True,
+        sparse=True,
+        mode="full",
+        idempotency_key="index-demo-abc123",
+        wait=True,
+    )
+    print("Index job:", index_job.get("job_id"))
+
+    # Batch search multiple queries
+    queries = ["What is A?", "What is B?", "What is C?"]
+    batch = client.search_batch(
+        corpus_id,
+        queries,
+        top_k=3,
+        return_config={"include_text": True},
+    )
+    for i, resp in enumerate(batch.get("responses", [])):
+        print(f"Query {i + 1}: {queries[i]}")
+        for r in resp.get("results", []):
+            print("  ", (r.get("text") or "")[:60])
+
+except Knowledge2Error as e:
+    print(f"API error: {e}")
+    raise

sdk/examples/document_upload.py

@@ -0,0 +1,56 @@
+"""Document upload: single file, batch raw_text, URL ingestion. Shows wait=True pattern."""
+
+from __future__ import annotations
+
+import os
+
+from sdk import Knowledge2, Knowledge2Error
+
+try:
+    api_key = os.environ.get("K2_API_KEY")
+    if not api_key:
+        raise SystemExit("K2_API_KEY is required")
+
+    client = Knowledge2(api_key=api_key)
+    corpus_id = os.environ.get("K2_CORPUS_ID", "corpus-123")
+
+    # Single upload via file_path
+    resp = client.upload_document(
+        corpus_id,
+        file_path="/path/to/doc.pdf",
+        source_uri="doc://my-file",
+        idempotency_key="upload-1",
+    )
+    print("Uploaded:", resp.get("id"))
+
+    # Batch upload raw_text list (wait=True blocks until job completes)
+    docs = [
+        {"source_uri": "doc://a", "raw_text": "First document content."},
+        {"source_uri": "doc://b", "raw_text": "Second document content."},
+    ]
+    batch_resp = client.upload_documents_batch(
+        corpus_id,
+        docs,
+        idempotency_key="batch-1",
+        wait=True,
+        poll_s=5,
+    )
+    print("Batch job:", batch_resp.get("job_id"))
+
+    # URL ingestion with wait=True
+    urls = [
+        {"url": "https://example.com/page1", "title": "Page 1"},
+        {"url": "https://example.com/page2", "title": "Page 2"},
+    ]
+    url_resp = client.ingest_urls(
+        corpus_id,
+        urls,
+        idempotency_key="urls-1",
+        wait=True,
+        poll_s=5,
+    )
+    print("URL ingest job:", url_resp.get("job_id"))
+
+except Knowledge2Error as e:
+    print(f"API error: {e}")
+    raise

sdk/examples/e2e_lifecycle.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from typing import Iterable
+
+from sdk import Knowledge2, Knowledge2Error
+from sdk.types.jobs import JobResponse
+from sdk.types.search import SearchResult
+from sdk.types.training import TuningRunDetailResponse
+
+TERMINAL_JOB_STATUSES = {"succeeded", "failed", "canceled"}
+TERMINAL_RUN_STATUSES = {"succeeded", "failed", "canceled"}
+
+
+def _wait_for_job(
+    client: Knowledge2,
+    job_id: str,
+    *,
+    poll_s: float = 5.0,
+    timeout_s: float = 900.0,
+) -> JobResponse:
+    deadline = time.time() + timeout_s
+    while True:
+        job = client.get_job(job_id)
+        status = job.get("status")
+        if status in TERMINAL_JOB_STATUSES:
+            return job
+        if time.time() >= deadline:
+            raise TimeoutError(f"Timed out waiting for job {job_id}")
+        time.sleep(poll_s)
+
+
+def _wait_for_tuning_run(
+    client: Knowledge2,
+    run_id: str,
+    *,
+    poll_s: float = 10.0,
+    timeout_s: float = 7200.0,
+) -> TuningRunDetailResponse:
+    deadline = time.time() + timeout_s
+    while True:
+        run = client.get_tuning_run(run_id)
+        status = run.get("status")
+        if status in TERMINAL_RUN_STATUSES:
+            return run
+        if time.time() >= deadline:
+            raise TimeoutError(f"Timed out waiting for tuning run {run_id}")
+        time.sleep(poll_s)
+
+
+def _print_hits(results: Iterable[SearchResult]) -> None:
+    for idx, result in enumerate(results, start=1):
+        text = (result.get("text") or "").strip().replace("\n", " ")
+        print(f"{idx:02d}. score={result.get('score'):.4f} text={text[:120]}")
+
+
+def main() -> None:
+    api_key = os.getenv("K2_API_KEY")
+    if not api_key:
+        raise SystemExit("K2_API_KEY is required")
+
+    client = Knowledge2(
+        api_host=os.getenv("K2_BASE_URL", "https://api.knowledge2.ai"),
+        api_key=api_key,
+    )
+    idempotency_suffix = os.getenv("K2_IDEMPOTENCY_SUFFIX", uuid.uuid4().hex[:8])
+
+    def _key(base: str) -> str:
+        return f"{base}-{idempotency_suffix}"
+
+    project_id = os.getenv("K2_PROJECT_ID")
+    if not project_id:
+        project = client.create_project("knowledge2-demo")
+        project_id = project["id"]
+
+    corpus = client.create_corpus(
+        project_id,
+        "knowledge2-demo-corpus",
+        description="Sample corpus for the Knowledge2 end-to-end lifecycle.",
+    )
+    corpus_id = corpus["id"]
+
+    docs = [
+        {
+            "source_uri": "doc://overview",
+            "raw_text": "Knowledge2 organizes knowledge into projects and corpora. Documents are chunked into passages that can be indexed for search. Stable source_uris let you update content without duplicates.",
+            "metadata": {"topic": "overview", "product": "knowledge2"},
+        },
+        {
+            "source_uri": "doc://ingestion",
+            "raw_text": "Batch ingestion accepts documents with source_uri, raw_text, and optional metadata. Use idempotency keys to prevent duplicate ingest jobs. Upload in batches to stay within API limits.",
+            "metadata": {"topic": "ingestion", "product": "knowledge2"},
+        },
+        {
+            "source_uri": "doc://indexing",
+            "raw_text": "Dense indexes capture semantic similarity while sparse indexes capture keyword matches. Building both enables hybrid retrieval. Rebuild indexes after large content updates.",
+            "metadata": {"topic": "indexing", "product": "knowledge2"},
+        },
+        {
+            "source_uri": "doc://hybrid-search",
+            "raw_text": "Hybrid retrieval blends dense and sparse scores using RRF or weighted fusion. Adjust dense_weight and sparse_weight to balance semantics vs exact terms. You can request scores and provenance in the response.",
+            "metadata": {"topic": "search", "product": "knowledge2"},
+        },
+        {
+            "source_uri": "doc://tuning",
+            "raw_text": "Tuning runs train a better embedding model from query-document pairs. Training data can be auto-built or uploaded as JSONL. Successful runs can be promoted to a deployable model.",
+            "metadata": {"topic": "tuning", "product": "knowledge2"},
+        },
+        {
+            "source_uri": "doc://deployments",
+            "raw_text": "Deployments attach a tuned model to a corpus and optionally trigger reindexing. Track the reindex job until it succeeds. Once complete, searches use the tuned model.",
+            "metadata": {"topic": "deployments", "product": "knowledge2"},
+        },
+        {
+            "source_uri": "doc://evaluation",
+            "raw_text": "Evaluation runs compute metrics like nDCG, recall, and MRR on labeled data. Compare baseline and tuned models before promotion. Keep eval sets representative of real queries.",
+            "metadata": {"topic": "evaluation", "product": "knowledge2"},
+        },
+        {
+            "source_uri": "doc://security",
+            "raw_text": "API keys authenticate requests and can be rotated without downtime. Admin tokens are required for org bootstrap and should be stored securely. Audit logs and usage endpoints help with governance.",
+            "metadata": {"topic": "security", "product": "knowledge2"},
+        },
+    ]
+    ingest = client.upload_documents_batch(
+        corpus_id,
+        docs,
+        idempotency_key=_key("demo-ingest-1"),
+        auto_index=False,
+        wait=False,
+    )
+    print("Ingest job:", ingest["job_id"])
+    _wait_for_job(client, ingest["job_id"])
+
+    index_job = client.build_indexes(
+        corpus_id,
+        dense=True,
+        sparse=True,
+        mode="full",
+        idempotency_key=_key("demo-index-1"),
+        wait=False,
+    )
+    print("Index build job:", index_job["job_id"])
+    _wait_for_job(client, index_job["job_id"])
+
+    baseline = client.search(
+        corpus_id,
+        "How does hybrid retrieval blend dense and sparse signals?",
+        top_k=5,
+        hybrid={
+            "enabled": True,
+            "fusion_mode": "rrf",
+            "rrf_k": 60,
+            "dense_weight": 0.6,
+            "sparse_weight": 0.4,
+        },
+        return_config={"include_text": True, "include_scores": True, "include_provenance": True},
+    )
+    print("Baseline hybrid results:")
+    _print_hits(baseline["results"])
+
+    training_build = client.build_training_data(
+        corpus_id,
+        idempotency_key=_key("demo-training-data-1"),
+    )
+    print("Training data build job:", training_build["job_id"])
+    _wait_for_job(client, training_build["job_id"])
+
+    tuning_run = client.create_tuning_run(
+        corpus_id,
+        idempotency_key=_key("demo-tuning-1"),
+    )
+
+    print("Tuning run:", tuning_run["run_id"])
+    run = _wait_for_tuning_run(client, tuning_run["run_id"])
+    if run.get("status") != "succeeded":
+        raise SystemExit(f"Tuning run failed with status {run.get('status')}")
+
+    try:
+        promoted = client.promote_tuning_run(tuning_run["run_id"])
+    except Knowledge2Error as exc:
+        raise SystemExit(f"Promotion failed: {exc}") from exc
+
+    model_id = promoted["model_id"]
+    deployment = client.create_deployment(corpus_id, model_id, reindex=True)
+    reindex_job_id = deployment.get("reindex_job_id")
+    if reindex_job_id:
+        print("Reindex job:", reindex_job_id)
+        _wait_for_job(client, reindex_job_id)
+
+    tuned = client.search(
+        corpus_id,
+        "Explain hybrid retrieval in Knowledge2.",
+        top_k=5,
+        hybrid={
+            "enabled": True,
+            "fusion_mode": "rrf",
+            "rrf_k": 60,
+            "dense_weight": 0.5,
+            "sparse_weight": 0.5,
+        },
+        return_config={"include_text": True, "include_scores": True, "include_provenance": True},
+    )
+    print("Tuned hybrid results:")
+    _print_hits(tuned["results"])
+
+    print("Eval runs will be generated automatically after tuning completes.")
+
+
+if __name__ == "__main__":
+    main()

sdk/examples/error_handling.py

@@ -0,0 +1,61 @@
+"""Error handling: catch specific errors, use retryable, configure max_retries."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from sdk import (
+    AuthenticationError,
+    Knowledge2,
+    Knowledge2Error,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+
+try:
+    api_key = os.environ.get("K2_API_KEY")
+    if not api_key:
+        raise SystemExit("K2_API_KEY is required")
+
+    # Client with custom max_retries (0 = disable auto-retry)
+    client = Knowledge2(
+        api_key=api_key,
+        max_retries=3,
+    )
+
+    # Pre-flight check
+    if not client.is_authenticated():
+        print("No credentials configured!")
+        sys.exit(1)
+
+    corpus_id = os.environ.get("K2_CORPUS_ID", "corpus-123")
+
+    try:
+        client.get_corpus("nonexistent-corpus-id")
+    except AuthenticationError as e:
+        print("Invalid API key:", e.message)
+    except NotFoundError as e:
+        print("Resource not found:", e.message)
+    except RateLimitError as e:
+        print("Rate limited. Retry after:", e.retry_after)
+        if e.retryable:
+            print("This error is retryable.")
+    except ServerError as e:
+        print("Server error:", e.message)
+        if e.retryable:
+            print("Consider retrying the request.")
+
+    # Example: check retryable before custom retry logic
+    try:
+        client.search(corpus_id, "test query")
+    except Knowledge2Error as e:
+        if e.retryable:
+            print("Transient error - safe to retry:", e.message)
+        else:
+            print("Non-retryable error:", e.message)
+
+except Knowledge2Error as e:
+    print(f"API error: {e}")
+    raise

sdk/examples/pagination.py

@@ -0,0 +1,64 @@
+"""Pagination: iter_documents vs list_documents manual pagination, iter with filters."""
+
+from __future__ import annotations
+
+import os
+
+from sdk import Knowledge2, Knowledge2Error
+
+try:
+    api_key = os.environ.get("K2_API_KEY")
+    if not api_key:
+        raise SystemExit("K2_API_KEY is required")
+
+    client = Knowledge2(api_key=api_key)
+    corpus_id = os.environ.get("K2_CORPUS_ID", "corpus-123")
+
+    # --- Page[T]: single-page results from list_* methods ---
+    page = client.list_documents(corpus_id, limit=20, offset=0)  # returns Page[T]
+
+    # Page attributes and protocols
+    print(f"Total across all pages: {page.total}")  # page.total
+    print(f"Items on this page:     {page.items}")  # page.items  (list[T])
+    print(f"Page length:            {len(page)}")  # len(page)
+    print(f"Page is truthy:         {bool(page)}")  # bool(page)
+
+    for doc in page:  # iterate over items on this page
+        print(doc.get("id"), doc.get("source_uri", ""))
+
+    # Manual pagination loop using Page[T]
+    offset = 0
+    limit = 20
+    while True:
+        page = client.list_documents(corpus_id, limit=limit, offset=offset)
+        if not page:
+            break
+        for doc in page:
+            print(doc.get("id"), doc.get("source_uri", ""))
+        offset += len(page)
+        if len(page) < limit:
+            break
+
+    # --- SyncPager[T]: auto-pagination from iter_* methods ---
+    # iter_documents returns a SyncPager that lazily fetches successive pages.
+    pager = client.iter_documents(corpus_id, limit=50)  # SyncPager[T]
+
+    for item in pager:
+        print(item.get("id"), item.get("source_uri", ""))
+
+    # iter_documents with filters
+    for item in client.iter_documents(
+        corpus_id,
+        limit=50,
+        status="indexed",
+        source="doc://",
+    ):
+        print(item.get("id"))
+
+    # Collect all items into a list
+    all_docs = list(client.iter_documents(corpus_id, limit=100))
+    print(f"Total documents: {len(all_docs)}")
+
+except Knowledge2Error as e:
+    print(f"API error: {e}")
+    raise