knowledge2 0.4.1__tar.gz → 0.5.0__tar.gz

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.1 → knowledge2-0.5.0}/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the SDK version string."""
 
-__version__ = "0.4.1"
+__version__ = "0.5.0"

{knowledge2-0.4.1 → knowledge2-0.5.0}/async_client.py

@@ -31,19 +31,17 @@ from sdk.async_resources import (
     AsyncAuthMixin,
     AsyncConsoleMixin,
     AsyncCorporaMixin,
-    AsyncDeploymentsMixin,
     AsyncDocumentsMixin,
     AsyncFeedsMixin,
+    AsyncGenerationModelsMixin,
     AsyncIndexesMixin,
     AsyncJobsMixin,
     AsyncMetadataMixin,
-    AsyncModelsMixin,
     AsyncOnboardingMixin,
     AsyncOrgsMixin,
     AsyncPipelinesMixin,
     AsyncProjectsMixin,
     AsyncSearchMixin,
-    AsyncTrainingMixin,
     AsyncUsageMixin,
 )
 
@@ -61,13 +59,10 @@ class AsyncKnowledge2(
     AsyncAuthMixin,
     AsyncProjectsMixin,
     AsyncCorporaMixin,
-    AsyncModelsMixin,
     AsyncDocumentsMixin,
     AsyncIndexesMixin,
     AsyncSearchMixin,
     AsyncMetadataMixin,
-    AsyncTrainingMixin,
-    AsyncDeploymentsMixin,
     AsyncJobsMixin,
     AsyncAuditMixin,
     AsyncUsageMixin,
@@ -75,6 +70,7 @@ class AsyncKnowledge2(
     AsyncOnboardingMixin,
     AsyncAgentsMixin,
     AsyncFeedsMixin,
+    AsyncGenerationModelsMixin,
     AsyncPipelinesMixin,
     AsyncA2AMixin,
 ):

{knowledge2-0.4.1 → knowledge2-0.5.0}/async_resources/__init__.py

@@ -6,19 +6,17 @@ from .audit import AsyncAuditMixin
 from .auth import AsyncAuthMixin
 from .console import AsyncConsoleMixin
 from .corpora import AsyncCorporaMixin
-from .deployments import AsyncDeploymentsMixin
 from .documents import AsyncDocumentsMixin
 from .feeds import AsyncFeedsMixin
+from .generation_models import AsyncGenerationModelsMixin
 from .indexes import AsyncIndexesMixin
 from .jobs import AsyncJobsMixin
 from .metadata import AsyncMetadataMixin
-from .models import AsyncModelsMixin
 from .onboarding import AsyncOnboardingMixin
 from .orgs import AsyncOrgsMixin
 from .pipelines import AsyncPipelinesMixin
 from .projects import AsyncProjectsMixin
 from .search import AsyncSearchMixin
-from .training import AsyncTrainingMixin
 from .usage import AsyncUsageMixin
 
 __all__ = [
@@ -28,18 +26,16 @@ __all__ = [
     "AsyncAuthMixin",
     "AsyncConsoleMixin",
     "AsyncCorporaMixin",
-    "AsyncDeploymentsMixin",
     "AsyncDocumentsMixin",
     "AsyncFeedsMixin",
+    "AsyncGenerationModelsMixin",
     "AsyncIndexesMixin",
     "AsyncJobsMixin",
     "AsyncMetadataMixin",
-    "AsyncModelsMixin",
     "AsyncOnboardingMixin",
     "AsyncOrgsMixin",
     "AsyncPipelinesMixin",
     "AsyncProjectsMixin",
     "AsyncSearchMixin",
-    "AsyncTrainingMixin",
     "AsyncUsageMixin",
 ]

{knowledge2-0.4.1 → knowledge2-0.5.0}/async_resources/console.py

@@ -145,7 +145,6 @@ class AsyncConsoleMixin(AsyncRequesterMixin):
         project_id: str,
         *,
         name: str | None = None,
-        graph_rag_policy: dict[str, Any] | None = None,
         request_options: RequestOptions | None = None,
     ) -> ConsoleProjectItem:
         """Update a console project's settings.
@@ -153,7 +152,6 @@ class AsyncConsoleMixin(AsyncRequesterMixin):
         Args:
             project_id: Unique identifier of the project to update.
             name: New display name for the project.
