Metadata-Version: 2.4
Name: ptab-cli
Version: 0.1.11
Summary: USPTO PTAB Trial proceedings CLI — search IPR/PGR/CBM decisions from the terminal
Project-URL: Homepage, https://github.com/noaa/ptab-cli
License: MIT
License-File: LICENSE
Keywords: cli,ipr,patent,pgr,ptab,trial,uspto
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Legal Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: click>=8.0
Requires-Dist: pdfminer-six>=20221105
Requires-Dist: pypdf>=4.0
Requires-Dist: requests>=2.28
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# ptab-cli

A command-line tool for querying the USPTO Patent Trial and Appeal Board (PTAB) API directly from your terminal. Search and retrieve IPR/PGR/CBM trial proceedings, decisions, documents, appeal decisions, and interference decisions.

## Installation

```bash
pip install ptab-cli
# or
uv tool install ptab-cli
# or
pipx install ptab-cli
```

## Quick Start

```bash
# 1. Save your API key
ptab configure

# 2. Search IPR proceedings
ptab proc search --q "petitionerPartyName:Apple" --type IPR

# 3. Look up a single trial
ptab proc get IPR2023-00001

# 4. List decisions for a trial
ptab decision list IPR2023-00001
```

## API Key Setup

Priority order (highest first):

| Method | Example |
|---|---|
| CLI option | `ptab proc get IPR2023-00001 --api-key KEY` |
| Environment variable | `export USPTO_API_KEY=KEY` |
| Config file | `ptab configure` → `~/.ptab-cli.toml` |

```bash
ptab configure          # Interactive setup (API key, timeout, proxy, CA bundle)
ptab configure --show   # Show current configuration
```

Timeout follows the same priority:
- `--timeout N` global option
- `REQUEST_TIMEOUT` environment variable
- `~/.ptab-cli.toml` `[http] timeout` (default: 30s)

## Proxy & TLS Configuration

If you are behind a corporate proxy or need a custom CA bundle, run `ptab configure`
and fill in the proxy/CA fields, or edit `~/.ptab-cli.toml` directly:

```toml
[proxy]
https = "http://proxy.example.com:8080"
http  = "http://proxy.example.com:8080"

[ssl]
ca_bundle = "/path/to/ca-bundle.crt"
```

- Omitting a key leaves requests to fall back to the standard environment variables
  (`HTTPS_PROXY`, `HTTP_PROXY`, `REQUESTS_CA_BUNDLE`).
- Set `ca_bundle` to the path of a PEM file to verify against a private CA.
- Proxy and CA settings apply to every command automatically once saved.

## Commands

### proc — Trial Proceedings (IPR/PGR/CBM)

```bash
ptab proc search [--q Q] [--type IPR|PGR|CBM] [--from DATE] [--to DATE] [--limit N] [--sort FIELD]
ptab proc get TRIAL_NUMBER
ptab proc download [--q Q] [--type IPR|PGR|CBM] [--from DATE] [--to DATE] --out FILE.json
```

### decision — Trial Decisions

```bash
ptab decision search [--q Q] [--type TYPE] [--petitioner NAME] [--patent NUMBER] [--from DATE] [--to DATE]
ptab decision get DOC_ID
ptab decision list TRIAL_NUMBER [--compact]
ptab decision download [--q Q] --out FILE.json
```

### doc — Trial Documents

```bash
ptab doc search [--q Q] [--type TYPE] [--from DATE] [--to DATE]
ptab doc get DOC_ID
ptab doc list TRIAL_NUMBER [--category CATEGORY] [--party PARTY] [--type TYPE,TYPE,...] [--compact]
ptab doc pdf DOC_ID [--out FILE.pdf] [--md] [--doc-type TEXT]
ptab doc parse PDF_FILE [--out FILE.md] [--doc-type TEXT]
ptab doc fetch-case TRIAL_NUMBER [--types TYPE,TYPE,...] [--out-dir DIR] [--md] [--delay SECONDS]
ptab doc download [--q Q] --out FILE.json
```

### appeal — Appeal Decisions

```bash
ptab appeal search [--q Q] [--from DATE] [--to DATE]
ptab appeal get DOC_ID
ptab appeal list APPEAL_NUMBER
ptab appeal download [--q Q] --out FILE.json
```

### interference — Interference Decisions

```bash
ptab interference search [--q Q] [--from DATE] [--to DATE]
ptab interference get DOC_ID
ptab interference list INTERFERENCE_NUMBER
ptab interference download [--q Q] --out FILE.json
```

## PDF → Markdown Conversion

`ptab doc parse` converts a downloaded PTAB PDF into structured Markdown for use with AI coding assistants or document analysis pipelines.

```bash
# Download a document as PDF, then convert to Markdown
ptab doc pdf 171200528 --out fwd.pdf
ptab doc parse fwd.pdf

# Specify a custom output path
ptab doc parse fwd.pdf --out analysis/fwd.md

# Or do both in one step
ptab doc pdf 171200528 --out fwd.pdf --md
```

The output `.md` file includes YAML front matter (trial number, patent number, document type, date) followed by the full extracted text. Image-based (scanned) pages are automatically detected — the command saves whatever text it can extract and prints a warning with the affected page numbers, the percentage of the document they represent, and — for pages that look like an Exhibit List / appendix (roman-numeral page labels or an "Exhibit List" heading) — a separate hint distinguishing them from pages that may have lost actual body text.

> **Note:** OCR is not performed automatically. If your PDF is fully image-based, use an external OCR tool first.

