uspto-oa-cli 0.1.5

USPTO 특허 심사과정 분석 CLI — 문서 다운로드 · XML 파싱 · MD 생성

uspto-oa-cli

A CLI tool that downloads USPTO patent prosecution documents via the ODP (Open Data Portal) API, parses the XML, and converts them into structured Markdown.

Supports a workflow where the generated MD file is passed to AI agents (Claude Code, Gemini CLI, etc.) for prosecution strategy analysis.

Requirements

• Python 3.13+
• uv
• USPTO API key (issued via the ODP portal)

Installation

# pip
pip install uspto-oa-cli

# uv (global install)
uv tool install uspto-oa-cli

# uv (add as project dependency)
uv add uspto-oa-cli

# local development
uv sync

API Key Setup

# Interactive setup (recommended) — saved to ~/.oa-cli.toml
uspto-oa configure

# Show current configuration
uspto-oa configure --show

Or set via environment variable:

export USPTO_API_KEY=your_api_key_here

Usage

# 0. Check document list before downloading
uspto-oa list 16330077

# 1. Download documents (saved to file/{app_num}/)
uspto-oa download 16330077

# 2. Parse XML → generate prosecution.md
uspto-oa extract 16330077
# Output: file/16330077/16330077_prosecution.md

# Extract in JSON format
uspto-oa extract 16330077 --format json

# 3. (Optional) OCR image-based PDFs → searchable PDFs
uspto-oa ocr 16330077

# Download specific document codes only
uspto-oa download 16330077 --doc-codes CTNF,CTFR,NOA

# Force re-download (overwrite existing files)
uspto-oa download 16330077 --force

# Verbose logging
uspto-oa -v download 16330077

# One-time API key override
uspto-oa download 16330077 --api-key YOUR_KEY

Command Options

uspto-oa list <application>

Option	Description
--all	Show all documents without prosecution-related filter
--format [table|json]	Output format (default: table)
--api-key TEXT	API key

uspto-oa download <application>

Option	Description
--doc-codes CODES	Comma-separated document codes (e.g. CTNF,CTFR,NOA). All prosecution docs if omitted
--output-dir DIR	Save path (default: file/{app_num}/)
--force	Re-download even if file already exists
--api-key TEXT	API key (overrides config file and environment variable)

uspto-oa extract <application>

Option	Description
--format [md|json]	Output format (default: md)
--output-dir DIR	File directory (default: file/{app_num}/)

uspto-oa ocr <application> (requires pip install ocrmypdf)

USPTO PDF documents are full-page image scans — standard text extraction fails. This command runs OCR on every PDF in the application directory and produces searchable PDFs alongside the originals.

Option	Description
--force	Re-OCR even if output already exists
--in-place	Overwrite original PDFs instead of creating *_ocr.pdf copies
--no-deskew	Skip deskew correction (faster)
--output-dir DIR	File directory (default: file/{app_num}/)

# Install OCR dependency
pip install ocrmypdf
# or: uv pip install ocrmypdf
# or: pip install uspto-oa-cli[ocr]

# Run OCR (creates {original}_ocr.pdf next to each PDF)
uspto-oa ocr 16330077

# Overwrite originals in place
uspto-oa ocr 16330077 --in-place

Workflow

uspto-oa list {app_num}           # Check document list before downloading
    └─ Browse prosecution document codes and formats

uspto-oa download {app_num}
    └─ Save XML / PDF to file/{app_num}/

uspto-oa extract {app_num}
    └─ Generate file/{app_num}/{app_num}_prosecution.md
         └─ AI agent (Claude Code / Gemini CLI)
              └─ Prosecution strategy analysis, summaries, Q&A

uspto-oa ocr {app_num}            # Optional — for PDF-only documents
    └─ Generate {original}_ocr.pdf (searchable) next to each PDF
         └─ AI agent can now read full text from image-based PDFs

Collected Document Codes

Code	Description
CTNF	Non-Final Office Action
CTFR	Final Office Action
NOA / NACT	Notice of Allowance
REM	Remarks
ABN	Abandonment
SRNT / SRFW	Search Report
EXIN	Examiner Interview
RCE / RCEX	Request for Continued Examination
CTAV	Advisory Action
892 / 1449 / IDS	Prior Art / IDS
A*	All Amendment variants

Generated File Structure

file/{app_num}/{app_num}_prosecution.md:

Section	Content
Timeline	All documents sorted by date (XML/PDF format shown)
Office Action Details	Full rejection grounds from CTNF/CTFR
Amendment Details	Amended claims (CLM) + Remarks (REM)
Examiner Interview Details	Full EXIN text
Notice of Allowance Details	Allowed claims + Examiner's Statement
PDF-only Documents	Image PDF list (for direct AI agent delivery)

PyPI Release

uv build
uv run twine upload dist/*