knowhere-python-sdk 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

knowhere/__init__.py

@@ -22,6 +22,7 @@ from knowhere._exceptions import (
     ConflictError,
     GatewayTimeoutError,
     InternalServerError,
+    InvalidStateError,
     JobFailedError,
     KnowhereError,
     NotFoundError,
@@ -30,6 +31,7 @@ from knowhere._exceptions import (
     PollingTimeoutError,
     RateLimitError,
     ServiceUnavailableError,
+    ValidationError,
 )
 from knowhere._types import PollProgressCallback, UploadProgressCallback
 from knowhere._version import __version__
@@ -58,6 +60,8 @@ __all__: list[str] = [
     "__version__",
     # Exceptions
     "KnowhereError",
+    "ValidationError",
+    "InvalidStateError",
     "APIConnectionError",
     "APITimeoutError",
     "APIStatusError",

knowhere/_base_client.py

@@ -25,6 +25,7 @@ from knowhere._constants import (
 from knowhere._exceptions import (
     APIConnectionError,
     APITimeoutError,
+    ValidationError,
     makeStatusError,
 )
 from knowhere._logging import getLogger, redactSensitiveHeaders
@@ -35,17 +36,23 @@ T = TypeVar("T")
 
 _logger = getLogger()
 
-# Error codes that are safe to retry
-_RETRYABLE_ERROR_CODES: frozenset[str] = frozenset({
-    "rate_limit_exceeded",
-    "service_unavailable",
-    "gateway_timeout",
-    "internal_server_error",
-    "timeout",
+# Error codes that are always safe to retry (matches server ALWAYS_RETRYABLE_ERROR_CODES)
+_ALWAYS_RETRYABLE_ERROR_CODES: frozenset[str] = frozenset({
+    "ABORTED",            # 409 - Concurrency conflict
+    "UNAVAILABLE",        # 503 - Service temporarily down
+    "DEADLINE_EXCEEDED",  # 504 - Timeout
 })
 
-# Status codes that are safe to retry
-_RETRYABLE_STATUS_CODES: frozenset[int] = frozenset({408, 429, 500, 502, 503, 504})
+# RESOURCE_EXHAUSTED (429) is conditionally retryable:
+#   - Rate limit: details.retry_after present → RETRY
+#   - Quota exceeded: no retry_after → DO NOT RETRY
+_CONDITIONALLY_RETRYABLE_ERROR_CODE: str = "RESOURCE_EXHAUSTED"
+
+# HTTP status codes that are always safe to retry
+_ALWAYS_RETRYABLE_STATUS_CODES: frozenset[int] = frozenset({409, 502, 503, 504})
+
+# HTTP status code that is conditionally retryable (only with retry_after)
+_CONDITIONALLY_RETRYABLE_STATUS_CODE: int = 429
 
 
 class BaseClient:
@@ -71,7 +78,7 @@ class BaseClient:
         # Resolve: arg > env > default
         resolved_key: Optional[str] = api_key or os.environ.get(ENV_API_KEY)
         if not resolved_key:
-            raise ValueError(
+            raise ValidationError(
                 "An API key must be provided via the 'api_key' argument "
                 f"or the {ENV_API_KEY} environment variable."
             )
@@ -122,12 +129,68 @@ class BaseClient:
         self,
         status_code: int,
         error_code: Optional[str] = None,
-        details: Optional[Any] = None,
+        details: Optional[Dict[str, Any]] = None,
     ) -> bool:
-        """Decide whether a request should be retried."""
-        if error_code and error_code in _RETRYABLE_ERROR_CODES:
+        """Decide whether a request should be retried.
+
+        Follows server-side retry semantics:
+        - ABORTED, UNAVAILABLE, DEADLINE_EXCEEDED → always retry
+        - RESOURCE_EXHAUSTED (429) → retry only if details.retry_after present
+        - All other errors → never retry
+        """
+        if error_code:
+            if error_code in _ALWAYS_RETRYABLE_ERROR_CODES:
+                return True
+            if error_code == _CONDITIONALLY_RETRYABLE_ERROR_CODE:
+                return self._hasRetryAfter(details)
+            return False
+
+        # Fallback to status code when error_code is unavailable
+        if status_code in _ALWAYS_RETRYABLE_STATUS_CODES:
             return True
-        return status_code in _RETRYABLE_STATUS_CODES
+        if status_code == _CONDITIONALLY_RETRYABLE_STATUS_CODE:
+            return self._hasRetryAfter(details)
+        return False
+
+    @staticmethod
+    def _hasRetryAfter(details: Optional[Dict[str, Any]]) -> bool:
+        """Check if details contains a retry_after hint."""
+        if not isinstance(details, dict):
+            return False
+        retry_after: Any = details.get("retry_after")
+        return retry_after is not None
+
+    @staticmethod
+    def _extractRetryAfter(
+        error_body: Optional[Dict[str, Any]],
+        response: httpx.Response,
+    ) -> Optional[float]:
+        """Extract retry_after from the response body or Retry-After header.
+
+        The server puts retry_after in ``error.details.retry_after``.
+        Falls back to the HTTP ``Retry-After`` header.
+        """
+        # Prefer body: error.details.retry_after
+        if isinstance(error_body, dict):
+            err_obj: Any = error_body.get("error", error_body)
+            if isinstance(err_obj, dict):
+                details: Any = err_obj.get("details")
+                if isinstance(details, dict):
+                    raw: Any = details.get("retry_after")
+                    if raw is not None:
+                        try:
+                            return float(raw)
+                        except (ValueError, TypeError):
+                            pass
+
+        # Fallback: HTTP Retry-After header
+        header_raw: Optional[str] = response.headers.get("retry-after")
+        if header_raw is not None:
+            try:
+                return float(header_raw)
+            except (ValueError, TypeError):
+                pass
+        return None
 
     def _calculateRetryDelay(
         self,
@@ -257,24 +320,24 @@ class SyncAPIClient(BaseClient):
                 response
             )
             error_code: Optional[str] = None
+            error_details: Optional[Dict[str, Any]] = None
             if isinstance(error_body, dict):
                 err_obj: Any = error_body.get("error", error_body)
                 if isinstance(err_obj, dict):
                     error_code = err_obj.get("code")
+                    raw_details: Any = err_obj.get("details")
+                    if isinstance(raw_details, dict):
+                        error_details = raw_details
 
             if (
                 attempt < self.max_retries
-                and self._shouldRetry(response.status_code, error_code)
+                and self._shouldRetry(
+                    response.status_code, error_code, error_details
+                )
             ):
-                retry_after_raw: Optional[str] = response.headers.get(
-                    "retry-after"
+                retry_after_val: Optional[float] = self._extractRetryAfter(
+                    error_body, response
                 )
-                retry_after_val: Optional[float] = None
-                if retry_after_raw:
-                    try:
-                        retry_after_val = float(retry_after_raw)
-                    except (ValueError, TypeError):
-                        pass
                 delay = self._calculateRetryDelay(attempt, retry_after_val)
                 _logger.warning(
                     "Retryable error %d on attempt %d/%d, retrying in %.1fs",
@@ -404,22 +467,24 @@ class AsyncAPIClient(BaseClient):
 
             error_body: Optional[Dict[str, Any]] = self._parseErrorResponse(response)
             error_code: Optional[str] = None
+            error_details: Optional[Dict[str, Any]] = None
             if isinstance(error_body, dict):
                 err_obj: Any = error_body.get("error", error_body)
                 if isinstance(err_obj, dict):
                     error_code = err_obj.get("code")
+                    raw_details: Any = err_obj.get("details")
+                    if isinstance(raw_details, dict):
+                        error_details = raw_details
 
             if (
                 attempt < self.max_retries
-                and self._shouldRetry(response.status_code, error_code)
+                and self._shouldRetry(
+                    response.status_code, error_code, error_details
+                )
             ):
-                retry_after_raw: Optional[str] = response.headers.get("retry-after")
-                retry_after_val: Optional[float] = None
-                if retry_after_raw:
-                    try:
-                        retry_after_val = float(retry_after_raw)
-                    except (ValueError, TypeError):
-                        pass
+                retry_after_val: Optional[float] = self._extractRetryAfter(
+                    error_body, response
+                )
                 delay = self._calculateRetryDelay(attempt, retry_after_val)
                 _logger.warning(
                     "Retryable error %d on attempt %d/%d, retrying in %.1fs",

knowhere/_client.py

@@ -13,6 +13,7 @@ from typing import BinaryIO, Optional, Union, overload
 
 from knowhere._base_client import AsyncAPIClient, SyncAPIClient
 from knowhere._constants import DEFAULT_POLL_INTERVAL, DEFAULT_POLL_TIMEOUT
+from knowhere._exceptions import ValidationError
 from knowhere._logging import getLogger
 from knowhere._types import (
     PollProgressCallback,
@@ -94,9 +95,9 @@ class Knowhere(SyncAPIClient):
         Provide exactly one of *url* or *file*.
         """
         if url and file:
-            raise ValueError("Provide either 'url' or 'file', not both.")
+            raise ValidationError("Provide either 'url' or 'file', not both.")
         if not url and file is None:
-            raise ValueError("Provide either 'url' or 'file'.")
+            raise ValidationError("Provide either 'url' or 'file'.")
 
         # Determine source type and create job
         if url:
@@ -196,9 +197,9 @@ class AsyncKnowhere(AsyncAPIClient):
     ) -> ParseResult:
         """Parse a document end-to-end (async version)."""
         if url and file:
-            raise ValueError("Provide either 'url' or 'file', not both.")
+            raise ValidationError("Provide either 'url' or 'file', not both.")
         if not url and file is None:
-            raise ValueError("Provide either 'url' or 'file'.")
+            raise ValidationError("Provide either 'url' or 'file'.")
 
         if url:
             job: Job = await self.jobs.create(

knowhere/_constants.py

@@ -18,6 +18,7 @@ DEFAULT_POLL_INTERVAL: float = 10.0
 
 # Retry configuration
 DEFAULT_MAX_RETRIES: int = 5
+DEFAULT_UPLOAD_MAX_RETRIES: int = 2
 
 # Polling configuration
 MAX_POLL_INTERVAL: float = 30.0

knowhere/_exceptions.py

@@ -41,6 +41,19 @@ class APITimeoutError(APIConnectionError):
         super().__init__(message)
 
 
+# ---------------------------------------------------------------------------
+# Validation / state
+# ---------------------------------------------------------------------------
+
+
+class ValidationError(KnowhereError):
+    """Raised when the caller provides invalid arguments."""
+
+
+class InvalidStateError(KnowhereError):
+    """Raised when an object is in an unexpected state for the operation."""
+
+
 # ---------------------------------------------------------------------------
 # Polling / job errors
 # ---------------------------------------------------------------------------
@@ -161,9 +174,17 @@ class ConflictError(APIStatusError):
 
 
 class RateLimitError(APIStatusError):
-    """HTTP 429 — includes optional ``retry_after`` hint."""
+    """HTTP 429 — includes optional rate limit hints from the server.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying (``None`` for quota exceeded).
+        limit: Maximum allowed requests in the rate window.
+        period: Rate window unit (``"second"``, ``"minute"``, ``"hour"``, ``"day"``).
+    """
 
     retry_after: Optional[float]
+    limit: Optional[int]
+    period: Optional[str]
 
     def __init__(
         self,
@@ -176,6 +197,8 @@ class RateLimitError(APIStatusError):
         body: Optional[Any] = None,
         response: httpx.Response,
         retry_after: Optional[float] = None,
+        limit: Optional[int] = None,
+        period: Optional[str] = None,
     ) -> None:
         super().__init__(
             status_code,
@@ -187,6 +210,8 @@ class RateLimitError(APIStatusError):
             response=response,
         )
         self.retry_after = retry_after
+        self.limit = limit
+        self.period = period
 
 
 class InternalServerError(APIStatusError):
@@ -194,9 +219,17 @@ class InternalServerError(APIStatusError):
 
 
 class ServiceUnavailableError(APIStatusError):
-    """HTTP 502 / 503 — includes optional ``retry_after`` hint."""
+    """HTTP 502 / 503 — includes optional rate limit hints from the server.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying.
+        limit: Maximum allowed requests in the rate window (optional).
+        period: Rate window unit (optional).
+    """
 
     retry_after: Optional[float]
+    limit: Optional[int]
+    period: Optional[str]
 
     def __init__(
         self,
@@ -209,6 +242,8 @@ class ServiceUnavailableError(APIStatusError):
         body: Optional[Any] = None,
         response: httpx.Response,
         retry_after: Optional[float] = None,
+        limit: Optional[int] = None,
+        period: Optional[str] = None,
     ) -> None:
         super().__init__(
             status_code,
@@ -220,12 +255,22 @@ class ServiceUnavailableError(APIStatusError):
             response=response,
         )
         self.retry_after = retry_after
+        self.limit = limit
+        self.period = period
 
 
 class GatewayTimeoutError(APIStatusError):
-    """HTTP 504 — includes optional ``retry_after`` hint."""
+    """HTTP 504 — includes optional rate limit hints from the server.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying.
+        limit: Maximum allowed requests in the rate window (optional).
+        period: Rate window unit (optional).
+    """
 
     retry_after: Optional[float]
+    limit: Optional[int]
+    period: Optional[str]
 
     def __init__(
         self,
@@ -238,6 +283,8 @@ class GatewayTimeoutError(APIStatusError):
         body: Optional[Any] = None,
         response: httpx.Response,
         retry_after: Optional[float] = None,
+        limit: Optional[int] = None,
+        period: Optional[str] = None,
     ) -> None:
         super().__init__(
             status_code,
@@ -249,6 +296,8 @@ class GatewayTimeoutError(APIStatusError):
             response=response,
         )
         self.retry_after = retry_after
+        self.limit = limit
+        self.period = period
 
 
 # ---------------------------------------------------------------------------
@@ -298,14 +347,36 @@ def makeStatusError(
         status_code, APIStatusError
     )
 
-    # Extract retry_after for classes that support it
+    # Extract retry hints for classes that support them
+    # Prefer body: error.details.retry_after, fallback to HTTP header
     retry_after: Optional[float] = None
-    raw_retry: Optional[str] = response.headers.get("retry-after")
-    if raw_retry is not None:
-        try:
-            retry_after = float(raw_retry)
-        except (ValueError, TypeError):
-            retry_after = None
+    limit: Optional[int] = None
+    period: Optional[str] = None
+
+    if isinstance(details, dict):
+        raw_body_retry: Any = details.get("retry_after")
+        if raw_body_retry is not None:
+            try:
+                retry_after = float(raw_body_retry)
+            except (ValueError, TypeError):
+                pass
+        raw_limit: Any = details.get("limit")
+        if raw_limit is not None:
+            try:
+                limit = int(raw_limit)
+            except (ValueError, TypeError):
+                pass
+        raw_period: Any = details.get("period")
+        if isinstance(raw_period, str):
+            period = raw_period
+
+    if retry_after is None:
+        raw_header_retry: Optional[str] = response.headers.get("retry-after")
+        if raw_header_retry is not None:
+            try:
+                retry_after = float(raw_header_retry)
+            except (ValueError, TypeError):
+                pass
 
     common_kwargs: Dict[str, Any] = dict(
         code=code,
@@ -318,7 +389,11 @@ def makeStatusError(
 
     if exception_class in (RateLimitError, ServiceUnavailableError, GatewayTimeoutError):
         return exception_class(
-            status_code, **common_kwargs, retry_after=retry_after  # type: ignore[call-arg]
+            status_code,
+            **common_kwargs,
+            retry_after=retry_after,  # type: ignore[call-arg]
+            limit=limit,
+            period=period,
         )
 
     return exception_class(status_code, **common_kwargs)

knowhere/_version.py

@@ -1 +1 @@
-__version__ = "0.1.0"  # x-release-please-version
+__version__ = "0.2.0"  # x-release-please-version

knowhere/lib/result_parser.py

@@ -18,6 +18,7 @@ from knowhere.types.result import (
     ParseResult,
     TableChunk,
     TextChunk,
+    TextChunkTokens,
 )
 
 _logger = getLogger()
@@ -79,6 +80,38 @@ def _extractFilePath(raw: Dict[str, Any]) -> Optional[str]:
     return fallback
 
 
+def _normalizeTokenList(raw_tokens: List[Any]) -> List[str]:
+    """Return a string-only token list with empty values removed."""
+    normalized_tokens: List[str] = []
+    for raw_token in raw_tokens:
+        token_text: str = str(raw_token).strip()
+        if token_text:
+            normalized_tokens.append(token_text)
+    return normalized_tokens
+
+
+def _parseTextChunkTokens(
+    raw_tokens: Any,
+    *,
+    chunk_id: str,
+) -> Optional[TextChunkTokens]:
+    """Normalize text chunk tokens from the current backend payload."""
+    if raw_tokens is None:
+        return None
+    if isinstance(raw_tokens, bool):
+        raise KnowhereError(
+            f"Invalid tokens payload for text chunk '{chunk_id}': expected list[str], got bool."
+        )
+    if isinstance(raw_tokens, list):
+        return _normalizeTokenList(raw_tokens)
+
+    raise KnowhereError(
+        "Invalid tokens payload for text chunk "
+        f"'{chunk_id}': expected list[str], "
+        f"got {type(raw_tokens).__name__}."
+    )
+
+
 def _buildChunks(
     raw_chunks: List[Dict[str, Any]],
     zf: zipfile.ZipFile,
@@ -127,13 +160,15 @@ def _buildChunks(
             )
         else:
             metadata = raw.get("metadata", {})
+            chunk_id: str = raw.get("chunk_id", "")
+            raw_tokens: Any = metadata.get("tokens", raw.get("tokens"))
             chunk = TextChunk(
-                chunk_id=raw.get("chunk_id", ""),
+                chunk_id=chunk_id,
                 type="text",
                 content=raw.get("content", ""),
                 path=raw.get("path"),
                 length=metadata.get("length", raw.get("length", 0)),
-                tokens=metadata.get("tokens", raw.get("tokens")),
+                tokens=_parseTextChunkTokens(raw_tokens, chunk_id=chunk_id),
                 keywords=metadata.get("keywords", raw.get("keywords")),
                 summary=metadata.get("summary", raw.get("summary")),
                 relationships=metadata.get("relationships", raw.get("relationships")),

knowhere/lib/upload.py

@@ -2,11 +2,15 @@
 
 from __future__ import annotations
 
+import asyncio
+import random
+import time
 from pathlib import Path
 from typing import BinaryIO, Dict, Optional, Union
 
 import httpx
 
+from knowhere._constants import DEFAULT_UPLOAD_MAX_RETRIES
 from knowhere._exceptions import APIConnectionError, APITimeoutError
 from knowhere._logging import getLogger
 from knowhere._types import UploadProgressCallback
@@ -16,6 +20,26 @@ _logger = getLogger()
 # Chunk size for streaming uploads (256 KiB)
 _UPLOAD_CHUNK_SIZE: int = 256 * 1024
 
+# Storage-provider HTTP status codes that are safe to retry.
+# These are transient errors from S3/GCS/Azure Blob, not Knowhere API codes.
+_UPLOAD_RETRYABLE_STATUS_CODES: frozenset[int] = frozenset({500, 502, 503, 504})
+
+
+def _calculateUploadRetryDelay(attempt: int) -> float:
+    """Exponential backoff with jitter for upload retries."""
+    base_delay: float = min(1.0 * (2 ** attempt), 16.0)
+    jitter: float = random.uniform(0, base_delay * 0.25)
+    return base_delay + jitter
+
+
+def _isRetryableUploadError(exc: Exception) -> bool:
+    """Return True if the upload error is transient and worth retrying."""
+    if isinstance(exc, (httpx.ConnectError, httpx.TimeoutException)):
+        return True
+    if isinstance(exc, httpx.HTTPStatusError):
+        return exc.response.status_code in _UPLOAD_RETRYABLE_STATUS_CODES
+    return False
+
 
 def _prepareFileContent(
     file: Union[Path, BinaryIO, bytes],
@@ -66,41 +90,68 @@ def syncUploadFile(
     on_progress: Optional[UploadProgressCallback] = None,
     *,
     timeout: float = 600.0,
+    max_retries: int = DEFAULT_UPLOAD_MAX_RETRIES,
 ) -> None:
-    """Upload *file* to *upload_url* using a synchronous PUT request."""
+    """Upload *file* to *upload_url* using a synchronous PUT request.
+
+    Retries on connection errors, timeouts, and transient storage HTTP errors
+    (500/502/503/504) up to *max_retries* times.
+    """
     content, total_bytes = _prepareFileContent(file)
     headers: Dict[str, str] = _buildUploadHeaders(upload_headers, total_bytes)
 
-    _logger.debug("Uploading %s bytes to %s", total_bytes, upload_url)
-
     if isinstance(content, bytes):
         data: bytes = content
     else:
-        # BinaryIO — read all for simplicity (already measured size)
         pos: int = content.tell()
         data = content.read()
         content.seek(pos)
 
-    if on_progress:
-        on_progress(0, total_bytes)
+    last_exc: Optional[Exception] = None
 
-    try:
-        response: httpx.Response = client.put(
-            upload_url,
-            content=data,
-            headers=headers,
-            timeout=timeout,
+    for attempt in range(max_retries + 1):
+        _logger.debug(
+            "Upload attempt %d/%d — %s bytes to %s",
+            attempt + 1, max_retries + 1, total_bytes, upload_url,
         )
-        response.raise_for_status()
-    except httpx.TimeoutException as exc:
-        raise APITimeoutError(f"Upload timed out: {exc}") from exc
-    except httpx.HTTPError as exc:
-        raise APIConnectionError(f"Upload failed: {exc}") from exc
-
-    if on_progress:
-        on_progress(len(data), total_bytes)
 
-    _logger.debug("Upload complete: %d", response.status_code)
+        if on_progress and attempt == 0:
+            on_progress(0, total_bytes)
+
+        try:
+            response: httpx.Response = client.put(
+                upload_url,
+                content=data,
+                headers=headers,
+                timeout=timeout,
+            )
+            response.raise_for_status()
+        except (httpx.HTTPError, httpx.TimeoutException) as exc:
+            last_exc = exc
+            if attempt < max_retries and _isRetryableUploadError(exc):
+                delay: float = _calculateUploadRetryDelay(attempt)
+                _logger.warning(
+                    "Upload attempt %d/%d failed (%s), retrying in %.1fs",
+                    attempt + 1, max_retries + 1, exc, delay,
+                )
+                time.sleep(delay)
+                continue
+            # Non-retryable or exhausted retries
+            if isinstance(exc, httpx.TimeoutException):
+                raise APITimeoutError(f"Upload timed out: {exc}") from exc
+            raise APIConnectionError(f"Upload failed: {exc}") from exc
+
+        # Success
+        if on_progress:
+            on_progress(len(data), total_bytes)
+        _logger.debug("Upload complete: %d", response.status_code)
+        return
+
+    # Should not reach here, but guard against it
+    if last_exc is not None:
+        if isinstance(last_exc, httpx.TimeoutException):
+            raise APITimeoutError(f"Upload timed out: {last_exc}") from last_exc
+        raise APIConnectionError(f"Upload failed: {last_exc}") from last_exc
 
 
 async def asyncUploadFile(
@@ -111,37 +162,62 @@ async def asyncUploadFile(
     on_progress: Optional[UploadProgressCallback] = None,
     *,
     timeout: float = 600.0,
+    max_retries: int = DEFAULT_UPLOAD_MAX_RETRIES,
 ) -> None:
-    """Upload *file* to *upload_url* using an async PUT request."""
+    """Upload *file* to *upload_url* using an async PUT request.
+
+    Retries on connection errors, timeouts, and transient storage HTTP errors
+    (500/502/503/504) up to *max_retries* times.
+    """
     content, total_bytes = _prepareFileContent(file)
     headers: Dict[str, str] = _buildUploadHeaders(upload_headers, total_bytes)
 
-    _logger.debug("Async uploading %s bytes to %s", total_bytes, upload_url)
-
     if isinstance(content, bytes):
         data: bytes = content
     else:
-        pos = content.tell()
+        pos: int = content.tell()
         data = content.read()
         content.seek(pos)
 
-    if on_progress:
-        on_progress(0, total_bytes)
+    last_exc: Optional[Exception] = None
 
-    try:
-        response: httpx.Response = await client.put(
-            upload_url,
-            content=data,
-            headers=headers,
-            timeout=timeout,
+    for attempt in range(max_retries + 1):
+        _logger.debug(
+            "Async upload attempt %d/%d — %s bytes to %s",
+            attempt + 1, max_retries + 1, total_bytes, upload_url,
         )
-        response.raise_for_status()
-    except httpx.TimeoutException as exc:
-        raise APITimeoutError(f"Upload timed out: {exc}") from exc
-    except httpx.HTTPError as exc:
-        raise APIConnectionError(f"Upload failed: {exc}") from exc
-
-    if on_progress:
-        on_progress(len(data), total_bytes)
 
-    _logger.debug("Async upload complete: %d", response.status_code)
+        if on_progress and attempt == 0:
+            on_progress(0, total_bytes)
+
+        try:
+            response: httpx.Response = await client.put(
+                upload_url,
+                content=data,
+                headers=headers,
+                timeout=timeout,
+            )
+            response.raise_for_status()
+        except (httpx.HTTPError, httpx.TimeoutException) as exc:
+            last_exc = exc
+            if attempt < max_retries and _isRetryableUploadError(exc):
+                delay: float = _calculateUploadRetryDelay(attempt)
+                _logger.warning(
+                    "Async upload attempt %d/%d failed (%s), retrying in %.1fs",
+                    attempt + 1, max_retries + 1, exc, delay,
+                )
+                await asyncio.sleep(delay)
+                continue
+            if isinstance(exc, httpx.TimeoutException):
+                raise APITimeoutError(f"Upload timed out: {exc}") from exc
+            raise APIConnectionError(f"Upload failed: {exc}") from exc
+
+        if on_progress:
+            on_progress(len(data), total_bytes)
+        _logger.debug("Async upload complete: %d", response.status_code)
+        return
+
+    if last_exc is not None:
+        if isinstance(last_exc, httpx.TimeoutException):
+            raise APITimeoutError(f"Upload timed out: {last_exc}") from last_exc
+        raise APIConnectionError(f"Upload failed: {last_exc}") from last_exc

knowhere/resources/jobs.py

@@ -8,6 +8,7 @@ from typing import Any, BinaryIO, Dict, Optional, Union
 import httpx
 
 from knowhere._constants import DEFAULT_POLL_INTERVAL, DEFAULT_POLL_TIMEOUT
+from knowhere._exceptions import InvalidStateError
 from knowhere._logging import getLogger
 from knowhere._types import (
     PollProgressCallback,
@@ -84,7 +85,7 @@ class Jobs(SyncAPIResource):
         """
         if isinstance(job, Job):
             if not job.upload_url:
-                raise ValueError("Job does not have an upload URL.")
+                raise InvalidStateError("Job does not have an upload URL.")
             upload_url: str = job.upload_url
             upload_headers: Optional[Dict[str, str]] = job.upload_headers
         else:
@@ -134,7 +135,7 @@ class Jobs(SyncAPIResource):
         """
         if isinstance(job_result, JobResult):
             if not job_result.result_url:
-                raise ValueError("JobResult does not have a result_url.")
+                raise InvalidStateError("JobResult does not have a result_url.")
             result_url: str = job_result.result_url
         else:
             result_url = job_result
@@ -192,7 +193,7 @@ class AsyncJobs(AsyncAPIResource):
         """Upload a file for a job (async)."""
         if isinstance(job, Job):
             if not job.upload_url:
-                raise ValueError("Job does not have an upload URL.")
+                raise InvalidStateError("Job does not have an upload URL.")
             upload_url: str = job.upload_url
             upload_headers: Optional[Dict[str, str]] = job.upload_headers
         else:
@@ -234,7 +235,7 @@ class AsyncJobs(AsyncAPIResource):
         """Download and parse the result ZIP (async)."""
         if isinstance(job_result, JobResult):
             if not job_result.result_url:
-                raise ValueError("JobResult does not have a result_url.")
+                raise InvalidStateError("JobResult does not have a result_url.")
             result_url: str = job_result.result_url
         else:
             result_url = job_result

knowhere/types/result.py

@@ -8,6 +8,9 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
 
 from pydantic import BaseModel, Field
+from typing_extensions import TypeAlias
+
+from knowhere._exceptions import ValidationError
 
 
 # ---------------------------------------------------------------------------
@@ -30,11 +33,11 @@ def _sanitizeFilename(name: str) -> str:
 
 
 def _ensurePathWithinDirectory(base: Path, target: Path) -> Path:
-    """Raise ``ValueError`` if *target* escapes *base* (Zip Slip prevention)."""
+    """Raise ``ValidationError`` if *target* escapes *base* (Zip Slip prevention)."""
     resolved_base: Path = base.resolve()
     resolved_target: Path = target.resolve()
     if not str(resolved_target).startswith(str(resolved_base)):
-        raise ValueError(
+        raise ValidationError(
             f"Path '{resolved_target}' escapes output directory '{resolved_base}'."
         )
     return resolved_target
@@ -122,12 +125,15 @@ class BaseChunk(BaseModel):
     path: Optional[str] = None
 
 
+TextChunkTokens: TypeAlias = List[str]
+
+
 class TextChunk(BaseChunk):
     """A text chunk extracted from the document."""
 
     type: str = "text"
     length: int = 0
-    tokens: Optional[int] = None
+    tokens: Optional[TextChunkTokens] = None
     keywords: Optional[List[str]] = None
     summary: Optional[str] = None
     relationships: Optional[List[Union[Dict[str, Any], str]]] = None

{knowhere_python_sdk-0.1.0.dist-info → knowhere_python_sdk-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: knowhere-python-sdk
-Version: 0.1.0
+Version: 0.2.0
 Summary: Official Python SDK for the Knowhere document parsing API
 Project-URL: Homepage, https://knowhereto.ai
 Project-URL: Documentation, https://docs.knowhereto.ai
@@ -32,38 +32,41 @@ Description-Content-Type: text/markdown
 
 # Knowhere Python SDK
 
+[![PyPI version](https://img.shields.io/pypi/v/knowhere-python-sdk.svg)](https://pypi.org/project/knowhere-python-sdk/)
+
 Official Python SDK for the [Knowhere](https://knowhereto.ai) document parsing API.
 
 ## Installation
 
-```bash
+```sh
 pip install knowhere-python-sdk
 ```
 
 Or with [uv](https://docs.astral.sh/uv/):
 
-```bash
+```sh
 uv add knowhere-python-sdk
 ```
 
-## Quick Start
+## Usage
 
 ```python
 import knowhere
 
 client = knowhere.Knowhere(api_key="sk_...")
 
-# Parse a document from URL
 result = client.parse(url="https://example.com/report.pdf")
 
-print(result.statistics.total_chunks)  # 152
-print(result.full_markdown[:200])      # First 200 chars of full markdown
+print(result.statistics.total_chunks)
+print(result.full_markdown[:200])
 
 for chunk in result.text_chunks:
     print(chunk.content[:80])
 ```
 
-### Parse a Local File
+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.
+
+### Parse a local file
 
 ```python
 from pathlib import Path
@@ -77,7 +80,7 @@ print(result.manifest.source_file_name)  # "report.pdf"
 print(len(result.chunks))                # 152
 ```
 
-### Access Different Chunk Types
+### Access different chunk types
 
 ```python
 result = client.parse(url="https://example.com/report.pdf")
@@ -99,14 +102,14 @@ for chunk in result.table_chunks:
     print(chunk.html[:100])
 ```
 
-### Save All Results to Disk
+### Save all results to disk
 
 ```python
 result = client.parse(file=Path("report.pdf"))
 result.save("./output/report/")
 ```
 
-## Async Usage
+## Async usage
 
 ```python
 import asyncio
@@ -123,7 +126,7 @@ async def main():
 asyncio.run(main())
 ```
 
-## Step-by-Step Control
+## Step-by-step control
 
 For granular control over the parsing workflow, use the `jobs` resource directly:
 
@@ -148,6 +151,22 @@ result = client.jobs.load(job_result)
 print(result.statistics)
 ```
 
+## Handling errors
+
+All errors inherit from `knowhere.KnowhereError`.
+
+
+```python
+import knowhere
+
+try:
+    result = client.parse(url="https://example.com/report.pdf")
+except knowhere.AuthenticationError:
+    print("Invalid API key")
+except knowhere.APIStatusError as e:
+    print(f"{e.status_code}: {e.message}")
+```
+
 ## Configuration
 
 The SDK reads configuration from constructor arguments, environment variables, or defaults (in that priority order):
@@ -172,50 +191,30 @@ client = knowhere.Knowhere(
 )
 ```
 
-### Context Manager
+### Retries
 
-```python
-# Sync — ensures httpx.Client is properly closed
-with knowhere.Knowhere(api_key="sk_...") as client:
-    result = client.parse(url="https://example.com/report.pdf")
+Connection errors, 429 Rate Limit, and >=500 Internal errors are automatically retried with exponential backoff.
 
-# Async — ensures httpx.AsyncClient is properly closed
-async with knowhere.AsyncKnowhere(api_key="sk_...") as client:
-    result = await client.parse(url="https://example.com/report.pdf")
+```python
+client = knowhere.Knowhere(
+    api_key="sk_...",
+    max_retries=3,  # default is 5
+)
 ```
 
-## Error Handling
+### Determining the installed version
 
 ```python
-from knowhere import (
-    Knowhere,
-    AuthenticationError,
-    NotFoundError,
-    RateLimitError,
-    BadRequestError,
-    APIStatusError,
-    PollingTimeoutError,
-)
-
-try:
-    result = client.parse(url="https://example.com/report.pdf")
-except BadRequestError as e:
-    print(e.status_code)   # 400
-    print(e.code)          # "INVALID_ARGUMENT"
-    print(e.message)       # "Unsupported file format"
-    print(e.request_id)    # "req_abc123"
-except NotFoundError as e:
-    print(e.message)       # "Job not found"
-except RateLimitError as e:
-    print(e.retry_after)   # seconds to wait
-except AuthenticationError:
-    print("Invalid API key")
-except PollingTimeoutError:
-    print("Job did not complete within timeout")
-except APIStatusError as e:
-    print(f"API error {e.status_code}: {e.message}")
+import knowhere
+print(knowhere.__version__)
 ```
 
+## Versioning
+
+This package follows [Semantic Versioning](https://semver.org/).
+
+We publish stable releases to [PyPI](https://pypi.org/project/knowhere-python-sdk/). To install the latest unreleased changes directly from the repository: https://github.com/Ontos-AI/knowhere-python-sdk
+
 ## Requirements
 
 - Python 3.9+
@@ -223,92 +222,6 @@ except APIStatusError as e:
 - [pydantic](https://docs.pydantic.dev/) `>=2.0.0,<3.0`
 - [typing-extensions](https://pypi.org/project/typing-extensions/) `>=4.7.0`
 
-## Building from Source
-
-### Prerequisites
-
-- Python 3.9 or later
-- [uv](https://docs.astral.sh/uv/) (recommended) or pip
-
-### Build
-
-```bash
-git clone https://github.com/Ontos-AI/knowhere-python-sdk.git
-cd knowhere-python-sdk
-
-# Install uv if you don't have it
-curl -LsSf https://astral.sh/uv/install.sh | sh
-
-# Build sdist + wheel
-uv build
-
-# Install the built wheel
-pip install dist/knowhere_python_sdk-*.whl
-```
-
-## Development
-
-### Setup
-
-```bash
-git clone https://github.com/Ontos-AI/knowhere-python-sdk.git
-cd knowhere-python-sdk
-
-# Create venv and install all dependencies (including dev)
-uv sync --all-extras
-```
-
-### Running Tests
-
-```bash
-# Run all unit tests
-uv run pytest tests/ -v
-
-# Run with coverage
-uv run coverage run -m pytest tests/ -v
-uv run coverage report -m
-```
-
-### Linting and Type Checking
-
-```bash
-# Lint
-uv run ruff check src/
-
-# Type check
-uv run mypy src/knowhere/
-```
-
-### Project Structure
-
-```
-knowhere-python-sdk/
-├── src/knowhere/
-│   ├── __init__.py              # Public API surface
-│   ├── _client.py               # Knowhere + AsyncKnowhere clients
-│   ├── _base_client.py          # HTTP logic, retry, error parsing
-│   ├── _exceptions.py           # Exception hierarchy
-│   ├── _constants.py            # Default URLs, timeouts, env var names
-│   ├── _types.py                # Sentinel types, callback type aliases
-│   ├── _logging.py              # Logger setup, header redaction
-│   ├── _response.py             # APIResponse wrapper
-│   ├── _version.py              # __version__
-│   ├── py.typed                 # PEP 561 marker
-│   ├── types/
-│   │   ├── job.py               # Job, JobResult, JobError
-│   │   ├── result.py            # ParseResult, Manifest, Chunk types
-│   │   └── params.py            # ParsingParams, WebhookConfig
-│   ├── resources/
-│   │   └── jobs.py              # Jobs + AsyncJobs resource
-│   └── lib/
-│       ├── polling.py           # Adaptive polling loop
-│       ├── upload.py            # Streaming file upload
-│       └── result_parser.py     # ZIP parsing, checksum verification
-├── tests/                       # Unit tests (respx-mocked HTTP)
-├── examples/                    # Usage examples
-└── pyproject.toml
-```
-
 ## License
 
 MIT

knowhere_python_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+knowhere/__init__.py,sha256=EuIpP3FtDeszonVAXMxZimjRd9iUcQ8wA53h1f27S3k,2343
+knowhere/_base_client.py,sha256=ddeRR1lWLhes5ipvYX6-TMEecjjiEBGfQdPw_vnSNqA,17978
+knowhere/_client.py,sha256=MGU1QsyjKrzTiitm891wgNCq6JLf3DR7y7zhkil_p2E,8027
+knowhere/_constants.py,sha256=ZNCFQC00NpUZIyc_XZ0uemjJE-E8uKAbv3BDa3po9cg,885
+knowhere/_exceptions.py,sha256=yg-4pK7AP6uUPxxyggxf8spQeXgFTpKRwELsHjCQycg,11489
+knowhere/_logging.py,sha256=tNqEA1dLv-adTT6qRq5RBeO35FoWrnS3gwt7gKChLTA,1376
+knowhere/_response.py,sha256=EsrM794qxCykvl82UkszeqjJzm9_OSq7nsyzaSCnx0I,1415
+knowhere/_types.py,sha256=8-JFaRcxgBJbw2mV9BwnmCktFVph41a1mduwtXlYidI,1775
+knowhere/_version.py,sha256=piZV5NEcs0VIotCxwaWvzWE2ASUv5tox5ye8ogIRiIk,50
+knowhere/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+knowhere/lib/__init__.py,sha256=e953V5ny3VmDtCw7y_4uPwdTkwwNpe_Y6o4AEgz3ujw,50
+knowhere/lib/polling.py,sha256=s0EPHozAvNhXLqr5uwU8YXkkwAdF0ji_nIN0QfR6avY,4500
+knowhere/lib/result_parser.py,sha256=U-DK3SDKrbUY0g_-ad04bsbra1mhYy9FJ2opa1n2bTU,8406
+knowhere/lib/upload.py,sha256=eT-O9_wB2WkWUAsUd7VzaKY6DVfNeA6WMHRdwm0HM0o,7849
+knowhere/resources/__init__.py,sha256=_x391t8qxwkGbOmbkzcp7rR10Q8uoDLQaAkZxCq_oM8,170
+knowhere/resources/_base.py,sha256=tgKphNTsgMhktWp6_rhyVOZyee4CYlDmD5O1_jWVvYo,1829
+knowhere/resources/jobs.py,sha256=45P4rZ9HMnTdgcso2AwQ6lDA9U80HGsgOU0jZLBIMFU,8460
+knowhere/types/__init__.py,sha256=OwTxpa9uo0GOEJ6Ds6rqEmXl86O49ByS6M7cscMwQo8,791
+knowhere/types/job.py,sha256=8shCqvgzKKkEPOpEHdk7CnDbPQiDzy3wEd5Jngw94ZM,2362
+knowhere/types/params.py,sha256=7DyBd4xMxtLPch-A1130-gI0ajKOv2G5tbSMkE8n6-E,543
+knowhere/types/result.py,sha256=Lmtaa0wQymBzAm6hXoZZr6dlfwf0WCMEda6Gd8nDIdw,9628
+knowhere/types/shared.py,sha256=K5ezX212othxgCviiE2WnwWFY2MS08pXKJ8Km1ZWmjc,104
+knowhere_python_sdk-0.2.0.dist-info/METADATA,sha256=10dnumfebnQ3VmPHmYuDexWTCdqdFLi-eAaF8FwcNpc,6115
+knowhere_python_sdk-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+knowhere_python_sdk-0.2.0.dist-info/RECORD,,

{knowhere_python_sdk-0.1.0.dist-info → knowhere_python_sdk-0.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.28.0
+Generator: hatchling 1.29.0
 Root-Is-Purelib: true
 Tag: py3-none-any

knowhere_python_sdk-0.1.0.dist-info/RECORD

@@ -1,25 +0,0 @@
-knowhere/__init__.py,sha256=CGMrMT1Ujmv8-9Kq_Imfch_lFzxkfbBebefd2nMLIo8,2251
-knowhere/_base_client.py,sha256=Rt9rbERMVOFGHU-Tyou4CaUCqQ3VRUvA8siDlp8bcDM,15222
-knowhere/_client.py,sha256=-Bv5BOinvvnHyLregcGfMFMSbwpFGzWFVnfIN8uq5qY,7958
-knowhere/_constants.py,sha256=zD1WuJz77LbGE3NXP1zc0eSXkaiibStSVLyN34D-lYc,849
-knowhere/_exceptions.py,sha256=vH2b_shTBElkeHoQ30QZp-zNucSVaTQ7QHDuy6tEyb0,9012
-knowhere/_logging.py,sha256=tNqEA1dLv-adTT6qRq5RBeO35FoWrnS3gwt7gKChLTA,1376
-knowhere/_response.py,sha256=EsrM794qxCykvl82UkszeqjJzm9_OSq7nsyzaSCnx0I,1415
-knowhere/_types.py,sha256=8-JFaRcxgBJbw2mV9BwnmCktFVph41a1mduwtXlYidI,1775
-knowhere/_version.py,sha256=IOEzhCbX916JIkvZr03GFY4bl9YqSkfjdqLO4qJ2FOs,50
-knowhere/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-knowhere/lib/__init__.py,sha256=e953V5ny3VmDtCw7y_4uPwdTkwwNpe_Y6o4AEgz3ujw,50
-knowhere/lib/polling.py,sha256=s0EPHozAvNhXLqr5uwU8YXkkwAdF0ji_nIN0QfR6avY,4500
-knowhere/lib/result_parser.py,sha256=KnRDhW8G_frH5-FMrpoeG3_188_Hk2kSzDixrec6_fg,7257
-knowhere/lib/upload.py,sha256=AEDLJH1UANPU96JbDdstomE__xuu5DfW7YTZQk1g0lg,4544
-knowhere/resources/__init__.py,sha256=_x391t8qxwkGbOmbkzcp7rR10Q8uoDLQaAkZxCq_oM8,170
-knowhere/resources/_base.py,sha256=tgKphNTsgMhktWp6_rhyVOZyee4CYlDmD5O1_jWVvYo,1829
-knowhere/resources/jobs.py,sha256=k6ZNAdEr6CKmHT-bgtaliF5gjOF7IjLYnDM5dqPCKhw,8381
-knowhere/types/__init__.py,sha256=OwTxpa9uo0GOEJ6Ds6rqEmXl86O49ByS6M7cscMwQo8,791
-knowhere/types/job.py,sha256=8shCqvgzKKkEPOpEHdk7CnDbPQiDzy3wEd5Jngw94ZM,2362
-knowhere/types/params.py,sha256=7DyBd4xMxtLPch-A1130-gI0ajKOv2G5tbSMkE8n6-E,543
-knowhere/types/result.py,sha256=9uCiTm2-X6jOMK5eyNbbzMj11G9vfCuCF_yoowLJ2JQ,9475
-knowhere/types/shared.py,sha256=K5ezX212othxgCviiE2WnwWFY2MS08pXKJ8Km1ZWmjc,104
-knowhere_python_sdk-0.1.0.dist-info/METADATA,sha256=sf2ro4Ya8-r1wHCtWhpTtt-xQLcXQY04wAyjHn-msss,8536
-knowhere_python_sdk-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-knowhere_python_sdk-0.1.0.dist-info/RECORD,,