feat!: 3.0.0 reads the API's 2026-10-11 shape; 2.x names kept, deprecated

.github/workflows/ci.yml

@@ -35,7 +35,11 @@ jobs:
           ruff format --check .
       - name: Type-check
         # mypy strict only on hand-written code; generated _generated/ (if added later) is excluded via pyproject.
-        run: mypy src/lenz_io
+        # The examples too: they are what people copy, so a renamed field or a
+        # wrong type there fails CI like one in the SDK.
+        run: |
+          mypy src/lenz_io
+          mypy examples
       - name: Test
         # `--no-cov` because the coverage gate lives in `addopts` and would
         # otherwise run in all eight matrix cells. Coverage does not vary

examples/core/citecheck_draft.py

@@ -0,0 +1,57 @@
+"""Check a draft's citations on their own: does each source say what the
+draft says it does?
+
+Run:
+    export LENZ_API_KEY=lenz_...
+    python examples/core/citecheck_draft.py
+
+Send a draft (its links and DOIs are read from the text; keep a link as a
+markdown link) or the statement-source pairs yourself. 1 credit per checked
+citation; a citation that could not be checked is not charged.
+"""
+
+from __future__ import annotations
+
+import os
+
+from lenz_io import CitationPair, Citecheck, CitecheckFailedError, CitecheckTimeoutError, Lenz
+
+DRAFT = (
+    "Water boils at 100 degrees Celsius at sea level, according to "
+    "[the encyclopedia entry](https://en.wikipedia.org/wiki/Boiling_point)."
+)
+
+PAIRS: list[CitationPair] = [
+    {
+        "statement": "Diamond sensors can measure temperature inside a living cell.",
+        "doi": "10.1038/nature12373",
+        "cited_year": "2013",
+    },
+]
+
+
+def report(label: str, check: Citecheck) -> None:
+    print(f"{label}: {check.outcome}")  # clean | issues_found | incomplete | unchecked
+    for row in check.citations:
+        finding = row.result.finding if row.result else "pending"
+        print(f"  {finding}: {row.cited_url or row.doi}")
+    for issue in check.citation_issues:  # most serious first
+        print(f"  ISSUE {issue.finding}: {issue.statement}")
+        if issue.snippet:
+            print(f"    The source says: {issue.snippet}")
+
+
+def main() -> None:
+    client = Lenz(api_key=os.environ.get("LENZ_API_KEY"))
+    try:
+        report("draft", client.citecheck_and_wait(DRAFT, max_citations=10))
+        report("pairs", client.citecheck_and_wait(pairs=PAIRS))
+    except CitecheckTimeoutError as exc:
+        # The check keeps running: read it later by its id, never resubmit.
+        print("Still running; read it later with client.get_citecheck:", exc.citecheck_id)
+    except CitecheckFailedError as exc:
+        print("The check failed:", exc.error_code, exc.hint)
+
+
+if __name__ == "__main__":
+    main()

examples/core/fastapi_webhook.py