-            graph_rag_policy: Updated GraphRAG policy configuration.
 
         Returns:
             The updated project information.
@@ -166,8 +164,6 @@ class AsyncConsoleMixin(AsyncRequesterMixin):
         payload: dict[str, Any] = {}
         if name is not None:
             payload["name"] = name
-        if graph_rag_policy is not None:
-            payload["graph_rag_policy"] = graph_rag_policy
         data = await self._request(
             "PATCH",
             f"/v1/console/projects/{project_id}",

{knowledge2-0.4.1 → knowledge2-0.5.0}/async_resources/corpora.py

@@ -146,7 +146,6 @@ class AsyncCorporaMixin(AsyncRequesterMixin):
         name: str | None = None,
         description: str | None = None,
         chunking_config: dict[str, Any] | None = None,
-        graph_rag_policy: dict[str, Any] | None = None,
         request_options: RequestOptions | None = None,
     ) -> CorpusResponse:
         """Update corpus settings.
@@ -157,8 +156,6 @@ class AsyncCorporaMixin(AsyncRequesterMixin):
             description: New description for the corpus.  Pass an empty
                 string to clear an existing description.
             chunking_config: Default chunking configuration for documents in this corpus.
-            graph_rag_policy: Optional corpus-level GraphRAG defaults that override
-                project-level settings when present.
 
         Returns:
             Updated corpus response
@@ -171,8 +168,6 @@ class AsyncCorporaMixin(AsyncRequesterMixin):
             payload["description"] = description
         if chunking_config is not None:
             payload["chunking_config"] = chunking_config
-        if graph_rag_policy is not None:
-            payload["graph_rag_policy"] = graph_rag_policy
         data = await self._request(
             "PATCH", f"/v1/corpora/{corpus_id}", json=payload, request_options=request_options
         )
@@ -218,60 +213,3 @@ class AsyncCorporaMixin(AsyncRequesterMixin):
             request_options=request_options,
         )
         return self._maybe_validate(data, "CorpusDeleteResponse")
-
-    async def list_corpus_models(
-        self,
-        corpus_id: str,
-        limit: int = 100,
-        offset: int = 0,
-        request_options: RequestOptions | None = None,
-    ) -> Page[dict[str, Any]]:
-        """List models associated with a corpus.
-
-        Args:
-            corpus_id: Unique identifier of the corpus.
-            limit: Maximum number of models to return per page.
-            offset: Number of models to skip for pagination.
-
-        Returns:
-            A Page containing model records for the corpus with pagination metadata.
-
-        Raises:
-            NotFoundError: If the corpus does not exist.
-            Knowledge2Error: If the API request fails.
-        """
-        corpus_id = require_str(corpus_id, "corpus_id")
-        return await self._list_page(
-            "GET",
-            f"/v1/corpora/{corpus_id}/models",
-            items_key="models",
-            limit=limit,
-            offset=offset,
-        )
-
-    def iter_corpus_models(
-        self,
-        corpus_id: str,
-        *,
-        limit: int = 100,
-        request_options: RequestOptions | None = None,
-    ) -> AsyncPager[dict[str, Any]]:
-        """Lazily paginate corpus models, yielding individual model items.
-
-        Args:
-            corpus_id: Unique identifier of the corpus.
-            limit: Page size used for each underlying API request.
-
-        Yields:
-            Individual model dicts.
-
-        Raises:
-            Knowledge2Error: If any underlying API request fails.
-        """
-        corpus_id = require_str(corpus_id, "corpus_id")
-        return self._paginate(
-            "GET",
-            f"/v1/corpora/{corpus_id}/models",
-            items_key="models",
-            limit=limit,
-        )

knowledge2-0.5.0/async_resources/generation_models.py

@@ -0,0 +1,29 @@
+"""Async generation model resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from sdk._request_options import RequestOptions
+from sdk.async_resources._mixin_base import AsyncRequesterMixin
+from sdk.types import GenerationModelsListResponse
+
+
+class AsyncGenerationModelsMixin(AsyncRequesterMixin):
+    async def list_generation_models(
+        self,
+        *,
+        request_options: RequestOptions | None = None,
+    ) -> GenerationModelsListResponse:
+        """List available generation models.
+
+        Returns:
+            A response containing the available generation models.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        data = await self._request(
+            "GET",
+            "/v1/models/generation",
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "GenerationModelsListResponse")