feat: sync HTTP types and auth with Node SDK 2.2.0

README.md

@@ -42,19 +42,20 @@ for page in result.page_chunks:
 ## Retrieval and document lifecycle
 
 New documents are published into a retrieval namespace. The server returns a
-stable `document_id` after the job is published. `client.jobs.create(...)`
-does not return a usable `document_id`; persist `job_result.document_id` if you
-need to update or archive the same document later.
+stable `document_id` on job create when it has a planned id, and on the
+completed `job_result` after publication.
 
 ```python
 job = client.jobs.create(
     source_type="url",
     source_url="https://example.com/manual.pdf",
     namespace="support-center",
+    document_metadata={"title": "Support manual"},
 )
 
+document_id = job.document_id
 job_result = client.jobs.wait(job.job_id)
-document_id = job_result.document_id
+document_id = document_id or job_result.document_id
 
 if document_id is None:
     raise RuntimeError("Expected document_id after successful publication.")
@@ -119,6 +120,11 @@ if chunks.chunks:
     print(chunk.chunk.content)
     print(chunk.chunk.metadata.get("page_nums"))  # Page citations.
     print(chunk.chunk.asset_url)  # Requested 7-day URL when available.
+    page_assets = chunk.chunk.metadata.get("pageAssets") or []
+    print(page_assets)
+
+source = client.documents.get_page_citation_source(document_id)
+print(source.url)
 
 client.documents.archive(document_id)
 ```
@@ -152,6 +158,12 @@ response = client.retrieval.query(
 
 While you can provide an `api_key` keyword argument, we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/) to add `KNOWHERE_API_KEY="sk_..."` to your `.env` file so that your API key is not stored in source control.
 
+Short-lived dashboard tokens can use `auth_token_provider` instead of a static key. If `api_key` is also set, the static key wins.
+
+```python
+client = knowhere.Knowhere(auth_token_provider=lambda: current_access_token())
+```
+
 ### Parse a local file
 
 ```python

docs/usage.md

@@ -42,7 +42,7 @@ uv add knowhere-python-sdk
 
 ## Authentication
 
-The SDK requires an API key. You can provide it in three ways (highest priority first):
+Provide a static API key or a short-lived token provider.
 
 1. Constructor argument:
 
@@ -76,6 +76,12 @@ load_dotenv()
 client = knowhere.Knowhere()
 ```
 
+4. Short-lived bearer token. If `api_key` is also set (or `KNOWHERE_API_KEY` is present), the static key wins.
+
+```python
+client = knowhere.Knowhere(auth_token_provider=lambda: current_access_token())
+```
+
 ## Quick Start
 
 ```python
@@ -145,6 +151,7 @@ result = client.parse(file=pdf_bytes, file_name="report.pdf")
 | `parsing_params` | `ParsingParams \| None` | `None` | Parsing configuration (see below). |
 | `webhook` | `WebhookConfig \| None` | `None` | Webhook for completion notification. |
 | `llm_config` | `LLMConfig \| None` | `None` | BYOK OpenAI-compatible credentials (flat root and/or `text` / `vision`). |
+| `document_metadata` | `dict \| None` | `None` | Display metadata copied onto the published document. Official `created_by_client` / `client_version` defaults are filled when omitted. |
 | `poll_interval` | `float` | `10.0` | Initial polling interval in seconds. |
 | `poll_timeout` | `float` | `1800.0` | Maximum time to wait for completion (30 min). |
 | `verify_checksum` | `bool` | `True` | Verify SHA-256 checksum of the downloaded ZIP. |
@@ -399,6 +406,7 @@ print(result.statistics)
 | `parsing_params` | `ParsingParams \| None` | `None` | Parsing configuration. |
 | `webhook` | `WebhookConfig \| None` | `None` | Webhook for completion notification. |
 | `llm_config` | `LLMConfig \| None` | `None` | BYOK OpenAI-compatible credentials (flat root and/or `text` / `vision`). |
+| `document_metadata` | `dict \| None` | `None` | Display metadata copied onto the published document. Official `created_by_client` / `client_version` defaults are filled when omitted. |
 
 Returns a `Job` object:
 
@@ -627,6 +635,9 @@ image_chunk = client.documents.get_chunk(
 )
 print(image_chunk.chunk.asset_url)
 
+source = client.documents.get_page_citation_source("doc_123")
+print(source.url, source.content_type)
+
 archived = client.documents.archive("doc_123")
 print(archived.status)  # "archived"
 ```

