knowledge2 0.7.0__tar.gz → 0.8.0__tar.gz

{knowledge2-0.7.0 → knowledge2-0.8.0}/CHANGELOG.md

@@ -5,6 +5,154 @@ All notable changes to the Knowledge² Python SDK will be documented in this fil
 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

{knowledge2-0.7.0/knowledge2.egg-info → knowledge2-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: knowledge2
-Version: 0.7.0
+Version: 0.8.0
 Summary: Python SDK for the Knowledge² retrieval platform
 Author-email: Knowledge2 <contact@knowledge2.ai>
 License: MIT
@@ -72,7 +72,8 @@ pip install -e ".[yaml]"
 | 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 |
+| Enterprise capabilities | agents, feeds, destinations, pipelines, A2A, extraction templates |
+| Quality & schema evolution (preview) | quality (engagement, metrics, retrieval outcomes, proposals) — proposals require the `schema_evolution_enabled` org flag; metrics and retrieval-outcomes reads are ungated |
 
 The main docs and examples below focus on the core retrieval workflow.
 
@@ -142,6 +143,41 @@ counters that track admitted documents as processing advances. For broader
 operational context during a large import, you can still pair them with
 `get_corpus_status(...)`, `get_job(...)`, or document-level status checks.
 
+### Indexing semantics
+
+Uploads run in two stages and `get_corpus_status(...)` exposes both:
+
+1. **Ingestion** — chunking + embedding writes. Tracked by `ingesting`. Once
+   `ingesting=false`, all chunks for the upload are persisted.
+2. **Indexing** — the dense + sparse retrieval indexes are rebuilt. Tracked by
+   `indexing` and `search_status`. Search and chat reflect the new chunks once
+   `search_status="ready"` (or `retrieval_ready=true`).
+
+When `auto_index=True` (the default), uploads automatically queue an
+incremental index build after ingestion completes. Search keeps serving the
+previous ready index until the new one finishes — so a doc you just uploaded
+will not appear in search/chat between `ingesting=false` and
+`search_status="ready"`. Poll `get_corpus_status` for `search_status="ready"`
+(or `retrieval_ready=true`) before relying on the new chunks:
+
+```python
+import time
+
+deadline = time.monotonic() + 300  # cap the wait — adjust to your SLA
+while time.monotonic() < deadline:
+    status = client.get_corpus_status(corpus["id"])
+    if status.get("retrieval_ready") or status.get("search_status") == "ready":
+        break
+    if status.get("search_status") in ("failed", "error"):
+        raise RuntimeError(f"Index build failed: {status}")
+    time.sleep(3)
+else:
+    raise TimeoutError("Corpus did not reach search-ready before deadline")
+```
+
+If you set `auto_index=False`, call `client.sync_indexes(corpus["id"], wait=True)`
+yourself when you are ready to publish the new chunks to search.
+
 ## Improve Retrieval Quality
 
 ```python
@@ -240,19 +276,118 @@ from sdk.integrations.llamaindex import K2LlamaIndexRetriever
 
 Agents, feeds, pipelines, and A2A are available for enterprise deployments. Keep the primary examples focused on the core retrieval flow.
 
+### Agent Declared Schema and Harvest Policy (Preview)
+
+`create_agent` and `update_agent` accept a typed `declared_schema` envelope and a `harvest_policy` literal. The server requires `declared_schema` to wrap the JSON Schema under a `fields_schema` key — bare schemas are rejected with HTTP 422.
+
+```python
+agent = client.create_agent(
+    name="Case Brief Extractor",
+    corpus_id=corpus["id"],
+    task_type="extract",
+    declared_schema={
+        "fields_schema": {
+            "type": "object",
+            "properties": {
+                "court": {"type": "string"},
+                "decision_date": {"type": "string", "format": "date"},
+            },
+            "required": ["court"],
+        }
+    },
+    harvest_policy="declared-only",
+)
+```
+
+`harvest_policy` is one of `"off"`, `"inferred"`, or `"declared-only"`:
+
+- `"off"` (default) — agent runs do not harvest any output back into the corpus.
+- `"inferred"` — harvest the LLM-inferred fields (and, if `declared_schema` is set, the declared fields too) into the corpus on each run.
+- `"declared-only"` — harvest only the declared fields from `declared_schema` (no inferred fields). **Requires `declared_schema` to be set**; if it's not, no structured output is requested and the agent behaves as if `harvest_policy="off"`.
+
+The legacy aliases `"always"` (→ `"declared-only"`) and `"declared_and_inferred"` (→ `"inferred"`) were normalised by Alembic 0100_harvest_policy_dedupe and are no longer accepted as of #2286.
+
+### Running an Agent (Preview)
+
+`run_agent(...)` enqueues a background job and by default returns the 202 handle
+immediately. Pass `wait=True` to block until the run reaches a terminal state
+and receive the full job dict (including `result`):
+
+```python
+# Fire-and-forget (default) — returns {"job_id": ..., "status": "queued"}.
+run = client.run_agent(agent_id, input_chunks=[{"text": "..."}])
+
+# Synchronous — blocks until the run reaches a terminal state.
+job = client.run_agent(
+    agent_id,
+    input_chunks=[{"text": "..."}],
+    wait=True,
+    poll_s=2,
+    timeout_s=120,
+)
+envelope = job.get("result")  # AgentRunEnvelope | None: content / fields / metadata
+```
+
+`timeout_s` bounds the **full** wall-clock budget from enqueue through polling
+(a slow POST eats into the polling budget; once `timeout_s` elapses the call
+raises `TimeoutError` regardless of which phase is in flight). `wait=True`
+raises `RuntimeError` (carrying the job's `error_message` when present,
+otherwise a synthesized `"Job <id> ended with status=<status>"` string) if the
+run ends `failed` or `canceled` — same exception contract as
+`upload_documents_batch(..., wait=True)` and `optimize_indexes(...,
+wait=True)`. If the server returns a 202 without a `job_id` (contract
+violation), `wait=True` raises `RuntimeError` rather than silently returning
+the enqueue handle.
+
+Under `client.with_raw_response.run_agent(..., wait=True)` the return value is
+a `RawResponse` wrapping the terminal job (`status_code`, `headers`, and
+`parsed` dict) — the trailing `GET /v1/jobs/{id}` honors raw mode so callers
+who opt into raw responses keep getting envelopes on the wait path.
+
+### Corpus Extraction Template (Preview)
+
+> **API path convention:** All v1 endpoints use hyphens in the path. Use `/v1/extraction-templates`, not `/v1/extraction_templates`. The underscore variant returns 404.
+
+`create_corpus` and `update_corpus` accept `extraction_template_id` and `re_extraction_policy` (`"lazy"` or `"eager"`). The template must be a seed template or owned by the **target corpus/project's organization** — for ordinary org-scoped keys this is the caller's org, but global-scope/admin keys can bind templates owned by the cross-org project they're targeting.
+
+> **Typed-contract note for `declared_schema`:** `AgentDeclaredSchema` is a Python `TypedDict` with `total=False`. The server requires at least one of `fields_schema` / `metadata_schema` (an empty envelope `{}` is rejected with `422`), but `TypedDict` cannot express that constraint statically — so static type checkers will accept `declared_schema={}` even though it will fail at runtime. The TS SDK models the same constraint as a discriminated union, which **does** catch `{}` at compile time. If you need stricter Python validation, build the request through the Pydantic model layer (`sdk.models.agents.AgentDeclaredSchemaModel`) before passing it through.
+
+```python
+corpus = client.create_corpus(
+    project["id"],
+    "Legal Decisions",
+    extraction_template_id="tpl_legal_v1",
+    re_extraction_policy="eager",
+)
+```
+
+`re_extraction_policy` has no effect at create time (a fresh corpus has no documents) but is persisted so that it governs re-extraction behavior when the template binding is later changed on a non-empty corpus.
+
+To unbind a previously-bound template, pass `extraction_template_id=None` to `update_corpus(...)` — the SDK distinguishes "omit" (leave unchanged) from "explicitly null" (clear the binding) via a sentinel default. The same pattern applies to `update_agent(declared_schema=None, ...)` and `update_agent(harvest_policy=None, ...)`.
+
+### Per-corpus intent-routing kill-switch
+
+`create_corpus` and `update_corpus` accept `intent_routing_enabled` (`bool`), echoed back on `get_corpus`. It defaults to `True` (routing on — opt-out). Set it to `False` to disable the whole intent pre-pass + tiered-filter pipeline for the corpus, so chat/agent-run against it skips query classification and tier assignment entirely — useful for incident response and eval baselines. Omit the kwarg (leave `None`) on `update_corpus` to leave the current value unchanged. This is broader than a per-field hard-threshold disable, which only turns off the hard tier.
+
+```python
+client.update_corpus(corpus["id"], intent_routing_enabled=False)  # routing off
+```
+
 ### Subscription Modes (Preview)
 
-Agent-feed subscriptions support three authoring modes on `create_subscription`, gated behind the `knowledge_agents_enabled` feature flag:
+Agent-feed subscriptions support four authoring modes on `create_subscription`, gated behind the `knowledge_agents_enabled` feature flag:
 
 | Mode | Use | Required fields |
 |------|-----|-----------------|
 | `always` | Route every envelope from the feed | `feed_id`, `role` |
 | `explicit` | Evaluate a predicate DSL against the envelope | `feed_id`, `role`, `match_spec` |
 | `nl_semantic` | Describe the match in plain English; compiled server-side into a `semantic_like` predicate against `content` | `feed_id`, `role`, `match_spec_description` (10-500 chars); optional `threshold` (default 0.75) |
+| `structured` | Compose filter clauses without writing raw DSL; compiled server-side into an explicit MatchSpec | `feed_id`, `role`, `structured_filters` (list of filter dicts); optional `structured_logic` (`"and"` default or `"or"`) |
 
 The create response echoes the compiled `match_spec` and the raw `match_spec_description`, so no separate `/preview` endpoint is required:
 
 ```python
+# Natural-language mode
 sub = client.create_subscription(
     agent_id,
     feed_id=feed_id,
@@ -262,6 +397,19 @@ sub = client.create_subscription(
 )
 print(sub["match_spec"])            # compiled semantic_like predicate
 print(sub["match_spec_description"])  # raw NL description (echoed)
+
+# Structured filter mode
+sub = client.create_subscription(
+    agent_id,
+    feed_id=feed_id,
+    role="output",
+    mode="structured",
+    structured_filters=[
+        {"path": "metadata.declared.claim_type", "op": "==", "value": "theft"},
+    ],
+    structured_logic="and",
+)
+print(sub["match_spec"])  # compiled explicit predicate
 ```
 
 ### Feed Drafts, Subscriptions, and Feedback (Preview)
@@ -279,13 +427,32 @@ editing and feedback surface of the Feeds API as flat methods on `client`
 | `list_feed_subscriptions(feed_id)` | Read-only view | Returns subscriptions embedded on the feed record; use `create_subscription` on the Agents mixin to attach new ones |
 | `submit_feed_feedback(feed_id, *, rating, chunk_id, feed_run_id)` | `POST /v1/feeds/{id}/feedback` | `rating` is `1` (thumbs up) or `0` (thumbs down) |
 | `get_feed_feedback_stats(feed_id, *, feed_run_id=None)` | `GET /v1/feeds/{id}/feedback` | Optional `feed_run_id` scopes stats to a single run |
+| `backfill_feed(feed_id, *, start_from)` | `POST /v1/feeds/{id}/backfill` | Re-enqueue a backfill on an existing feed without delete-and-recreate. Resets the feed cursor and updates `start_from`. Returns `202` with `{job_id, start_from, previous_last_checked_seq}`; raises `409 feed_backfill_in_flight` if a run_feed job is already queued or running (#2328) |
 
 ```python
 draft = client.create_feed_draft(feed_id)
 client.update_feed(draft["id"], name="new name")
 client.activate_feed_draft(feed_id)  # applies the draft; returns the parent
 
+# Cron-scheduled feed (UTC; mutually exclusive with schedule_interval) — #2305
+client.create_feed(
+    project_id=project_id,
+    source_agent_id=agent_id,
+    name="weekly digest",
+    persistent=True,
+    target_corpus={"existing": corpus_id},
+    schedule_cron="0 9 * * MON",  # Mondays at 09:00 UTC
+)
+
+# execution_mode='answer' returns an LLM-generated answer over the chunks (#2303)
 run = client.run_feed(feed_id, return_results=True)
+if run.get("generated_answer"):
+    answer_text = run["generated_answer"]["content"]  # envelope shape
+
+# Re-backfill in place (#2328); the response carries the previous cursor for
+# forensic correlation in audit logs.
+client.backfill_feed(feed_id, start_from="2026-01-01T00:00:00Z")
+
 # `results` is only populated for non-persistent feeds run with
 # `return_results=True`; guard the example for safe use.
 if run.get("results"):
@@ -298,7 +465,7 @@ if run.get("results"):
 stats = client.get_feed_feedback_stats(feed_id)  # org-wide for this feed
 ```
 
-All three areas are fully mirrored on `AsyncKnowledge2` under the same names.
+All methods above are fully mirrored on `AsyncKnowledge2` under the same names.
 
 ## Error Handling
 

{knowledge2-0.7.0 → knowledge2-0.8.0}/README.md

@@ -43,7 +43,8 @@ pip install -e ".[yaml]"
 | 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 |
+| Enterprise capabilities | agents, feeds, destinations, pipelines, A2A, extraction templates |
+| Quality & schema evolution (preview) | quality (engagement, metrics, retrieval outcomes, proposals) — proposals require the `schema_evolution_enabled` org flag; metrics and retrieval-outcomes reads are ungated |
 
 The main docs and examples below focus on the core retrieval workflow.
 
@@ -113,6 +114,41 @@ counters that track admitted documents as processing advances. For broader
 operational context during a large import, you can still pair them with
 `get_corpus_status(...)`, `get_job(...)`, or document-level status checks.
 
+### Indexing semantics
+
+Uploads run in two stages and `get_corpus_status(...)` exposes both:
+
+1. **Ingestion** — chunking + embedding writes. Tracked by `ingesting`. Once
+   `ingesting=false`, all chunks for the upload are persisted.
+2. **Indexing** — the dense + sparse retrieval indexes are rebuilt. Tracked by
+   `indexing` and `search_status`. Search and chat reflect the new chunks once
+   `search_status="ready"` (or `retrieval_ready=true`).
+
+When `auto_index=True` (the default), uploads automatically queue an
+incremental index build after ingestion completes. Search keeps serving the
+previous ready index until the new one finishes — so a doc you just uploaded
+will not appear in search/chat between `ingesting=false` and
+`search_status="ready"`. Poll `get_corpus_status` for `search_status="ready"`
+(or `retrieval_ready=true`) before relying on the new chunks:
+
+```python
+import time
+
+deadline = time.monotonic() + 300  # cap the wait — adjust to your SLA
+while time.monotonic() < deadline:
+    status = client.get_corpus_status(corpus["id"])
+    if status.get("retrieval_ready") or status.get("search_status") == "ready":
+        break
+    if status.get("search_status") in ("failed", "error"):
+        raise RuntimeError(f"Index build failed: {status}")
+    time.sleep(3)
+else:
+    raise TimeoutError("Corpus did not reach search-ready before deadline")
+```
+
+If you set `auto_index=False`, call `client.sync_indexes(corpus["id"], wait=True)`
+yourself when you are ready to publish the new chunks to search.
+
 ## Improve Retrieval Quality
 
 ```python
@@ -211,19 +247,118 @@ from sdk.integrations.llamaindex import K2LlamaIndexRetriever
 
 Agents, feeds, pipelines, and A2A are available for enterprise deployments. Keep the primary examples focused on the core retrieval flow.
 
+### Agent Declared Schema and Harvest Policy (Preview)
+
+`create_agent` and `update_agent` accept a typed `declared_schema` envelope and a `harvest_policy` literal. The server requires `declared_schema` to wrap the JSON Schema under a `fields_schema` key — bare schemas are rejected with HTTP 422.
+
+```python
+agent = client.create_agent(
+    name="Case Brief Extractor",
+    corpus_id=corpus["id"],
+    task_type="extract",
+    declared_schema={
+        "fields_schema": {
+            "type": "object",
+            "properties": {
+                "court": {"type": "string"},
+                "decision_date": {"type": "string", "format": "date"},
+            },
+            "required": ["court"],
+        }
+    },
+    harvest_policy="declared-only",
+)
+```
+
+`harvest_policy` is one of `"off"`, `"inferred"`, or `"declared-only"`:
+
+- `"off"` (default) — agent runs do not harvest any output back into the corpus.
+- `"inferred"` — harvest the LLM-inferred fields (and, if `declared_schema` is set, the declared fields too) into the corpus on each run.
+- `"declared-only"` — harvest only the declared fields from `declared_schema` (no inferred fields). **Requires `declared_schema` to be set**; if it's not, no structured output is requested and the agent behaves as if `harvest_policy="off"`.
+
+The legacy aliases `"always"` (→ `"declared-only"`) and `"declared_and_inferred"` (→ `"inferred"`) were normalised by Alembic 0100_harvest_policy_dedupe and are no longer accepted as of #2286.
+
+### Running an Agent (Preview)
+
+`run_agent(...)` enqueues a background job and by default returns the 202 handle
+immediately. Pass `wait=True` to block until the run reaches a terminal state
+and receive the full job dict (including `result`):
+
+```python
+# Fire-and-forget (default) — returns {"job_id": ..., "status": "queued"}.
+run = client.run_agent(agent_id, input_chunks=[{"text": "..."}])
+
+# Synchronous — blocks until the run reaches a terminal state.
+job = client.run_agent(
+    agent_id,
+    input_chunks=[{"text": "..."}],
+    wait=True,
+    poll_s=2,
+    timeout_s=120,
+)
+envelope = job.get("result")  # AgentRunEnvelope | None: content / fields / metadata
+```
+
+`timeout_s` bounds the **full** wall-clock budget from enqueue through polling
+(a slow POST eats into the polling budget; once `timeout_s` elapses the call
+raises `TimeoutError` regardless of which phase is in flight). `wait=True`
+raises `RuntimeError` (carrying the job's `error_message` when present,
+otherwise a synthesized `"Job <id> ended with status=<status>"` string) if the
+run ends `failed` or `canceled` — same exception contract as
+`upload_documents_batch(..., wait=True)` and `optimize_indexes(...,
+wait=True)`. If the server returns a 202 without a `job_id` (contract
+violation), `wait=True` raises `RuntimeError` rather than silently returning
+the enqueue handle.
+
+Under `client.with_raw_response.run_agent(..., wait=True)` the return value is
+a `RawResponse` wrapping the terminal job (`status_code`, `headers`, and
+`parsed` dict) — the trailing `GET /v1/jobs/{id}` honors raw mode so callers
+who opt into raw responses keep getting envelopes on the wait path.
+
+### Corpus Extraction Template (Preview)
+
+> **API path convention:** All v1 endpoints use hyphens in the path. Use `/v1/extraction-templates`, not `/v1/extraction_templates`. The underscore variant returns 404.
+
+`create_corpus` and `update_corpus` accept `extraction_template_id` and `re_extraction_policy` (`"lazy"` or `"eager"`). The template must be a seed template or owned by the **target corpus/project's organization** — for ordinary org-scoped keys this is the caller's org, but global-scope/admin keys can bind templates owned by the cross-org project they're targeting.
+
+> **Typed-contract note for `declared_schema`:** `AgentDeclaredSchema` is a Python `TypedDict` with `total=False`. The server requires at least one of `fields_schema` / `metadata_schema` (an empty envelope `{}` is rejected with `422`), but `TypedDict` cannot express that constraint statically — so static type checkers will accept `declared_schema={}` even though it will fail at runtime. The TS SDK models the same constraint as a discriminated union, which **does** catch `{}` at compile time. If you need stricter Python validation, build the request through the Pydantic model layer (`sdk.models.agents.AgentDeclaredSchemaModel`) before passing it through.
+
+```python
+corpus = client.create_corpus(
+    project["id"],
+    "Legal Decisions",
+    extraction_template_id="tpl_legal_v1",
+    re_extraction_policy="eager",
+)
+```
+
+`re_extraction_policy` has no effect at create time (a fresh corpus has no documents) but is persisted so that it governs re-extraction behavior when the template binding is later changed on a non-empty corpus.
+
+To unbind a previously-bound template, pass `extraction_template_id=None` to `update_corpus(...)` — the SDK distinguishes "omit" (leave unchanged) from "explicitly null" (clear the binding) via a sentinel default. The same pattern applies to `update_agent(declared_schema=None, ...)` and `update_agent(harvest_policy=None, ...)`.
+
+### Per-corpus intent-routing kill-switch
+
+`create_corpus` and `update_corpus` accept `intent_routing_enabled` (`bool`), echoed back on `get_corpus`. It defaults to `True` (routing on — opt-out). Set it to `False` to disable the whole intent pre-pass + tiered-filter pipeline for the corpus, so chat/agent-run against it skips query classification and tier assignment entirely — useful for incident response and eval baselines. Omit the kwarg (leave `None`) on `update_corpus` to leave the current value unchanged. This is broader than a per-field hard-threshold disable, which only turns off the hard tier.
+
+```python
+client.update_corpus(corpus["id"], intent_routing_enabled=False)  # routing off
+```
+
 ### Subscription Modes (Preview)
 
-Agent-feed subscriptions support three authoring modes on `create_subscription`, gated behind the `knowledge_agents_enabled` feature flag:
+Agent-feed subscriptions support four authoring modes on `create_subscription`, gated behind the `knowledge_agents_enabled` feature flag:
 
 | Mode | Use | Required fields |
 |------|-----|-----------------|
 | `always` | Route every envelope from the feed | `feed_id`, `role` |
 | `explicit` | Evaluate a predicate DSL against the envelope | `feed_id`, `role`, `match_spec` |
 | `nl_semantic` | Describe the match in plain English; compiled server-side into a `semantic_like` predicate against `content` | `feed_id`, `role`, `match_spec_description` (10-500 chars); optional `threshold` (default 0.75) |
+| `structured` | Compose filter clauses without writing raw DSL; compiled server-side into an explicit MatchSpec | `feed_id`, `role`, `structured_filters` (list of filter dicts); optional `structured_logic` (`"and"` default or `"or"`) |
 
 The create response echoes the compiled `match_spec` and the raw `match_spec_description`, so no separate `/preview` endpoint is required:
 
 ```python
+# Natural-language mode
 sub = client.create_subscription(
     agent_id,
     feed_id=feed_id,
@@ -233,6 +368,19 @@ sub = client.create_subscription(
 )
 print(sub["match_spec"])            # compiled semantic_like predicate
 print(sub["match_spec_description"])  # raw NL description (echoed)
+
+# Structured filter mode
+sub = client.create_subscription(
+    agent_id,
+    feed_id=feed_id,
+    role="output",
+    mode="structured",
+    structured_filters=[
+        {"path": "metadata.declared.claim_type", "op": "==", "value": "theft"},
+    ],
+    structured_logic="and",
+)
+print(sub["match_spec"])  # compiled explicit predicate
 ```
 
 ### Feed Drafts, Subscriptions, and Feedback (Preview)
@@ -250,13 +398,32 @@ editing and feedback surface of the Feeds API as flat methods on `client`
 | `list_feed_subscriptions(feed_id)` | Read-only view | Returns subscriptions embedded on the feed record; use `create_subscription` on the Agents mixin to attach new ones |
 | `submit_feed_feedback(feed_id, *, rating, chunk_id, feed_run_id)` | `POST /v1/feeds/{id}/feedback` | `rating` is `1` (thumbs up) or `0` (thumbs down) |
 | `get_feed_feedback_stats(feed_id, *, feed_run_id=None)` | `GET /v1/feeds/{id}/feedback` | Optional `feed_run_id` scopes stats to a single run |
+| `backfill_feed(feed_id, *, start_from)` | `POST /v1/feeds/{id}/backfill` | Re-enqueue a backfill on an existing feed without delete-and-recreate. Resets the feed cursor and updates `start_from`. Returns `202` with `{job_id, start_from, previous_last_checked_seq}`; raises `409 feed_backfill_in_flight` if a run_feed job is already queued or running (#2328) |
 
 ```python
 draft = client.create_feed_draft(feed_id)
 client.update_feed(draft["id"], name="new name")
 client.activate_feed_draft(feed_id)  # applies the draft; returns the parent
 
+# Cron-scheduled feed (UTC; mutually exclusive with schedule_interval) — #2305
+client.create_feed(
+    project_id=project_id,
+    source_agent_id=agent_id,
+    name="weekly digest",
+    persistent=True,
+    target_corpus={"existing": corpus_id},
+    schedule_cron="0 9 * * MON",  # Mondays at 09:00 UTC
+)
+
+# execution_mode='answer' returns an LLM-generated answer over the chunks (#2303)
 run = client.run_feed(feed_id, return_results=True)
+if run.get("generated_answer"):
+    answer_text = run["generated_answer"]["content"]  # envelope shape
+
+# Re-backfill in place (#2328); the response carries the previous cursor for
+# forensic correlation in audit logs.
+client.backfill_feed(feed_id, start_from="2026-01-01T00:00:00Z")
+
 # `results` is only populated for non-persistent feeds run with
 # `return_results=True`; guard the example for safe use.
 if run.get("results"):
@@ -269,7 +436,7 @@ if run.get("results"):
 stats = client.get_feed_feedback_stats(feed_id)  # org-wide for this feed
 ```
 
-All three areas are fully mirrored on `AsyncKnowledge2` under the same names.
+All methods above are fully mirrored on `AsyncKnowledge2` under the same names.
 
 ## Error Handling
 

{knowledge2-0.7.0 → knowledge2-0.8.0}/__init__.py

@@ -8,6 +8,7 @@ from ._logging import set_debug
 from ._paging import Page, SyncPager
 from ._raw_response import RawResponse
 from ._request_options import RequestOptions
+from ._sentinels import NOT_GIVEN, NotGivenOr
 from .async_client import AsyncKnowledge2
 from .client import Knowledge2, Knowledge2Validated
 from .errors import (
@@ -42,6 +43,7 @@ def __getattr__(name: str):
 
 
 __all__ = [
+    "NOT_GIVEN",
     "APIConnectionError",
     "APIError",
     "APITimeoutError",
@@ -59,6 +61,7 @@ __all__ = [
     "Knowledge2Error",
     "Knowledge2Validated",
     "NotFoundError",
+    "NotGivenOr",
     "Page",
     "PermissionDeniedError",
     "PipelineBuilder",

knowledge2-0.8.0/_embedding_limits.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+def validate_chunking_config(config: Mapping[str, Any] | None) -> None:
+    if not config:
+        return
+    chunk_size = config.get("chunk_size")
+    overlap = config.get("overlap")
+    if chunk_size is not None and overlap is not None and int(overlap) >= int(chunk_size):
+        raise ValueError("chunking overlap must be smaller than chunk_size")