knowledge2 0.4.0__tar.gz → 0.5.0__tar.gz

{knowledge2-0.4.0 → knowledge2-0.5.0}/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to the Knowledge2 Python SDK will be documented in this file
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2026-04-03
+
+### Changed
+
+- Release automation hardening for the public SDK sync/tag/PyPI path. No SDK API surface changes.
+
 ## [0.3.0] - 2026-03-30
 
 ### Added

knowledge2-0.5.0/MANIFEST.in

@@ -0,0 +1,5 @@
+exclude AGENTS.md
+exclude specification.md
+recursive-exclude .claude *
+recursive-exclude .codex *
+recursive-exclude .skills *

knowledge2-0.5.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: knowledge2
+Version: 0.5.0
+Summary: Python SDK for the Knowledge2 retrieval platform
+Author-email: Knowledge2 <contact@knowledge2.ai>
+License: MIT
+Project-URL: Homepage, https://knowledge2.ai
+Project-URL: Documentation, https://knowledge2.ai/docs
+Project-URL: Repository, https://github.com/knowledge2-ai/knowledge2-python-sdk
+Project-URL: Changelog, https://github.com/knowledge2-ai/knowledge2-python-sdk/blob/main/CHANGELOG.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: config
+Requires-Dist: pydantic-settings>=2.0; extra == "config"
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == "pydantic"
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == "yaml"
+
+# Knowledge2 Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/knowledge2.svg)](https://pypi.org/project/knowledge2/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Python client for the Knowledge2 retrieval platform. The supported customer journey is:
+
+`create corpus -> ingest documents -> build indexes -> search -> optimize retrieval`
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install knowledge2
+pip install "knowledge2[config]"
+pip install "knowledge2[pydantic]"
+pip install "knowledge2[yaml]"
+```
+
+From source:
+
+```bash
+pip install -e .
+pip install -e ".[config]"
+pip install -e ".[pydantic]"
+pip install -e ".[yaml]"
+```
+
+## Surface Categories
+
+| Category | Surface |
+|---|---|
+| Core retrieval workflow | orgs, auth, projects, corpora, documents, indexes, search, jobs, metadata, onboarding, audit, usage, console, generation models |
+| Enterprise capabilities | agents, feeds, pipelines, A2A |
+
+The main docs and examples below focus on the core retrieval workflow.
+
+## Quick Start
+
+```python
+from sdk import Knowledge2
+
+client = Knowledge2(api_key="k2_...")
+
+project = client.create_project("My Project")
+corpus = client.create_corpus(project["id"], "My Corpus")
+
+client.upload_documents_batch(
+    corpus["id"],
+    [
+        {
+            "source_uri": "doc://overview",
+            "raw_text": "Knowledge2 builds dense and sparse indexes for hybrid retrieval.",
+            "metadata": {"topic": "overview"},
+        },
+        {
+            "source_uri": "doc://search",
+            "raw_text": "Hybrid retrieval combines semantic similarity with exact keyword matching.",
+            "metadata": {"topic": "search"},
+        },
+    ],
+    wait=True,
+    auto_index=False,
+)
+client.sync_indexes(corpus["id"], wait=True)
+
+results = client.search(
+    corpus["id"],
+    "what is hybrid retrieval",
+    top_k=3,
+    return_config={"include_text": True, "include_scores": True},
+)
+
+for hit in results["results"]:
+    print(hit["score"], hit.get("text", "")[:80])
+```
+
+## Improve Retrieval Quality
+
+```python
+profile = client.get_query_profile(corpus["id"])
+print(profile["example_queries"])
+
+job = client.optimize_indexes(
+    corpus["id"],
+    example_queries=[
+        "how does hybrid retrieval work",
+        "what is bm25 tuning",
+        "how does rrf combine dense and sparse search",
+    ],
+    query_count=25,
+    top_k=10,
+    metric="ndcg",
+    wait=False,
+)
+print(job["job_id"], job["job_type"])
+```
+
+## Examples
+
+- `sdk/examples/retrieval_quickstart.py`: minimal happy path from empty corpus to working hybrid search
+- `sdk/examples/e2e_lifecycle.py`: full retrieval-quality workflow with query profile inspection and `indexes:optimize`
+
+Run either example with:
+
+```bash
+export K2_BASE_URL=https://api.knowledge2.ai
+export K2_API_KEY=<api-key>
+python sdk/examples/retrieval_quickstart.py
+python sdk/examples/e2e_lifecycle.py
+```
+
+## Authentication
+
+| Method | Header | Typical use |
+|---|---|---|
+| API key | `X-API-Key` | primary programmatic access |
+| Bearer token | `Authorization: Bearer <token>` | console / Auth0 session |
+| Admin token | `X-Admin-Token` | bootstrap and admin operations |
+
+```python
+client = Knowledge2(api_key="k2_...")
+client = Knowledge2.from_env()
+client = Knowledge2(bearer_token="...")
+```
+
+## Configuration
+
+Important constructor knobs:
+
+- `api_host`: defaults to `https://api.knowledge2.ai`
+- `api_key`: API key for programmatic access
+- `org_id`: auto-detected from `GET /v1/auth/whoami` when omitted
+- `timeout`: float or `ClientTimeouts`
+- `limits`: connection-pool settings via `ClientLimits`
+- `max_retries`: transient retry budget
+- `validate_responses`: enable Pydantic response validation
+- `http_client`: bring your own `httpx.Client`
+
+```python
+from sdk import ClientTimeouts, Knowledge2
+
+client = Knowledge2(
+    api_key="k2_...",
+    timeout=ClientTimeouts(connect=5, read=120, write=30, pool=10),
+)
+```
+
+## Namespaces
+
+The flat client API is canonical. Namespace helpers group the same methods without changing behavior:
+
+- `client.documents.*`
+- `client.corpora.*`
+- `client.search_ns.*`
+- `client.jobs.*`
+- `client.auth.*`
+
+## Framework Integrations
+
+The SDK ships LangChain and LlamaIndex integration modules in-package. Install the framework dependency separately, then import the adapter:
+
+```python
+from sdk.integrations.langchain import K2LangChainRetriever
+from sdk.integrations.llamaindex import K2LlamaIndexRetriever
+```
+
+## Enterprise Capabilities
+
+Agents, feeds, pipelines, and A2A are available for enterprise deployments. Keep the primary examples focused on the core retrieval flow.
+
+## Error Handling
+
+All SDK exceptions inherit from `Knowledge2Error`.
+
+```python
+from sdk.errors import Knowledge2Error, NotFoundError, RateLimitError
+
+try:
+    client.get_corpus("missing")
+except NotFoundError:
+    ...
+except RateLimitError as exc:
+    print(exc.retry_after)
+except Knowledge2Error as exc:
+    print(exc)
+```