pyproject.toml

@@ -35,7 +35,7 @@ dev = [
     "pytest>=7.0.0,<9.0.0",
     "pytest-asyncio>=0.23.0",
     "respx>=0.21.0",
-    "ruff>=0.1.0",
+    "ruff>=0.15.0,<0.16.0",
     "mypy>=1.0.0",
     "coverage>=7.0.0",
 ]

src/knowhere/__init__.py

@@ -33,8 +33,12 @@
     ServiceUnavailableError,
     ValidationError,
 )
-from knowhere._types import PollProgressCallback, UploadProgressCallback
+from knowhere._types import AuthTokenProvider, PollProgressCallback, UploadProgressCallback
 from knowhere._version import __version__
+from knowhere.lib.document_metadata import (
+    PYTHON_SDK_DOCUMENT_METADATA_DEFAULTS,
+    merge_document_metadata_defaults,
+)
 from knowhere.types.document import (
     Document,
     DocumentChunk,
@@ -44,25 +48,23 @@
     DocumentChunkType,
     DocumentListPagination,
     DocumentListResponse,
+    DocumentPageCitationSource,
 )
 from knowhere.types.job import Job, JobError, JobProgress, JobResult
+from knowhere.types.page_citation import (
+    PAGE_CITATION_ASSETS_METADATA_KEY,
+    PageCitationAsset,
+    PageCitationAssetContentType,
+    PageCitationAssetSource,
+)
 from knowhere.types.params import (
+    DocumentMetadata,
     LLMConfig,
     LLMModelsConfig,
     LLMProviderConfig,
     ParsingParams,
     WebhookConfig,
 )
-from knowhere.types.retrieval import (
-    RetrievalChannel,
-    RetrievalChunkType,
-    RetrievalFilterMode,
-    RetrievalReferencedChunk,
-    RetrievalSectionExclusion,
-    RetrievalSource,
-    RetrievalQueryResponse,
-    RetrievalResult,
-)
 from knowhere.types.result import (
     BaseChunk,
     Checksum,
@@ -82,13 +84,25 @@
     TableFileInfo,
     TextChunk,
 )
+from knowhere.types.retrieval import (
+    RetrievalChannel,
+    RetrievalChunkType,
+    RetrievalFilterMode,
+    RetrievalQueryResponse,
+    RetrievalReferencedChunk,
+    RetrievalResult,
+    RetrievalSectionExclusion,
+    RetrievalSource,
+)
 
 __all__: list[str] = [
     # Clients
     "Knowhere",
     "AsyncKnowhere",
     # Version
     "__version__",
+    "PYTHON_SDK_DOCUMENT_METADATA_DEFAULTS",
+    "merge_document_metadata_defaults",
     # Exceptions
     "KnowhereError",
     "ValidationError",
@@ -123,6 +137,11 @@
     "DocumentChunkType",
     "DocumentListPagination",
     "DocumentListResponse",
+    "DocumentPageCitationSource",
+    "PageCitationAsset",
+    "PageCitationAssetContentType",
+    "PageCitationAssetSource",
+    "PAGE_CITATION_ASSETS_METADATA_KEY",
     # Retrieval types
     "RetrievalChannel",
     "RetrievalChunkType",
@@ -151,6 +170,7 @@
     "TableChunk",
     "Chunk",
     # Param types
+    "DocumentMetadata",
     "LLMConfig",
     "LLMModelsConfig",
     "LLMProviderConfig",
@@ -159,4 +179,5 @@
     # Callback types
     "UploadProgressCallback",
     "PollProgressCallback",
+    "AuthTokenProvider",
 ]