Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@ All notable changes to this SDK are documented here. Format follows

## [Unreleased]

### Added

- Support for audio file uploads (`.mp3`, `.m4a`, `.wav`, `.ogg`, `.webm`) and direct audio URLs across `extract_file`, `review_file`, `review_file_and_wait`, and CLI commands (`lenz extract`, `lenz review`).

### Changed

- Docs: `sr` (Serbian, answered in the Latin script) is listed among the supported `language` codes; the API now accepts it. No code change: the SDK sends `language` as given.
Expand Down
14 changes: 8 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,11 +185,12 @@ read it with `client.get_review(review_id)`, only the issues with
`client.get_review(review_id, view="issues")`, or poll it with
`client.wait_for_review(review_id)`.

**Reviewing document and image files (.docx, .pdf, .png, .jpg, .webp).** Instead of raw text, you can upload Word documents, PDFs, or images directly using `review_file` and `review_file_and_wait`. URL inputs also accept Google Docs, YouTube videos, direct PDF URLs (`.pdf`, `arxiv.org/pdf/<id>`), and direct image links alongside web articles. Pass a file path, `pathlib.Path`, open binary reader, or raw `bytes`:
**Reviewing document, image, and audio files (.docx, .pdf, .png, .jpg, .webp, .mp3, .m4a, .wav, .ogg, .webm).** Instead of raw text, you can upload Word documents, PDFs, images, or audio files directly using `review_file` and `review_file_and_wait`. URL inputs also accept Google Docs, YouTube videos, direct PDF URLs (`.pdf`, `arxiv.org/pdf/<id>`), direct image links, and direct audio links alongside web articles. Pass a file path, `pathlib.Path`, open binary reader, or raw `bytes`:

```python
# Submit and wait for a Word document, PDF, or image:
# Submit and wait for a Word document, PDF, image, or audio recording:
review = client.review_file_and_wait("report.docx")
review_audio = client.review_file_and_wait("podcast.mp3")
review_img = client.review_file_and_wait("infographic.png")

# Or submit without waiting and poll later:
Expand Down Expand Up @@ -460,7 +461,7 @@ your own claims. Use webhooks for production async flows.
## What you get on the client

- **`client.extract(text=...)`** → `ExtractedClaims`. Free, capped at 1000/account/day. Add `focus=` to narrow the list — see [Steering extract](#steering-extract) — and `locate=True` to keep only the claims traced back to your text, with their positions (each `out.claims[i].positions`). Each attempt waits up to 150s by default (a timeout is retried like any transport error, and the call's idempotency key makes the retry replay the first answer); `timeout=` overrides it for that call.
- **`client.extract_file(file=...)`** → `ExtractedClaims`. Free, capped at 1000/account/day. Extract claims directly from Word documents (`.docx`), PDFs (`.pdf`), or standalone images (`.png`, `.jpg`, `.jpeg`, `.webp`) from a file path, `pathlib.Path`, open binary reader, or raw `bytes`. Accepts the same `language=`, `focus=`, and `locate=` options as `extract`.
- **`client.extract_file(file=...)`** → `ExtractedClaims`. Free, capped at 1000/account/day. Extract claims directly from Word documents (`.docx`), PDFs (`.pdf`), standalone images (`.png`, `.jpg`, `.jpeg`, `.webp`), or audio recordings (`.mp3`, `.m4a`, `.wav`, `.ogg`, `.webm`) from a file path, `pathlib.Path`, open binary reader, or raw `bytes`. Accepts the same `language=`, `focus=`, and `locate=` options as `extract`.
- **`client.assess(claim=...)`** / **`client.assess(claims=[...])`** → `AssessResponse`. Sync. One statement (~15s; `text=` is accepted as an alias: a document is `text`, a claim is `claim`) or a list of up to 20 claims in one call (~15s) — exactly one row per claim, in order; rows that got no verdict have `status == "failed"` and a `failure` block (`failure.code`, `failure.hint`), in position and free. A single text past 20 claims lists the rest in `more_claims` (`[]` otherwise). The two forms are mutually exclusive. `timeout=` overrides the client timeout for that call (both forms default to 100s: a long text can take up to 90s).
- **`client.verify(...)`** → `TaskAccepted`. Async submit; returns a `task_id`. Get the result by polling (`client.wait(...)` / `client.get_status(...)`) or via a webhook.
- **`client.verify_and_wait(...)`** → `Verification`. Submit + poll until the pipeline lands (sync ergonomic). Equivalent to `wait(verify(...))`.
Expand Down Expand Up @@ -1530,20 +1531,21 @@ On the CLI:
lenz extract "$(cat draft.txt)" --locate
```