knowledge2-0.5.0/README.md

@@ -0,0 +1,189 @@
+# Knowledge2 Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/knowledge2.svg)](https://pypi.org/project/knowledge2/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Python client for the Knowledge2 retrieval platform. The supported customer journey is:
+
+`create corpus -> ingest documents -> build indexes -> search -> optimize retrieval`
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install knowledge2
+pip install "knowledge2[config]"
+pip install "knowledge2[pydantic]"
+pip install "knowledge2[yaml]"
+```
+
+From source:
+
+```bash
+pip install -e .
+pip install -e ".[config]"
+pip install -e ".[pydantic]"
+pip install -e ".[yaml]"
+```
+
+## Surface Categories
+
+| Category | Surface |
+|---|---|
+| Core retrieval workflow | orgs, auth, projects, corpora, documents, indexes, search, jobs, metadata, onboarding, audit, usage, console, generation models |
+| Enterprise capabilities | agents, feeds, pipelines, A2A |
+
+The main docs and examples below focus on the core retrieval workflow.
+
+## Quick Start
+
+```python
+from sdk import Knowledge2
+
+client = Knowledge2(api_key="k2_...")
+
+project = client.create_project("My Project")
+corpus = client.create_corpus(project["id"], "My Corpus")
+
+client.upload_documents_batch(
+    corpus["id"],
+    [
+        {
+            "source_uri": "doc://overview",
+            "raw_text": "Knowledge2 builds dense and sparse indexes for hybrid retrieval.",
+            "metadata": {"topic": "overview"},
+        },
+        {
+            "source_uri": "doc://search",
+            "raw_text": "Hybrid retrieval combines semantic similarity with exact keyword matching.",
+            "metadata": {"topic": "search"},
+        },
+    ],
+    wait=True,
+    auto_index=False,
+)
+client.sync_indexes(corpus["id"], wait=True)
+
+results = client.search(
+    corpus["id"],
+    "what is hybrid retrieval",
+    top_k=3,
+    return_config={"include_text": True, "include_scores": True},
+)
+
+for hit in results["results"]:
+    print(hit["score"], hit.get("text", "")[:80])
+```
+
+## Improve Retrieval Quality
+
+```python
+profile = client.get_query_profile(corpus["id"])
+print(profile["example_queries"])
+
+job = client.optimize_indexes(
+    corpus["id"],
+    example_queries=[
+        "how does hybrid retrieval work",
+        "what is bm25 tuning",
+        "how does rrf combine dense and sparse search",
+    ],
+    query_count=25,
+    top_k=10,
+    metric="ndcg",
+    wait=False,
+)
+print(job["job_id"], job["job_type"])
+```
+
+## Examples
+
+- `sdk/examples/retrieval_quickstart.py`: minimal happy path from empty corpus to working hybrid search
+- `sdk/examples/e2e_lifecycle.py`: full retrieval-quality workflow with query profile inspection and `indexes:optimize`
+
+Run either example with:
+
+```bash
+export K2_BASE_URL=https://api.knowledge2.ai
+export K2_API_KEY=<api-key>
+python sdk/examples/retrieval_quickstart.py
+python sdk/examples/e2e_lifecycle.py
+```
+
+## Authentication
+
+| Method | Header | Typical use |
+|---|---|---|
+| API key | `X-API-Key` | primary programmatic access |
+| Bearer token | `Authorization: Bearer <token>` | console / Auth0 session |
+| Admin token | `X-Admin-Token` | bootstrap and admin operations |
+
+```python
+client = Knowledge2(api_key="k2_...")
+client = Knowledge2.from_env()
+client = Knowledge2(bearer_token="...")
+```
+
+## Configuration
+
+Important constructor knobs:
+
+- `api_host`: defaults to `https://api.knowledge2.ai`
+- `api_key`: API key for programmatic access
+- `org_id`: auto-detected from `GET /v1/auth/whoami` when omitted
+- `timeout`: float or `ClientTimeouts`
+- `limits`: connection-pool settings via `ClientLimits`
+- `max_retries`: transient retry budget
+- `validate_responses`: enable Pydantic response validation
+- `http_client`: bring your own `httpx.Client`
+
+```python
+from sdk import ClientTimeouts, Knowledge2
+
+client = Knowledge2(
+    api_key="k2_...",
+    timeout=ClientTimeouts(connect=5, read=120, write=30, pool=10),
+)
+```
+
+## Namespaces
+
+The flat client API is canonical. Namespace helpers group the same methods without changing behavior:
+
+- `client.documents.*`
+- `client.corpora.*`
+- `client.search_ns.*`
+- `client.jobs.*`
+- `client.auth.*`
+
+## Framework Integrations
+
+The SDK ships LangChain and LlamaIndex integration modules in-package. Install the framework dependency separately, then import the adapter:
+
+```python
+from sdk.integrations.langchain import K2LangChainRetriever
+from sdk.integrations.llamaindex import K2LlamaIndexRetriever
+```
+
+## Enterprise Capabilities
+
+Agents, feeds, pipelines, and A2A are available for enterprise deployments. Keep the primary examples focused on the core retrieval flow.
+
+## Error Handling
+
+All SDK exceptions inherit from `Knowledge2Error`.
+
+```python
+from sdk.errors import Knowledge2Error, NotFoundError, RateLimitError
+
+try:
+    client.get_corpus("missing")
+except NotFoundError:
+    ...
+except RateLimitError as exc:
+    print(exc.retry_after)
+except Knowledge2Error as exc:
+    print(exc)
+```