@@ -1,7 +1,8 @@
+# mypy: allow-untyped-decorators
 """Receive Lenz webhook events in a FastAPI app.
 
-Lenz POSTs HMAC-signed payloads to your ``webhook_url`` when the
-verification pipeline terminates. This handler verifies the signature,
+Lenz POSTs HMAC-signed payloads to your ``webhook_url`` when a
+verification, a review or a citation check ends. This handler verifies the signature,
 parses the payload into a typed event, and dispatches per event type.
 
 Run:
@@ -22,8 +23,11 @@
 from fastapi import FastAPI, HTTPException, Request
 
 from lenz_io import (
+    CitecheckEvent,
     LenzWebhooks,
     LenzWebhookSignatureError,
+    ReviewEvent,
+    VerificationCancelled,
     VerificationCompleted,
     VerificationFailed,
     VerificationNeedsInput,
@@ -45,23 +49,57 @@ async def lenz_webhook(request: Request) -> dict[str, str]:
         logger.warning("Rejected webhook: %s", exc.message)
         raise HTTPException(status_code=400, detail=str(exc)) from exc
 
+    # A delivery can be retried: deduplicate on event.event_id (stable across
+    # attempts) before acting on it.
     if isinstance(event, VerificationCompleted):
-        # Verdict block is FLAT on event.result — no nested object.
-        logger.info(
-            "Completed: %s -> %s (lenz_score %s, confidence %s)",
-            event.verification_id,
-            event.result.get("verdict"),
-            event.result.get("lenz_score"),
-            event.result.get("confidence"),
-        )
+        # The verification as client.get_status returns it; the verdict is
+        # under .result.
+        result = event.verification.result if event.verification else None
+        if result is not None:
+            logger.info(
+                "Completed: %s -> %s (lenz_score %s, confidence %s)",
+                result.verification_id,
+                result.verdict,
+                result.lenz_score,
+                result.confidence,
+            )
         # TODO: persist verdict + sources to your DB; ping users; etc.
     elif isinstance(event, VerificationNeedsInput):
-        logger.info("Needs input on %s: %s", event.task_id, event.needs_input.get("reason"))
+        logger.info("Needs input on %s: %s", event.task_id, [c.claim for c in event.claims])
         # TODO: surface the candidate claims to the user, then call
         # client.select(task_id, claims=[...]) to resolve.
     elif isinstance(event, VerificationFailed):
-        logger.warning("Pipeline failed: %s (%s)", event.task_id, event.error)
+        failure = event.failure
+        logger.warning("Verification failed: %s (%s)", event.task_id, failure.code if failure else "unknown")
+    elif isinstance(event, VerificationCancelled):
+        # Stopped elsewhere (the website's Stop button, another process).
+        # Work submitted by an older client reports this as verification.failed
+        # with failure_class "cancelled" instead.
+        logger.info("Verification cancelled: %s", event.task_id)
+    elif isinstance(event, ReviewEvent):
+        # review.completed / review.failed / review.cancelled: the final review,
+        # as get_review returns it (event.status says which).
+        if event.review is not None:
+            logger.info(
+                "Review %s %s: outcome %s, %d issue(s)",
+                event.review_id,
+                event.status,
+                event.review.outcome,
+                len(event.review.issues),
+            )
+    elif isinstance(event, CitecheckEvent):
+        # citecheck.completed / citecheck.failed / citecheck.cancelled: the final
+        # check (event.status says which).
+        if event.citecheck is not None:
+            logger.info(
+                "Citation check %s %s: outcome %s, %d issue(s)",
+                event.citecheck_id,
+                event.status,
+                event.citecheck.outcome,
+                len(event.citecheck.citation_issues),
+            )
     else:
+        # A new event type: acknowledge it and move on.
         logger.info("Unhandled webhook event: %s", event.event)
 
     # Always return 2xx fast. Lenz expects an ack within 5s; otherwise the

examples/core/quickstart.py

@@ -1,4 +1,4 @@
-"""Lenz quickstart — the canonical four-primitive integration.
+"""Lenz quickstart — the canonical integration: the four-call ladder.
 
 Run:
     export LENZ_API_KEY=lenz_...
@@ -27,32 +27,36 @@ def main() -> None:
 
     # 1. extract — pull verifiable claims out of any text (free)
     out = client.extract(text="Sharks don't get cancer. The Eiffel Tower is 330m tall.")
-    claims = out.identified_claims or [out.claim]
+    claims = [c.claim for c in out.claims]
     print(f"Extracted {len(claims)} claims:")
     for c in claims:
         print(f"  - {c}")
     print()
 
     # 2. assess — one call over the extracted claims, one row per claim (sync)
     quick = client.assess(claims=claims).claims
-    for c in quick:
-        print(f"  {c.verdict:<12}  conf={c.confidence:<7}  {c.claim}")
-        if c.verdict == "Error":
-            # No verdict for this item — error_code says why, hint says what to send next.
-            print(f"    {c.error_code}: {c.hint}")
-        if c.identified_claims:
+    for row in quick:
+        print(f"  {row.verdict:<12}  conf={row.confidence:<7}  {row.claim}")
+        if row.status == "failed" and row.failure:
+            # No verdict for this item — failure.code says why, failure.hint says what to send next.
+            print(f"    {row.failure.code}: {row.failure.hint}")
+        if row.more_claims:
             # A compound item: only its main claim was assessed.
-            print(f"    also found (not assessed): {c.identified_claims}")
+            print(f"    also found (not assessed): {row.more_claims}")
     print()
 
     # 3. verify — escalate the low-confidence rows to the full multi-model panel
     # verify_batch_and_wait takes up to 20 claims a call: the first 20 here
-    doubtful = [{"claim": c.claim} for c in quick if c.verdict != "Error" and c.confidence == "low"][:20]
+    low = [row for row in quick if row.status == "completed" and row.confidence == "low"]
+    doubtful = [{"claim": row.claim} for row in low[:20]]
     # Fall back to the demo claim so the walkthrough always reaches steps 3
     # and 4 even when every row came back confident.
     doubtful = doubtful or [{"claim": "Sharks don't get cancer"}]
     results = client.verify_batch_and_wait(claims=doubtful)
-    v = next(r.verification for r in results if r.verification is not None)
+    v = next((r.verification for r in results if r.verification is not None), None)
+    if v is None:
+        print("No verification completed:", [r.status for r in results])
+        return
     print(f"Verdict: {v.verdict} (lenz_score {v.lenz_score}, confidence {v.confidence})")
     print(f"Summary: {v.executive_summary}")
     print()
@@ -65,7 +69,7 @@ def main() -> None:
     reply = client.ask.send(v.verification_id, message="Which source is strongest?")
     print()
     print("Q: Which source is strongest?")
-    print(f"A: {reply.reply}")
+    print(f"A: {reply.content}")
 
 
 if __name__ == "__main__":

examples/core/review_draft.py

@@ -0,0 +1,66 @@
+"""Review a draft: every claim quick-checked, the doubtful ones deep-checked.
+
+Run:
+    export LENZ_API_KEY=lenz_...
+    python examples/core/review_draft.py
+
+One call pulls the claims out of the draft, gives each a quick verdict, sends
+the ones that look wrong or uncertain through the deep check (up to five by
+default) and returns the issues with suggested rewrites. It takes two to four
+minutes; ``on_update`` shows the quick verdicts as soon as they are in.
+
+Credits: 1 per claim assessed, plus 10 per deep check (5 at ``depth="low"``),
+plus 1 per checked citation; ``review.credits.charged`` says what it cost.
+"""
+
+from __future__ import annotations
+
+import os
+
+from lenz_io import Lenz, LenzError, ReviewFailedError, ReviewFull, ReviewTimeoutError
+
+DRAFT = """
+The EU AI Act entered into force on 1 August 2024, and its obligations for
+general-purpose models applied from 2 August 2025. Fines for prohibited
+practices reach 7% of global annual turnover, according to
+[the regulation](https://eur-lex.europa.eu/eli/reg/2024/1689/oj).
+"""
+
+
+def show_progress(review: ReviewFull) -> None:
+    done = sum(1 for c in review.claims if c.assessment is not None and c.assessment.status != "pending")
+    print(f"  {review.status}: {done}/{len(review.claims)} claims have a quick verdict")
+
+
+def main() -> None:
+    client = Lenz(api_key=os.environ.get("LENZ_API_KEY"))
+    try:
+        review = client.review_and_wait(
+            DRAFT,
+            max_citations=5,  # also check the draft's first 5 sources (1 credit each)
+            suggest_edits=True,  # the smallest edits that make the draft say what each rewrite says
+            on_update=show_progress,
+        )
+    except ReviewTimeoutError as exc:
+        # The review keeps running: read it later by its id, never resubmit.
+        print("Still running; read it later with client.get_review:", exc.review_id)
+        return
+    except ReviewFailedError as exc:
+        print("The review failed:", exc.error_code, exc.hint)
+        return
+    except LenzError as exc:
+        print("Could not run the review:", exc.message, "(retryable)" if exc.retryable else "")
+        return
+
+    print(f"\nOutcome: {review.outcome}")  # clean | issues_found | incomplete | unchecked
+    for issue in review.issues:
+        print(f"- {issue.verdict} ({issue.confidence}): {issue.claim}")
+        if issue.suggested_rewrite:
+            print(f"  Suggested rewrite: {issue.suggested_rewrite}")
+    for citation in review.citation_issues:  # most serious first
+        print(f"- Source issue {citation.finding}: {citation.cited_url or citation.doi}")
+    print(f"Credits charged: {review.credits.charged if review.credits else 'unknown'}")
+
+
+if __name__ == "__main__":
+    main()

examples/core/verify_batch.py

@@ -31,14 +31,14 @@ def main() -> None:
 
     for r in results:
         if r.status == "completed" and r.verification is not None:
-            print(f"[completed] {r.claim_text} → {r.verification.verdict} ({r.verification.lenz_score})")
+            print(f"[completed] {r.claim} → {r.verification.verdict} ({r.verification.lenz_score})")
         elif r.status == "failed":
             detail = r.status_detail
-            reason = (detail.error or detail.failure_detail) if detail else "unknown"
-            print(f"[failed]    {r.claim_text} → {reason}")
+            reason = detail.failure.detail if detail and detail.failure else "unknown"
+            print(f"[failed]    {r.claim} → {reason}")
         else:
             # needs_input (resolve with client.select) or timeout (poll later)
-            print(f"[{r.status}] {r.claim_text}")
+            print(f"[{r.status}] {r.claim}")
 
 
 if __name__ == "__main__":

examples/core/verify_llm_output.py

@@ -30,39 +30,40 @@ def main() -> None:
 
     # Step 1: extract — pull the verifiable claims out of the answer (free).
     out = client.extract(text=LLM_OUTPUT)
-    claims = out.identified_claims or [out.claim]
+    claims = [c.claim for c in out.claims]
     print(f"Extracted {len(claims)} claims.\n")
 
     # Step 2: assess — one call per 20 extracted claims (extract finds up to
     # 100; one assess call takes 20), one row per claim, same order. A row
-    # with verdict "Error" got no verdict: ``error_code`` says why
-    # (``upstream_unavailable`` is worth a retry) and ``hint`` says what to
-    # send next. A compound item is assessed on its main claim and lists the
-    # rest in ``identified_claims``.
+    # with ``status == "failed"`` got no verdict: ``failure.code`` says why
+    # (``upstream_unavailable`` is worth a retry) and ``failure.hint`` says
+    # what to send next. A compound item is assessed on its main claim and
+    # lists the rest in ``more_claims``.
     quick = [row for i in range(0, len(claims), 20) for row in client.assess(claims=claims[i : i + 20]).claims]
     print(f"Assessed {len(quick)} claims:\n")
     for c in quick:
         print(f"  {c.verdict:<12}  conf={c.confidence:<7}  {c.claim}")
-        if c.verdict == "Error":
-            print(f"    {c.error_code}: {c.hint}")
-        elif c.identified_claims:
-            print(f"    also found (not assessed): {c.identified_claims}")
+        if c.status == "failed" and c.failure:
+            print(f"    {c.failure.code}: {c.failure.hint}")
+        elif c.more_claims:
+            print(f"    also found (not assessed): {c.more_claims}")
     print()
 
     # Step 3: verify — escalate the low-confidence rows to the full pipeline.
     # ``assess`` and ``verify`` share a result cache server-side, so a
     # claim that already has a deep verification surfaces immediately
     # via ``verification_url`` and you can skip the escalation.
     # verify_batch_and_wait takes up to 20 claims a call: the first 20 here
-    doubtful = [{"claim": c.claim} for c in quick if c.verdict != "Error" and c.confidence == "low"][:20]
+    low = [c for c in quick if c.status == "completed" and c.confidence == "low"]
+    doubtful = [{"claim": c.claim} for c in low[:20]]
     print(f"Escalating {len(doubtful)} low-confidence claims to full verification:\n")
     results = client.verify_batch_and_wait(claims=doubtful, timeout=180) if doubtful else []
     for r in results:
         v = r.verification
         if v is None:
-            print(f"{r.status.upper():<14} {r.claim_text}")
+            print(f"{r.status.upper():<14} {r.claim}")
             continue
-        print(f"{v.verdict.upper():<14} (lenz_score {v.lenz_score}) {r.claim_text}")
+        print(f"{v.verdict.upper():<14} (lenz_score {v.lenz_score}) {r.claim}")
         if v.verdict.lower() in ("false", "misleading") and v.sources:
             print(f"  ↳ {v.sources[0].title}")
             print(f"    {v.sources[0].url}")

pyproject.toml

@@ -33,6 +33,9 @@ dependencies = [
   # unknown Field kwarg is swallowed into json_schema_extra with a warning of
   # its own and the deprecation never fires, which is worse than the bump.
   "pydantic>=2.7",
+  # `@deprecated(..., category=None)` marks the deprecated property aliases for
+  # editors and type checkers without a runtime warning. Pydantic needs it too.
+  "typing_extensions>=4.5",
 ]
 
 [project.optional-dependencies]

scripts/hooks/pre-commit

@@ -9,7 +9,7 @@
 # Runs (~10s total on a warm cache):
 #   1. ruff check     — lint
 #   2. ruff format    — formatting
-#   3. mypy           — strict type-check on src/lenz_io
+#   3. mypy           — strict type-check on src/lenz_io and examples/
 #   4. pytest         — unit suite (skips live-API smoke; those run in CI / on release)
 #
 # Skip on a specific commit with `git commit --no-verify`. Don't habituate.
@@ -43,6 +43,7 @@ done_ok "ruff format"
 
 step "mypy (strict)"
 uv run mypy src/lenz_io || fail "mypy"
+uv run mypy examples || fail "mypy (examples)"
 done_ok "mypy"
 
 step "pytest (unit; skips live-API smoke)"