Metadata-Version: 2.5
Name: librarian-uspto
Version: 0.1.0
Summary: USPTO patent search backend for librarian: granted patents and published applications through the USPTO Open Data Portal API
Project-URL: Homepage, https://github.com/kevin-j-smith/librarian-uspto
Project-URL: Source, https://github.com/kevin-j-smith/librarian-uspto
Project-URL: Issues, https://github.com/kevin-j-smith/librarian-uspto/issues
Project-URL: Changelog, https://github.com/kevin-j-smith/librarian-uspto/blob/main/CHANGELOG.md
Project-URL: librarian, https://github.com/kevin-j-smith/librarian
Author: Kevin J. Smith
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: librarian,patents,plugin,research,uspto
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# librarian-uspto

A **patent search backend** for [librarian](https://github.com/kevin-j-smith/librarian)'s
research loop: granted US patents and published applications through the
USPTO Open Data Portal (ODP) API. It answers librarian's `science` category,
so patents reach the research selector beside papers.

Why: in librarian's search comparison, 5 of the 7 trusted sources WebSearch
found for a camera-tracking topic were USPTO patents, and SearXNG ships no
patent engine.

## Install

Install **into the same environment as librarian**, then route `science` to
it with your other science sources:

```bash
uv pip install librarian-uspto
```

```ini
# librarian's .env
USPTO_API_KEY=...          # an ODP key (data.uspto.gov); sent as X-API-KEY
RESEARCH_SEARCH_ROUTES=web: searxng; video: searxng; science: scholarly, uspto, searxng
```

Without `USPTO_API_KEY` a search returns nothing, says why, and sends
nothing.

## What it searches, and why that way

What ODP's search said on October 1, 2026:

- It covers application **metadata** (title, numbers, dates, applicant,
  classification), not abstracts or claims.
- Free text matches any word in any field: "camera tracking solver" matched
  106,891 records, the first five titled "Camera".
- Results come newest first, not by relevance, and a search with no hits
  answers 404.

So this backend searches **titles**. It first asks for titles naming every
content word of the topic, each as a prefix ("solver" matches "solving"),
among applications with public text (a patent or publication number). When
none match, it asks for titles naming any n-1 of the n words, then any n-2,
each step one request (`USPTO_MAX_ATTEMPTS`, 4). librarian's science ranking
then puts the titles that name the most of the topic first.

Each result links to the whole document as a PDF on image-ppubs.uspto.gov (a
granted patent by number, a published application by publication number),
which librarian ingests as one document, with OCR when its pages are scans.
The snippet carries the number, dates, applicant, and first CPC
classifications; ODP returns no abstract to show.

## Settings

| Setting | Default | What it does |
|---|---|---|
| `USPTO_API_KEY` | empty | Your ODP API key |
| `USPTO_MAX_ATTEMPTS` | 4 | Requests one search may make while broadening |
| `USPTO_MIN_INTERVAL_SECONDS` | 1.1 | Seconds between requests |
| `USPTO_COOLDOWN_SECONDS` | 600 | How long a refusal (429, 503) stops requests, doubling while it repeats, unless the reply sends Retry-After |
| `USPTO_TIMEOUT_SECONDS` | 30 | Per request |

Replies, and searches that found nothing, are cached with librarian's search
cache; the key is sent in a header and never cached.

## License

Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
