knowledge2 0.5.0__tar.gz → 0.8.0__tar.gz

knowledge2-0.8.0/CHANGELOG.md

@@ -0,0 +1,298 @@
+# Changelog
+
+All notable changes to the Knowledge² 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).
+
+## Unreleased
+
+### Changed
+
+- **`validate_responses=True` now returns typed run envelopes.** Under response
+  validation, `run_agent(..., wait=True)`'s `result` and each `list_agent_runs()`
+  item's `result` are now `AgentRunEnvelope` models (attribute access:
+  `.content`, `.fields.inferred`, `.metadata.inferred`, `.metadata.provenance`)
+  rather than raw dicts. A malformed envelope raises `ValidationError` (as with
+  every other validated model), consistent across both read paths. The default
+  (`validate_responses=False`) is unchanged — raw dicts. Also: `Provenance` now
+  types `source_refs`, and `TaskTypeInfo.unavailable_reason` is narrowed to
+  `Literal["env", "org"] | None`. (#2594)
+
+### Added
+
+- `client.backfill_feed(feed_id, *, start_from)` (sync) and
+  `await client.backfill_feed(...)` (async) — re-enqueue a backfill
+  on an existing feed without delete-and-recreate. Resets the feed
+  cursor and updates `Feed.start_from`; the worker re-sweeps the
+  corpus `CorpusChangeEvent` history from the supplied cutoff.
+  Returns `{job_id, start_from, previous_last_checked_seq}` (`202
+  Accepted`). Raises `ConflictError` (`code="feed_backfill_in_flight"`)
+  when a `run_feed` job for this feed is already queued or running;
+  raises `ValidationError` for future `start_from`. Per-feed-run
+  feedback lineage (#969) survives — every backfill produces a new
+  `feed_run_id`. (#2328)
+- `schedule_cron` kwarg on `create_feed(...)` / `update_feed(...)`
+  (sync + async) — UTC five-field cron expression for calendar-aware
+  feed schedules (e.g. `"0 9 * * MON"`). Mutually exclusive with
+  `schedule_interval`; requires `persistent=True`; rejected when
+  combined with `reactive=True`. Invalid expressions surface as
+  `422 ValidationError` with the underlying croniter message. New
+  field also surfaces on `FeedResponse`. (#2305)
+- `FeedRunResponse.generated_answer` (`dict | None`) — when
+  `execution_mode="answer"` and the retrieval step returns results,
+  the API now runs the full agent LLM via `execute_agent_task` over
+  the chunks and returns the envelope on the run response. Generation
+  failures are logged and downgrade gracefully (the response is still
+  returned without `generated_answer`). Previously the API raised
+  `501` for `answer` mode. (#2303)
+- `client.trigger_pipeline_spec(pipeline_spec_id)` (sync) and
+  `await client.trigger_pipeline_spec(...)` (async) — manually fire a
+  pipeline run against the spec's bound feeds. Returns
+  `{pipeline_run_id, child_run_ids}`; the freshly minted UUID is
+  stamped on every follow-on job spawned during the trigger's unwind so
+  the entire causal tree shares one correlation id (queryable via the
+  forthcoming FR-16e history endpoint). New `PipelineTriggerResponse`
+  TypedDict + Pydantic model registered for `validate_responses=True`.
+  (#2298)
+- `client.list_feed_runs(feed_id, *, limit, offset)` (sync) and
+  `await client.list_feed_runs(...)` (async) — paginated feed-run
+  history mirroring `list_agent_runs`. Returns the `run_feed` job
+  rows for the feed; the worker-internal `ingest_feed_results`
+  follow-on jobs are excluded server-side. (#2296)
+- `client.list_project_subscriptions(project_id, *, agent_id, feed_id,
+  limit, offset)` (sync) and `await client.list_project_subscriptions(...)`
+  (async) — paginated project-scoped subscriptions admin list. Returns
+  per-row admin summary fields (derived `mode`, `destination_count`,
+  `last_delivery_status`, `last_delivery_at`) so callers can build a
+  cross-agent overview without N+1 fetches. Powers the
+  `/subscriptions` page in the console. (#2297)
+- `client.run_agent(agent_id, *, input_chunks, wait, poll_s, timeout_s)`
+  (sync) and `await client.run_agent(...)` (async) gain
+  `wait=True` synchronous semantics. The default remains `wait=False`
+  (preserves today's 202-and-return behavior); opting in returns the
+  full job dict (`job_id` / `status` / `result` / `error_message`) once
+  the run reaches a terminal state. Raises `TimeoutError` past
+  `timeout_s` and `RuntimeError` on `failed` / `canceled` —
+  matching the exception contract of `upload_documents_batch(...,
+  wait=True)` and `optimize_indexes(..., wait=True)`. (#2343)
+
+### Changed
+
+- **`task_type` and `intent_fallback` are now narrowed to `Literal` aliases.**
+  Pre-#2291 the Python SDK declared both as bare `str`, so typos like
+  `task_type="exract"` only failed at the server's 422. Post-#2291 the new
+  `TaskType` and `IntentFallback` `Literal` aliases at `sdk.types.agents`
+  (re-exported from `sdk.types`) catch typos at static-analysis time. The
+  Pydantic response models (`sdk.models.agents`) and the resource method
+  signatures (`create_agent`, `update_agent` on both sync and async clients)
+  are narrowed in lockstep. The TS SDK gets symmetric `TaskType` and
+  `IntentFallback` literal unions exported from
+  `sdk-ts/src/resources/agents.ts` and re-exported from the package root
+  (`@knowledge2/sdk`) so npm consumers can import them directly. Note: the
+  TS SDK additionally corrected a pre-existing phantom-field bug on its
+  `AgentRun` interface — the Python `AgentRunListItem` TypedDict was
+  already correct and is unchanged by this PR. (#2291)
+- **`tool_config` is now a kind-discriminated tagged union.** Pre-#2307,
+  `tool_config` was a flat dict treated as webhook-only. Post-#2307 the
+  canonical shape is `{"kind": "webhook" | "mcp", "webhook": {...} | "mcp": {...}}`.
+  Two TypedDict envelopes are added (`ToolConfigWebhook`, `ToolConfigMcp`) plus
+  the helper alias `ToolConfigRequest` in `sdk.types.agents`. The legacy flat
+  shape (`{"webhook_url": "..."}`) is still accepted on write — the server
+  coerces it to the kinded shape via `_coerce_legacy_tool_config`. Response
+  shape (`ToolConfigResponseModel`) now carries `kind`, `webhook`, and `mcp`
+  fields; pre-#2307 top-level fields (`webhook_url`/`webhook_secret`/
+  `webhook_retries`) are tolerated for one minor version for SDK consumers
+  reading older API responses. The MCP kind is a stub — the server rejects
+  it at entitlement check with HTTP 403 + `feature_not_enabled` until the
+  enterprise rollout ships. Follow-up #2313 covers dropping the back-compat
+  paths once the engine is confirmed tightened. (#2307)
+- **`HarvestPolicy` enum narrowed from 5 values to 3.** Legacy aliases
+  `"always"` (equivalent to `"declared-only"`) and `"declared_and_inferred"`
+  (equivalent to `"inferred"`) are no longer accepted by the API or SDK.
+  The canonical values are now `"off"` / `"inferred"` / `"declared-only"`.
+  Existing stored values are normalised by Alembic
+  `0100_harvest_policy_dedupe`. The Python `Literal` type at
+  `sdk.types.agents.HarvestPolicy` and the TS union at
+  `sdk-ts/src/resources/agents.ts::HarvestPolicy` are narrowed in lockstep.
+  Callers using the legacy aliases will see a 422 from `create_agent` /
+  `update_agent`; switch to the canonical equivalent. (#2286)
+- `create_agent` / `async_create_agent` docstrings now recommend the
+  structured-destination flow for `task_type="notify"`: create the agent
+  without a `tool_config`, then attach destinations via
+  `create_destination(...)` against the agent's output subscription
+  (look up the subscription id via `list_subscriptions(agent_id)` first).
+  `tool_config.webhook_url` remains accepted as a generic-HTTPS shortcut
+  for backwards compat; the dispatcher fans out to both paths when both
+  are configured, so prefer one to avoid duplicate deliveries (#2241,
+  #2244).
+
+## [0.8.0] - 2026-05-04
+
+### Added
+
+- `create_corpus` and `async_create_corpus` now accept `extraction_template_id`
+  and `re_extraction_policy` keyword arguments so callers can bind an extraction
+  template at create time without a follow-up PATCH.
+- `update_corpus` and `async_update_corpus` now accept `extraction_template_id`
+  (pass `None` to unbind) and `re_extraction_policy` (`None` resets to server
+  default `"lazy"`). Both use the `NOT_GIVEN` sentinel to distinguish omit from
+  explicit `null`, preventing unintended field resets.
+- `create_agent` and `async_create_agent` accept `declared_schema`
+  (`AgentDeclaredSchema | None`) and `harvest_policy` (`HarvestPolicy | None`).
+- `update_agent` and `async_update_agent` accept `declared_schema` and
+  `harvest_policy` with `NOT_GIVEN` sentinel semantics.
+- New types exported from `sdk.types`: `AgentDeclaredSchema`, `HarvestPolicy`,
+  `NotGivenOr` — use `NOT_GIVEN` from `sdk` for update-only sentinel kwargs.
+- `NOT_GIVEN` sentinel and `_NotGiven` class are now exported from the top-level
+  `sdk` package for callers that build update payloads programmatically.
+
+### Changed
+
+- `CorpusResponse` (and the underlying Pydantic model) now includes
+  `extraction_template_id` and `re_extraction_policy` fields, matching the
+  server-side schema added in API v0.8 (#1988).
+
+## [0.7.0] - 2026-04-23
+
+### Added
+
+- Feed draft lifecycle on both `Knowledge2` and `AsyncKnowledge2`:
+  `create_feed_draft`, `get_feed_draft`, `activate_feed_draft`,
+  `discard_feed_draft`. Activation returns the updated **parent** feed;
+  the draft is deleted server-side.
+- `list_feed_subscriptions(feed_id)` — read-only view of the subscriptions
+  embedded on the feed record. Handles validated and raw-response modes,
+  passing `with_raw_response` errors through unchanged and re-wrapping
+  successful responses so status/headers survive.
+- Feed feedback helpers: `submit_feed_feedback(feed_id, *, rating,
+  chunk_id, feed_run_id)` and `get_feed_feedback_stats(feed_id, *,
+  feed_run_id=None)`. `rating` is validated client-side to be `0` or `1`.
+- New response types `FeedFeedbackSubmitResponse` and
+  `FeedFeedbackStatsResponse` exported from `sdk.types`, with matching
+  strict Pydantic models registered for `validate_responses=True`.
+- `FeedSubscriptionResponse` (and its Pydantic model) now include
+  `match_spec` and `match_spec_description` — the routing metadata
+  returned by the feed-side subscription schema for `explicit` and
+  `nl_semantic` subscriptions.
+
+### Changed
+
+- `FeedResponseModel.subscriptions` now always validates to a list
+  (previously `list | None = None`). The server contract guarantees a
+  list — empty by default — so validated clients can iterate without a
+  None check. A legacy response containing `null` for `subscriptions`
+  will now raise `ValidationError` instead of producing a `None` field.
+- `FeedSubscriptionResponseModel.agent_id` and `role` are now required
+  (previously `str | None = None`) to match the server schema and catch
+  malformed subscription payloads in validated clients.
+
+## [0.6.1] - 2026-04-17
+
+### Added
+
+- `upload_documents_batch_and_wait(...)` as the canonical blocking helper for raw-text batch ingestion
+- `wait_for_document_batch(...)` for callers that intentionally enqueue first and resolve the batch later
+
+### Changed
+
+- base installs now include `pydantic`, so `pip install knowledge2` is import-clean and supports validated response models without an extra
+- `knowledge2[pydantic]` remains accepted as a compatibility alias for older install commands
+- batch wait helpers now enforce a single end-to-end timeout budget and support `with_raw_response` correctly
+- `get_document_batch(...)` now surfaces stable `doc_ids` and live counters once a batch is visible, instead of waiting for terminal aggregation
+- refreshed the primary onboarding docs and examples to prefer the blocking batch helper and the released public contract
+- clarified early auth and quota guidance for the supported retrieval workflow
+
+## [0.6.0] - 2026-04-16
+
+### Changed
+
+- `upload_documents_batch(..., wait=False)` returns an enqueue handle with `job_id`, `batch_id`, and `count`
+- `get_document_batch(...)` is the supported batch-status lookup for raw-text uploads, including final `doc_ids` and per-item errors
+- refreshed public SDK release notes to align with the current batch-upload surface
+
+## [0.5.0] - 2026-04-13
+
+### Changed
+
+- aligned the published Python SDK support matrix with the public customer-facing surface
+- refreshed README guidance, examples, and optimize-related test coverage for the current SDK capabilities
+
+## [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
+
+- **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. Base installs now include the Pydantic model dependency.
+- **`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]`.