knowledge2 0.4.0__tar.gz

knowledge2-0.4.0/.github/workflows/pypi-release.yml

@@ -0,0 +1,104 @@
+name: pypi-release
+
+on:
+  push:
+    tags:
+      - "py-sdk-v*.*.*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build-test-publish:
+    runs-on: ubuntu-24.04
+    environment: pypi-publish
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -I -m pip install \
+            "setuptools>=68.0" \
+            setuptools-scm \
+            wheel \
+            build==1.2.2.post1 \
+            twine==6.1.0
+
+      - name: Version guard
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#py-sdk-v}"
+          PKG_VERSION=$(python -I -c "
+          import re, pathlib, sys
+          text = pathlib.Path('pyproject.toml').read_text()
+          m = re.search(r'^version\s*=\s*\"(.+?)\"', text, re.MULTILINE)
+          if not m:
+              print('ERROR: Could not find version in pyproject.toml', file=sys.stderr)
+              sys.exit(1)
+          print(m.group(1))
+          ")
+          echo "Tag version:     ${TAG_VERSION}"
+          echo "Package version: ${PKG_VERSION}"
+          if [ "${TAG_VERSION}" != "${PKG_VERSION}" ]; then
+            echo "::error::Tag version (${TAG_VERSION}) does not match pyproject.toml version (${PKG_VERSION})"
+            exit 1
+          fi
+
+      - name: Publish metadata guard
+        run: |
+          python -I - <<'PY'
+          import pathlib
+          import sys
+          import tomllib
+
+          project = tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))["project"]
+          urls = project.get("urls", {})
+          expected = {
+              "Repository": "https://github.com/knowledge2-ai/knowledge2-python-sdk",
+              "Changelog": "https://github.com/knowledge2-ai/knowledge2-python-sdk/blob/main/CHANGELOG.md",
+          }
+          for key, value in expected.items():
+              if key not in urls:
+                  print(f"::error::{key} URL missing from pyproject.toml")
+                  sys.exit(1)
+              if urls[key] != value:
+                  print(
+                      f"::error::{key} URL must be {value}, found {urls[key]}",
+                  )
+                  sys.exit(1)
+          PY
+
+      - name: Build package
+        run: python -I -m build --no-isolation . --outdir dist/
+
+      - name: Metadata guard
+        run: twine check dist/*
+
+      - name: Smoke test
+        run: |
+          python -I -m venv /tmp/smoke-test
+          python -I - <<'PY' >/tmp/smoke-test-requirements.txt
+          import pathlib
+          import tomllib
+
+          project = tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))["project"]
+          for dependency in project.get("dependencies", []):
+              print(dependency)
+          PY
+          if [ -s /tmp/smoke-test-requirements.txt ]; then
+            /tmp/smoke-test/bin/python -I -m pip install -r /tmp/smoke-test-requirements.txt
+          fi
+          /tmp/smoke-test/bin/python -I -m pip install --no-index --find-links dist/ --no-deps dist/*.whl
+          /tmp/smoke-test/bin/python -I -c "from sdk import Knowledge2; print(Knowledge2)"
+
+      - name: Hide stdlib-shadowing package for publish action
+        run: mv types _types_publish_hidden
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70  # v1.12.3
+        with:
+          packages-dir: dist/

knowledge2-0.4.0/AGENTS.md

@@ -0,0 +1,31 @@
+# AGENTS.md
+
+## Scope
+- This file documents the Python SDK in isolation; assume no context from other folders.
+- For system-level architecture and deployment strategy, read `../AGENTS.md` and `../docs/flux_release_branches.md`.
+
+## Repo release strategy (deployment-impacting changes)
+- Promotion is merge-forward only: `dev` -> `staging` -> `prod`.
+- Flux branch wiring and overlay mapping are documented in `../docs/flux_release_branches.md`.
+- Keep environment config isolated (Auth0 tenant/domain/client, callback URLs, and secrets must remain environment-specific).
+
+## What this library is
+- Minimal Python client for the API service.
+- Used by external apps and examples to call the REST API.
+
+## Entry point
+- Client: `sdk/client.py`.
+
+## Key files
+- `sdk/_base.py`: HTTP plumbing and shared request logic.
+- `sdk/types/`: data model types for responses.
+- `sdk/errors.py`: exception types.
+- `sdk/examples/`: runnable usage samples.
+
+## External dependencies (treat as contracts)
+- Expects API base URL and `X-API-Key` auth.
+- API request/response shapes must match server endpoints.
+
+## When changing this library
+- Keep backwards compatibility for public client methods.
+- If the API contract changes, update `sdk/types/` and regenerate examples.

knowledge2-0.4.0/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+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.3.0] - 2026-03-30
+
+### Added
+
+- **Async parallel uploads**: `upload_documents_parallel()` on `AsyncDocumentsMixin`, bringing parity with the sync client.
+- **Typed response models**: New response types for agents (`sdk/types/agents.py`), feeds (`sdk/types/feeds.py`), and pipelines (`sdk/types/pipelines.py`).
+- **Comprehensive unit tests**: 339 unit tests covering all SDK resource modules.
+- **PyPI release pipeline**: Public-repo `pypi-release.yml` GitHub Actions workflow for automated publishing.
+- **Python 3.13 classifier**: Added `Programming Language :: Python :: 3.13` to package metadata.
+- **Changelog URL**: Added changelog link to `pyproject.toml` project URLs.
+- Mark agents, feeds, pipelines, and A2A resources as preview — emits
+  `RuntimeWarning` on first call to indicate feature-flag dependency
+
+### Fixed
+
+- **Python version badge**: README badge now correctly states Python 3.11+ (was 3.10+).
+
+## [0.2.0] - 2026-03-12
+
+### Added
+
+- **`ClientTimeouts`** (#713): Per-phase HTTP timeout configuration (connect, read, write, pool). Accepts `ClientTimeouts` dataclass, `float`, or `httpx.Timeout`.
+- **`require_str()` param guard** (#714): Validates non-empty, non-whitespace resource IDs at call site before API request.
+- **SDK User-Agent** (#715): Auto-injected `User-Agent: k2-python-sdk/{version}` header on every request. Customizable via `user_agent` parameter.
+- **`is_authenticated()` health check** (#716): Returns `True` if any auth credential (API key, bearer token, admin token, or factory) is configured.
+- **`Page[T]` pagination** (#717): `list_*` methods return `Page[T]` frozen dataclass with `items`, `total`, `offset`, `limit`. Supports `len()`, iteration, and boolean check.
+- **`SyncPager[T]`** (#717): Lazy paginator with `next_page()`, `iter_pages()`, and item-level iteration for `iter_*` methods.
+- **`bearer_token_factory`** (#718): Callable-based dynamic auth for OAuth/OIDC. Thread-safe double-check locking with configurable `token_cache_ttl` (default 300s, 0 to disable). Auto-refreshes on 401.
+- **Two-step delete guard** (#719): `delete_corpus()` requires `confirm=True` to execute. Raises `ValueError` if not confirmed.
+- **`K2Config` frozen config** (#720): Pydantic-settings based configuration from environment variables (`K2_*` prefix), JSON/YAML files, or named profiles.
+- **Sub-client namespaces** (#721): `client.documents.*`, `client.corpora.*`, `client.search_ns.*`, etc. Lightweight cached proxies — flat methods still work.
+- **Parallel uploads** (#722): `upload_documents_parallel()` using `ThreadPoolExecutor` for concurrent document ingestion.
+- **Pydantic response validation** (#723): Optional `validate_responses=True` or `Knowledge2Validated` class. Requires `pip install knowledge2[pydantic]`.
+- **`AsyncKnowledge2` client** (#724): Native async client using `httpx.AsyncClient`. `AsyncPager[T]` for async pagination. Factory methods: `create()`, `from_env()`, `from_file()`, `from_profile()`.
+- **`RequestOptions`** (#732): Per-call overrides for timeout, retries, and passthrough headers. `request_options` parameter on all public methods.
+- **`with_raw_response`** (#733): `client.with_raw_response.<method>(...)` returns `RawResponse[T]` with `status_code`, `headers`, and `parsed` body. Thread-safe (sync) and task-safe (async).
+- **Custom `httpx.Client` injection** (#734): `http_client` parameter for custom TLS, proxies, or observability middleware. Explicit ownership — SDK never closes caller-supplied clients.
+
+### Changed
+
+- **`list_*` methods return `Page[T]`** instead of raw dicts. This is a breaking change for code that accessed the raw dict keys directly. Use `page.items` instead.
+
+## [0.1.0] - 2026-02-13
+
+### Added
+
+- **Error hierarchy**: 10 exception types (`AuthenticationError`, `RateLimitError`,
+  `ServerError`, `APIConnectionError`, `APITimeoutError`, etc.) with `retryable`
+  property. All subclass `Knowledge2Error` for backward compatibility.
+- **Automatic retry**: Exponential backoff with jitter for 5xx, 429, connection
+  errors, and timeouts. Configurable via `max_retries` (default: 2). Rate limit
+  429 responses honor `Retry-After` header.
+- **Pagination iterators**: `iter_*` methods for all paginated `list_*` endpoints
+  (e.g., `iter_documents`, `iter_corpora`, `iter_jobs`). Lazy page fetching.
+- **Debug logging**: Logger named `knowledge2` with credential redaction.
+  `set_debug()` convenience method.
+- **Typed config parameters**: Search methods accept TypedDict types
+  (`SearchHybridConfig`, `SearchRerankConfig`, etc.) alongside `dict[str, Any]`.
+- **Comprehensive docstrings**: Google-style docstrings on all public methods.
+- **Standalone package**: `pyproject.toml` for independent `pip install`.
+- **SDK versioning**: `__version__` attribute and this changelog.
+- **Focused examples**: Quick-start, search, document upload, error handling,
+  pagination, and batch operations examples.
+- **Comprehensive README**: Installation, authentication, configuration, error
+  handling, pagination, and resource overview.
+
+### Changed
+
+- `fetch_whoami()` renamed to `get_whoami()` for consistency. `fetch_whoami()`
+  is now a deprecated alias.
+- `reconcile_jobs()` and `cancel_tuning_run()` return typed responses instead
+  of `dict[str, Any]`.