{knowledge2-0.4.0 → knowledge2-0.5.0}/__init__.py

@@ -18,9 +18,11 @@ from .errors import (
     BadRequestError,
     ConfirmationRequiredError,
     ConflictError,
+    FeatureNotEnabledError,
     Knowledge2Error,
     NotFoundError,
     PermissionDeniedError,
+    QuotaExceededError,
     RateLimitError,
     ServerError,
     ValidationError,
@@ -51,6 +53,7 @@ __all__ = [
     "ClientTimeouts",
     "ConfirmationRequiredError",
     "ConflictError",
+    "FeatureNotEnabledError",
     "K2Config",
     "Knowledge2",
     "Knowledge2Error",
@@ -59,6 +62,7 @@ __all__ = [
     "Page",
     "PermissionDeniedError",
     "PipelineBuilder",
+    "QuotaExceededError",
     "RateLimitError",
     "RawResponse",
     "RequestOptions",

{knowledge2-0.4.0 → knowledge2-0.5.0}/_async_base.py

@@ -285,6 +285,12 @@ class AsyncBaseClient:
                 response = await self._client.request(
                     method, path, headers=merged_headers, **kwargs
                 )
+            except RuntimeError as exc:
+                if "closed" in str(exc).lower():
+                    raise APIConnectionError(
+                        "Client has been closed. Create a new client instance."
+                    ) from exc
+                raise
             except asyncio.CancelledError:
                 raise
             except httpx.ConnectError as exc:

{knowledge2-0.4.0 → knowledge2-0.5.0}/_async_paging.py

@@ -24,17 +24,45 @@ class AsyncPager(Generic[T]):
         self._limit = limit
         self._offset = offset
         self._exhausted = False
+        self._first_page: Page[T] | None = None
+        self._first_page_consumed = False
+
+    async def get_total(self) -> int:
+        """Total number of items across all pages.
+
+        Lazily fetches the first page if not yet fetched.
+        """
+        if self._first_page is None:
+            items, total = await self._fetch_page(self._offset, self._limit)
+            self._first_page = Page(
+                items=items, total=total, offset=self._offset, limit=self._limit
+            )
+        return self._first_page.total
+
+    def _advance(self, page: Page[T]) -> None:
+        """Update offset or mark exhausted after consuming a page."""
+        if len(page.items) < self._limit or (
+            page.total > len(page.items) and self._offset + self._limit >= page.total
+        ):
+            self._exhausted = True
+        else:
+            self._offset += self._limit
 
     async def next_page(self) -> Page[T] | None:
         """Fetch the next page. Returns None when exhausted."""
         if self._exhausted:
             return None
+        # Return cached first page if it hasn't been consumed yet
+        if self._first_page is not None and not self._first_page_consumed:
+            self._first_page_consumed = True
+            self._advance(self._first_page)
+            return self._first_page
         items, total = await self._fetch_page(self._offset, self._limit)
         page = Page(items=items, total=total, offset=self._offset, limit=self._limit)
-        if len(items) < self._limit or (total > len(items) and self._offset + self._limit >= total):
-            self._exhausted = True
-        else:
-            self._offset += self._limit
+        if self._first_page is None:
+            self._first_page = page
+            self._first_page_consumed = True
+        self._advance(page)
         return page
 
     async def iter_pages(self) -> AsyncIterator[Page[T]]:

{knowledge2-0.4.0 → knowledge2-0.5.0}/_base.py

@@ -302,6 +302,12 @@ class BaseClient:
                     _redact_headers(merged_headers),
                 )
                 response = self._client.request(method, path, headers=merged_headers, **kwargs)
+            except RuntimeError as exc:
+                if "closed" in str(exc).lower():
+                    raise APIConnectionError(
+                        "Client has been closed. Create a new client instance."
+                    ) from exc
+                raise
             except httpx.ConnectError as exc:
                 last_error = APIConnectionError(f"Connection error: {exc}")
                 last_error.__cause__ = exc

{knowledge2-0.4.0 → knowledge2-0.5.0}/_paging.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any, Callable, Generic, Iterator, TypeVar
+from typing import Callable, Generic, Iterator, TypeVar
 
 T = TypeVar("T")
 
@@ -44,17 +44,46 @@ class SyncPager(Generic[T]):
         self._limit = limit
         self._offset = offset
         self._exhausted = False
+        self._first_page: Page[T] | None = None
+        self._first_page_consumed = False
+
+    @property
+    def total(self) -> int:
+        """Total number of items across all pages.
+
+        Lazily fetches the first page if not yet fetched.
+        """
+        if self._first_page is None:
+            items, total = self._fetch_page(self._offset, self._limit)
+            self._first_page = Page(
+                items=items, total=total, offset=self._offset, limit=self._limit
+            )
+        return self._first_page.total
+
+    def _advance(self, page: Page[T]) -> None:
+        """Update offset or mark exhausted after consuming a page."""
+        if len(page.items) < self._limit or (
+            page.total > len(page.items) and self._offset + self._limit >= page.total
+        ):
+            self._exhausted = True
+        else:
+            self._offset += self._limit
 
     def next_page(self) -> Page[T] | None:
         """Fetch the next page. Returns None when exhausted."""
         if self._exhausted:
             return None
+        # Return cached first page if it hasn't been consumed yet
+        if self._first_page is not None and not self._first_page_consumed:
+            self._first_page_consumed = True
+            self._advance(self._first_page)
+            return self._first_page
         items, total = self._fetch_page(self._offset, self._limit)
         page = Page(items=items, total=total, offset=self._offset, limit=self._limit)
-        if len(items) < self._limit or (total > len(items) and self._offset + self._limit >= total):
-            self._exhausted = True
-        else:
-            self._offset += self._limit
+        if self._first_page is None:
+            self._first_page = page
+            self._first_page_consumed = True
+        self._advance(page)
         return page
 
     def iter_pages(self) -> Iterator[Page[T]]:

{knowledge2-0.4.0 → knowledge2-0.5.0}/_preview.py

@@ -42,7 +42,9 @@ def preview_resource(cls: _T) -> _T:
                     warnings.warn(
                         f"{_name}() is a preview feature and may not be available "
                         f"in all environments. The underlying API requires a "
-                        f"feature flag to be enabled.",
+                        f"feature flag to be enabled."
+                        f" Visit https://console.knowledge2.ai/settings/support"
+                        f" to request access.",
                         RuntimeWarning,
                         stacklevel=2,
                     )
@@ -59,7 +61,9 @@ def preview_resource(cls: _T) -> _T:
                     warnings.warn(
                         f"{_name}() is a preview feature and may not be available "
                         f"in all environments. The underlying API requires a "
-                        f"feature flag to be enabled.",
+                        f"feature flag to be enabled."
+                        f" Visit https://console.knowledge2.ai/settings/support"
+                        f" to request access.",
                         RuntimeWarning,
                         stacklevel=2,
                     )

{knowledge2-0.4.0 → knowledge2-0.5.0}/_transport.py

@@ -18,9 +18,11 @@ from sdk.errors import (
     AuthenticationError,
     BadRequestError,
     ConflictError,
+    FeatureNotEnabledError,
     Knowledge2Error,
     NotFoundError,
     PermissionDeniedError,
+    QuotaExceededError,
     RateLimitError,
     ServerError,
     ValidationError,
@@ -41,6 +43,12 @@ _STATUS_ERROR_MAP: dict[int, type[APIError]] = {
     504: ServerError,
 }
 
+# Code-based overrides: (status_code, error_code) -> more specific error class.
+_CODE_ERROR_OVERRIDE: dict[tuple[int, str], type[APIError]] = {
+    (403, "feature_not_enabled"): FeatureNotEnabledError,
+    (429, "quota_exceeded"): QuotaExceededError,
+}
+
 
 def error_from_response(response: httpx.Response) -> APIError:
     """Parse an error response into the appropriate APIError subclass."""
@@ -69,17 +77,38 @@ def error_from_response(response: httpx.Response) -> APIError:
         message = f"{message} (request_id={request_id})"
 
     status = response.status_code
+
+    # Build human-readable message from Pydantic validation details for 422
+    if status == 422 and isinstance(details, list) and details:
+        parts = []
+        for item in details:
+            if isinstance(item, dict):
+                loc = item.get("loc", [])
+                field = " → ".join(str(s) for s in loc if s != "body") or "unknown"
+                msg = item.get("msg", "invalid")
+                parts.append(f"{field} — {msg}")
+        if parts:
+            message = "Validation failed: " + "; ".join(parts)
+            if request_id:
+                message = f"{message} (request_id={request_id})"
+
     error_cls = _STATUS_ERROR_MAP.get(status)
     if error_cls is None:
         error_cls = ServerError if 500 <= status < 600 else APIError
 
-    if error_cls is RateLimitError:
+    # Narrow to a more specific subclass when the error code matches.
+    if code:
+        override_key = (status, code)
+        if override_key in _CODE_ERROR_OVERRIDE:
+            error_cls = _CODE_ERROR_OVERRIDE[override_key]
+
+    if error_cls is not None and issubclass(error_cls, RateLimitError):
         retry_after_raw = response.headers.get("Retry-After")
         retry_after: float | None = None
         if retry_after_raw is not None:
             with contextlib.suppress(ValueError, TypeError):
                 retry_after = float(retry_after_raw)
-        return RateLimitError(
+        return error_cls(
             message,
             status_code=status,
             retry_after=retry_after,