### Extracting from document and image files (.docx, .pdf, .png, .jpg, .webp)
### Extracting from document, image, and audio files (.docx, .pdf, .png, .jpg, .webp, .mp3, .m4a, .wav, .ogg, .webm)

Instead of raw text, extract verifiable claims directly from Word documents, PDFs, or images using `client.extract_file()`:
Instead of raw text, extract verifiable claims directly from Word documents, PDFs, images, or audio recordings using `client.extract_file()`:

```python
# Pass a file path, pathlib.Path, open binary reader, or raw bytes:
out = client.extract_file("pitch_deck.pdf", focus="market size")
out_audio = client.extract_file("interview.mp3", focus="key announcements")
out_img = client.extract_file("infographic.png")
```

On the CLI:

```bash
lenz extract pitch_deck.pdf --focus "market size"
lenz extract interview.mp3 --focus "key announcements"
```

## Multi-language output
Expand Down
2 changes: 1 addition & 1 deletion context7.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
"The client reads `LENZ_API_KEY` (`lenz_...`) from the environment by default (`Lenz()`).",
"Use `client.assess(claim=...)` or `client.assess(claims=[...])` for fast (~15s) multi-model triage returning `claims` with `verdict`, `confidence`, `rationale`, `searched_pages`, and `suggested_rewrite`.",
"Use `client.verify_and_wait(claim=...)` for deep sourced verification (takes about a minute or two, returning `verdict`, `lenz_score` 1-10 or `None` on 'No Public Record', `confidence`, `key_finding`, `executive_summary`, and `sources`).",
"Use `client.review_and_wait(text=..., max_citations=20)` (text or URL) or `client.review_file_and_wait(\"report.docx\")` to verify claims and citations across a document (`review.outcome`, `review.issues`, `review.citation_issues`).",
"Use `client.review_and_wait(text=..., max_citations=20)` or `client.review_file_and_wait(file)` (.docx, .pdf, image, audio) to verify claims and citations across a document or recording (`review.outcome`, `review.issues`, `review.citation_issues`).",
"Use `client.citecheck_and_wait(draft, max_citations=10)` or `client.citecheck_and_wait(pairs=[{\"statement\": ..., \"url\": ...}])` to verify URLs, DOIs, and legal citations (`cite`) against their sources.",
"When `verdict == \"No Public Record\"`, `lenz_score` is `None` — no public record in the evidence settles the claim, which does not make it false."
]
Expand Down
4 changes: 2 additions & 2 deletions skills/lenz-api/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Lenz checks the facts, figures, and citations in your work so you can sign off o

## Six API Calls

1. **`extract`** (`POST /api/v1/extract`, `POST /api/v1/extract/file`): Pull verifiable factual claims from text, public URLs (web pages, Google Docs, YouTube, direct PDFs/images), or uploaded files (`.docx`, `.pdf`, `.png`, `.jpg`, `.webp`). Free (1,000 calls/account/day).
1. **`extract`** (`POST /api/v1/extract`, `POST /api/v1/extract/file`): Pull verifiable factual claims from text, public URLs (web pages, Google Docs, YouTube, direct PDFs/images/audio), or uploaded files (`.docx`, `.pdf`, `.png`, `.jpg`, `.webp`, `.mp3`, `.m4a`, `.wav`, `.ogg`, `.webm`). Free (1,000 calls/account/day).
2. **`assess`** (`POST /api/v1/assess`): Fast 3-model panel verdict on 1 to 20 claims in about 15 seconds (1 credit/claim). Returns `verdict`, `confidence`, `rationale`, `searched_pages`, and `suggested_rewrite` (when `suggest_rewrite=True`).
3. **`verify`** (`POST /api/v1/verify`, `POST /api/v1/verify/batch`): Full multi-model verification pipeline with independent web research and citations in about a minute or two (10 credits standard / 5 credits at `depth="low"`). Returns `verdict`, `lenz_score` (1–10 or `null`), `confidence`, `key_finding`, `executive_summary`, and `sources`.
4. **`citecheck`** (`POST /api/v1/citecheck`): Standalone citation verification. Checks whether cited sources (`url`, `doi`, or legal `cite`) exist and support what the draft says (1 credit/checked citation).
Expand Down Expand Up @@ -144,7 +144,7 @@ for issue in review.issues:
for c in review.citation_issues:
print(c.finding, c.cited_url or c.doi, c.statement)