> **Why this matters:** PTAB decision PDFs use font encodings that many PDF
> readers — including the built-in PDF readers of AI coding agents — render
> as garbled, letter-spaced text (e.g. "G O O G L E LLC"). `ptab doc parse`
> (and `doc pdf --md`) extract the underlying text layer correctly, so always
> read the generated `.md` file instead of the raw PDF when analyzing PTAB
> documents with an AI agent.

The `document_type` recorded in the front matter is guessed from the PDF content by default, which can be wrong. Pass `--doc-type` to record the actual type instead (e.g. the `documentTypeDescriptionText` value from `ptab doc list`); when guessed, the front matter includes `document_type_guessed: true` so you know to double-check it.

```bash
ptab doc parse fwd.pdf --doc-type "Final Written Decision"
ptab doc pdf 171200528 --md --doc-type "Institution Decision: Grant"
```

### Fetching an entire case in one command

`ptab doc fetch-case` downloads (and optionally converts) every document for a trial in a single call, instead of scripting a loop around `doc list` + `doc pdf`:

```bash
# Download everything for a trial
ptab doc fetch-case IPR2023-00001

# Only the key documents, converted to Markdown
ptab doc fetch-case IPR2023-00001 \
  --types "Petition,Institution Decision,Patent Owner Response,Final Written Decision" \
  --md

# Custom output directory and a longer delay between requests
ptab doc fetch-case IPR2023-00001 --out-dir cases/ipr-1 --md --delay 5
```

Documents are saved as `{N}_{type-slug}.pdf` in the target directory (default: `./{TRIAL_NUMBER}`), with a configurable delay between requests to stay within rate limits. With `--md`, each PDF is converted immediately using the document's own `documentTypeDescriptionText` as `--doc-type`, so the front matter is accurate without guessing. A failed document is skipped (not fatal) and the command prints a final `N/M saved` summary.

## Options

All `search` commands accept:

```
--q TEXT          Lucene query string
--from DATE       Start date (YYYY-MM-DD)
--to DATE         End date (YYYY-MM-DD)
--limit N         Maximum results (default: 25)
--offset N        Page offset (default: 0)
--sort FIELD      Sort field (e.g. "filingDate desc")
--format/-f       Output format: table | json | csv (default: table)
--out FILE        Save output to file (csv/json)
--api-key KEY     API key (one-time override)
```

Global options (placed immediately after `ptab`):

```
--verbose/-v      Debug HTTP request/response logs (stderr).
                  Also surfaces any response header containing "ratelimit"
                  (e.g. remaining quota), including on 429 responses.
--timeout N       Request timeout in seconds
--version         Show version
```

Retries with exponential backoff are built in for transient errors (429, 500, 502, 503, 504) — no need to add your own delay logic for occasional rate limiting.

## Output Formats

**table** (default) — Terminal-friendly, key fields only:

```
 Trial No.       Type  Filed       Status       Petitioner        Patent No.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 IPR2023-00001   IPR   2023-01-05  Terminated   Apple Inc.        US9876543

1 results (1 total)
```

**json** — Raw API response, pretty-printed (useful for piping)

**csv** — CSV with headers (UTF-8 BOM, for spreadsheets and data analysis)

## Examples

```bash
# Search Apple IPR filings in 2023
ptab proc search --q "petitionerPartyName:Apple" --type IPR --from 2023-01-01 --to 2023-12-31

# Get a single trial as JSON
ptab proc get IPR2023-00001 --format json

# Save Final Written Decisions to CSV
ptab decision search --type "Final Written Decision" --from 2024-01-01 --format csv --out decisions.csv

# Search decisions by petitioner name
ptab decision search --petitioner Apple --format csv --out apple_decisions.csv

# Search decisions by patent number
ptab decision search --patent US9876543

# Download Samsung IPR proceedings as JSON
ptab proc download --q "petitionerPartyName:Samsung" --type IPR --out samsung_ipr.json

# List documents for a trial
ptab doc list IPR2023-00001

# Filter documents by category (FINAL, DECISION, MOTION, Exhibit, …)
ptab doc list IPR2023-00001 --category FINAL

# Filter documents by filing party (BOARD, PETITIONER, PATENT OWNER)
ptab doc list IPR2023-00001 --party BOARD

# Combine filters
ptab doc list IPR2023-00001 --category FINAL --party BOARD

# Filter by document type (substring match, case-insensitive)
ptab doc list IPR2023-00001 --type "Institution Decision,Final Written Decision"

# Compact JSON: hoist per-trial metadata to the top level instead of
# repeating it in every item (~55% smaller for IPR2019-01238)
ptab doc list IPR2023-00001 --format json --compact
ptab decision list IPR2023-00001 --format json --compact

# Download a single document as PDF
ptab doc pdf 171200528
ptab doc pdf 171200528 --out petition.pdf

# Convert a PDF to Markdown for AI analysis
ptab doc parse petition.pdf
ptab doc parse petition.pdf --out analysis/petition.md

# Record the actual document type instead of guessing
ptab doc parse petition.pdf --doc-type "Petition"

# Fetch every key document for a case in one command
ptab doc fetch-case IPR2023-00001 --types "Petition,Institution Decision,Final Written Decision" --md

# Combine Lucene query clauses
ptab proc search --q "statusCategory:Terminated AND trialMetaData.trialTypeCode:IPR"

# Extend timeout for slow connections
ptab --timeout 60 proc search --q "petitionerPartyName:Apple"
```

## Requirements

- Python 3.11+
- USPTO PTAB API key (obtain at [developer.uspto.gov](https://developer.uspto.gov))

## License

MIT