# File upload (.docx, .pdf, .png, .jpg, .webp) and annotated .docx export:
# File upload (.docx, .pdf, .png, .jpg, .webp, .mp3, .m4a, .wav, .ogg, .webm) and annotated .docx export:
# review_doc = client.review_file_and_wait("report.docx")
# export = client.export_review(review_doc.review_id, format="docx")
```
Expand Down
2 changes: 2 additions & 0 deletions src/lenz_io/_core.py
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,8 @@
# the first answer rather than run the extraction again. 150s leaves room
# above the slowest.
EXTRACT_TIMEOUT = 150.0
# Timeout floor for media uploads (image and audio files) and document URL inputs.
URL_TIMEOUT_FLOOR = 90.0
# Default ``timeout`` for the helpers that poll a verification to its end
# (``wait``, ``verify_and_wait``, ``verify_batch_and_wait``). A check usually
# finishes in ~90s; a slow one under load can take several minutes. A
Expand Down
16 changes: 13 additions & 3 deletions src/lenz_io/_shared.py
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ def _read_upload_file(
) -> tuple[str, bytes, str]:
"""Validate file input and resolve filename, bytes, and content type.

Accepts Word (.docx), PDF (.pdf), and image (.png, .jpg, .webp) files.
Accepts Word (.docx), PDF (.pdf), image (.png, .jpg, .webp), and audio (.mp3, .m4a, .wav, .ogg, .webm) files.
"""
file_bytes: bytes
resolved_filename: str
Expand Down Expand Up @@ -145,10 +145,20 @@ def _read_upload_file(
resolved_content_type = content_type or "image/jpeg"
elif lower_fn.endswith(".webp"):
resolved_content_type = content_type or "image/webp"
elif lower_fn.endswith(".mp3"):
resolved_content_type = content_type or "audio/mpeg"
elif lower_fn.endswith(".m4a"):
resolved_content_type = content_type or "audio/mp4"
elif lower_fn.endswith(".wav"):
resolved_content_type = content_type or "audio/wav"
elif lower_fn.endswith(".ogg"):
resolved_content_type = content_type or "audio/ogg"
elif lower_fn.endswith(".webm"):
resolved_content_type = content_type or "audio/webm"
else:
raise LenzUsageError(
f"Unsupported file format for {action}: {resolved_filename}. Only Word (.docx), PDF (.pdf), "
"and image (.png, .jpg, .webp) files are supported.",
"image (.png, .jpg, .webp), and audio (.mp3, .m4a, .wav, .ogg, .webm) files are supported.",
code="invalid_argument",
param="file",
)
Expand Down Expand Up @@ -205,7 +215,7 @@ def _prepare_review_file_multipart(
) -> tuple[dict[str, Any], dict[str, str]]:
"""Validate file input and construct httpx files and data dictionaries.

Accepts Word (.docx), PDF (.pdf), and image (.png, .jpg, .webp) files.
Accepts Word (.docx), PDF (.pdf), image (.png, .jpg, .webp), and audio (.mp3, .m4a, .wav, .ogg, .webm) files.
"""
resolved_filename, file_bytes, resolved_content_type = _read_upload_file(
file, filename=filename, content_type=content_type, action="review"
Expand Down
34 changes: 23 additions & 11 deletions src/lenz_io/async_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@
EXTRACT_TIMEOUT,
NOT_GIVEN,
NOT_SENDABLE,
URL_TIMEOUT_FLOOR,
WAIT_TIMEOUT,
CitationPair,
NotGiven,
Expand Down Expand Up @@ -1011,11 +1012,10 @@ async def extract(
retries; pin your own with ``idempotency_key=``, or pass
``idempotency=False`` to send none. Never derived from the text.

When ``text`` is one URL and the page behind it cannot be read, the
call raises :class:`LenzValidationError` (HTTP 422) with ``code``
``"page_unreadable"`` and ``fix`` ``"Paste the page's text
instead."``; it is not retried. Work that failed on our side is a 502
with ``code`` ``"internal"``.
When ``text`` is one URL (web page, Google Doc, direct PDF, image, or audio URL)
and the resource behind it cannot be read, the call raises :class:`LenzValidationError` (HTTP 422)
with ``code`` ``"page_unreadable"`` and ``fix`` ``"Paste the page's text instead."``;
it is not retried. Work that failed on our side is a 502 with ``code`` ``"internal"``.
"""
_call_options(timeout, max_retries, extra_headers, "extract()")
return await self._extract(
Expand Down Expand Up @@ -1045,7 +1045,8 @@ async def extract_file(
extra_headers: Mapping[str, str | None] | None = None,
) -> ExtractedClaims:
"""Pull verifiable claims directly out of a Word (.docx), PDF (.pdf),
or image (.png, .jpg, .webp) document. Sync, free, capped at 1000
image (.png, .jpg, .webp), or audio (.mp3, .m4a, .wav, .ogg, .webm)
document or audio recording. Sync, free, capped at 1000
calls/account/day (shared across your API keys).

``file``: a path (:class:`pathlib.Path` or ``str``), raw ``bytes``,
Expand Down Expand Up @@ -1631,8 +1632,9 @@ async def review(

``text`` is the draft (up to 50,000 characters; longer text is cut and
reported as ``summary.input_truncated``), or one public http(s) URL
(web page, Google Doc, YouTube video, direct ``.pdf`` or ``arxiv.org/pdf/<id>``
URL, or direct ``.png``/``.jpg``/``.webp`` image URL).
(web page, Google Doc, YouTube video, direct ``.pdf`` or ``arxiv.org/pdf/<id>`` URL,
direct ``.png``/``.jpg``/``.webp`` image URL, or direct ``.mp3``/``.m4a``/``.wav``/``.ogg``/``.webm``
audio URL).

Every claim in the draft gets a quick verdict (up to
``max_assessments``, default 20, most check-worthy first). The ones
Expand Down Expand Up @@ -1961,7 +1963,7 @@ async def review_file(
extra_headers: Mapping[str, str | None] | None = None,
idempotency: bool = True,
) -> ReviewStarted:
"""Submit a Word (.docx), PDF (.pdf), or image (.png, .jpg, .webp) file
"""Submit a Word (.docx), PDF (.pdf), image (.png, .jpg, .webp), or audio (.mp3, .m4a, .wav, .ogg, .webm) file
for review via multipart/form-data.

Returns a ``ReviewStarted`` receipt with a ``review_id``.
Expand All @@ -1986,6 +1988,11 @@ async def review_file(
)
job_key = _job_key(idempotency_key, idempotency)
headers = _key_header(job_key)
resolved_mime = str(files["file"][2])
lower_fn = str(files["file"][0]).lower()
is_audio = resolved_mime.startswith("audio/") or lower_fn.endswith((".mp3", ".m4a", ".wav", ".ogg", ".webm"))
is_image = resolved_mime.startswith("image/") or lower_fn.endswith((".png", ".jpg", ".jpeg", ".webp"))
floor = EXTRACT_TIMEOUT if is_audio else (URL_TIMEOUT_FLOOR if is_image else None)
body = await self._recovering(
_review_started_by_conflict,
"POST",
Expand All @@ -1995,6 +2002,7 @@ async def review_file(
headers=headers,
conflict_settles=_names_the_job("review_id"),
options=options,
floor=floor,
)
if isinstance(body, ReviewStarted):
return body
Expand Down Expand Up @@ -2027,7 +2035,7 @@ async def review_file_and_wait(
idempotency: bool = True,
cancel_on_abort: bool = False,
) -> ReviewFull:
"""Submit a Word (.docx), PDF (.pdf), or image (.png, .jpg, .webp) file
"""Submit a Word (.docx), PDF (.pdf), image (.png, .jpg, .webp), or audio (.mp3, .m4a, .wav, .ogg, .webm) file
for review and poll until it ends.

Returns the completed ``ReviewFull``.
Expand Down Expand Up @@ -2765,9 +2773,13 @@ async def _extract_file(
locate=locate,
)
headers = _key_header(idempotency_key)
resolved_mime = str(files["file"][2])
lower_fn = str(files["file"][0]).lower()
is_audio = resolved_mime.startswith("audio/") or lower_fn.endswith((".mp3", ".m4a", ".wav", ".ogg", ".webm"))
floor = 240.0 if is_audio else EXTRACT_TIMEOUT
with _carrying_key(idempotency_key, unreadable=True):
body = await self._request(
"POST", "/extract/file", files=files, data=data, headers=headers, options=options, floor=EXTRACT_TIMEOUT
"POST", "/extract/file", files=files, data=data, headers=headers, options=options, floor=floor
)
return _extracted(body, locate=locate, context=self._results)

Expand Down
7 changes: 5 additions & 2 deletions src/lenz_io/cli/commands.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@


def _is_existing_binary_file(text: str | None) -> bool:
"""Return True if *text* names an existing binary document or image file on disk.
"""Return True if *text* names an existing binary document, image, or audio file on disk.

Catches ``OSError`` (such as ``ENAMETOOLONG`` when *text* is a long literal
paragraph that happens to end in ``.pdf``) so literal text falls through to
Expand All @@ -50,7 +50,10 @@ def extract(
ctx: typer.Context,
text: str = typer.Argument(
None,
help="Text or document file (.docx, .pdf, .png, .jpg, .webp) to extract claims from ('-' or pipe = stdin).",
help=(
"Text, document, image, or audio file (.docx, .pdf, .png, .jpg, .webp, "
".mp3, .m4a, .wav, .ogg, .webm) to extract claims from ('-' or pipe = stdin)."
),
),
focus: str = typer.Option(
"",
Expand Down
29 changes: 24 additions & 5 deletions src/lenz_io/cli/review.py
Original file line number Diff line number Diff line change
Expand Up @@ -74,8 +74,9 @@ def review(
draft: str = typer.Argument(
None,
help=(
"The draft: a file path (.docx, .pdf, .png, .jpg, .webp, or text), '-' (or a pipe) for stdin, "
"or one http(s) URL (web articles, Google Docs, YouTube videos, direct PDF URLs, or direct image URLs)."
"The draft: a file path (.docx, .pdf, .png, .jpg, .webp, .mp3, .m4a, "
".wav, .ogg, .webm, or text), '-' (or a pipe) for stdin, or one http(s) URL "
"(web articles, Google Docs, YouTube videos, direct PDF URLs, direct image URLs, or direct audio URLs)."
),
),
issues: bool = typer.Option(False, "--issues", help="Print only the issues (and any failed rows)."),
Expand Down Expand Up @@ -290,17 +291,35 @@ def _parse_depth(raw: str | None) -> str | None:
return cleaned


_BINARY_DOCUMENT_EXTENSIONS: tuple[str, ...] = (
".docx",
".pdf",
".png",
".jpg",
".jpeg",
".webp",
".mp3",
".m4a",
".wav",
".ogg",
".webm",
)


def _is_binary_document(arg: str | None) -> bool:
"""Check if arg points to a binary document or image (.docx, .pdf, .png, .jpg, .jpeg, .webp)."""
"""Check if arg points to a binary document, image, or audio file
(.docx, .pdf, .png, .jpg, .jpeg, .webp, .mp3, .m4a, .wav, .ogg, .webm).
"""
if not arg or arg == "-" or _URL.match(arg.strip()):
return False
return arg.lower().endswith((".docx", ".pdf", ".png", ".jpg", ".jpeg", ".webp"))
return arg.lower().endswith(_BINARY_DOCUMENT_EXTENSIONS)


def _resolve_draft_input(arg: str | None) -> tuple[str | None, Path | None]:
"""Resolve draft argument into (text, file_path).

For binary documents and images (.docx, .pdf, .png, .jpg, .jpeg, .webp), returns (None, path).
For binary documents, images, and audio (.docx, .pdf, .png, .jpg, .jpeg,
.webp, .mp3, .m4a, .wav, .ogg, .webm), returns (None, path).
For text files, URLs, or stdin, returns (text, None).
"""
if arg is not None and _is_binary_document(arg):
Expand Down
Loading
Loading