Metadata-Version: 2.4
Name: epo-ops-cli
Version: 0.1.0
Summary: Agent-first command-line client for the EPO OPS 3.2 API — patent search, claims, family, legal events, with built-in guardrails and JSON output
Author: epo-ops-cli contributors
License: Apache-2.0
Keywords: patents,patent-search,epo,ops,cli,ai-agents
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Legal Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# epo-ops-cli

**Agent-first command line client for the EPO OPS 3.2 API** — search patents,
read claims, walk patent families, check legal events, watch your quota.
Built-in guardrails keep bad queries from burning your quota; every command
speaks JSON.

[中文文档](README.zh-CN.md)

[![CI](https://github.com/Awakeniing/epo-ops-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Awakeniing/epo-ops-cli/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
<!-- PyPI badge: enable after the first release to PyPI
[![PyPI](https://img.shields.io/pypi/v/epo-ops-cli)](https://pypi.org/project/epo-ops-cli/)
-->

## Why this exists

The EPO publishes the world's richest patent data through its OPS API —
and ships no command-line tool for it. Existing clients are libraries, not
CLIs. `epo-ops-cli` is a small, dependency-light CLI built for the agent era:
**give any AI agent (Claude Code, Codex, Cursor, Copilot, …) this repository
and say "install per AGENTS.md" — that is the whole install guide.** Humans
can of course just type the commands.

## Quickstart

```bash
pip install .            # from a clone (PyPI release planned — see ROADMAP)
epo setup                # paste your free Consumer Key/Secret once
epo search "txt=coffee" --n 5
```

Get free credentials at [developers.epo.org](https://developers.epo.org) →
My Apps. Credentials are stored in `~/.epo/ops_config.json` and never leave
your machine except to the EPO authentication endpoint.

## Commands

| Command | What it does |
|---|---|
| `epo search "<CQL>" --n 10` | Search with titles + abstracts |
| `epo citations <PN>` | Who cites this patent (forward citations) |
| `epo abstracts <PN>...` | Batch-fetch abstracts (up to 20) |
| `epo claims <PN>` | Claims text (EP/WO) |
| `epo description <PN>` | Description text (EP/WO) |
| `epo family <PN>` | Patent family members |
| `epo legal <PN>` | Legal events |
| `epo usage` | Today's official quota consumption |

CQL fields: `ti=` title, `ab=` abstract, `pa=` applicant, `in=` inventor,
`txt=` full text (quote multi-word), `pd=` publication date, `ct=` cited-by.
Wildcards work (`spher*`), as do `AND/OR/NOT`, `pd within "2020"` and the
official `prox` operator. The full annotated catalogue lives in
[docs/CQL-FIELDS.md](docs/CQL-FIELDS.md).

## Guardrails (this tool spends your quota carefully)

- **Whitelist before requests** — an invalid field (`abs=`, `NEAR`, …) is
  rejected locally with the correct spelling in the message. Nothing is sent,
  nothing is spent.
- **Coverage awareness** — claims/description exist only for EP/WO documents;
  asking for a CN document returns a clear `skipped` note, not a 404.
- **Fair-use manners** — bulk abstracts go 10 per request with a pause between
  batches; search ranges are capped; no blind automatic retries.
- **Credential hygiene** — tokens are cached (your secret only ever travels to
  the EPO auth endpoint); every request is recorded in a local usage log.

## For agents and scripts

Every data command takes `--json`. The output contract is frozen: exit codes
`0` ok / `1` business error (JSON `error` object with a `hint`) / `2` usage
error; stdout carries data, stderr carries diagnostics; JSON field names only
ever get added. Details: [docs/OUTPUT-CONTRACT.md](docs/OUTPUT-CONTRACT.md).

```bash
epo search "ti=ice AND pa=\"lg electronics\"" --json | python -m json.tool
```

AI agents: start from [AGENTS.md](AGENTS.md) — it contains the full
install-audit-verify protocol and contribution rules for agent feedback.

## Library use

```python
from epo_ops_cli.core.client import OpsClient
from epo_ops_cli.services.search import SearchService

c = OpsClient()                       # reads ~/.epo/ops_config.json
hits = SearchService(c).search_with_abstracts('ti="ice maker"', 100)
print(hits["total"], len(hits["refs"]))
```

## The sibling project

[espacenet-cli](https://github.com/Awakeniing/espacenet-cli) drives the
[Espacenet](https://worldwide.espacenet.com) web channel instead of the OPS
API — no key needed, adds PDF download and CSV export. Use it as the fallback
when your key isn't approved yet; the two tools share design and conventions.

## Compliance

OPS is a free, registered service of the EPO subject to
[fair-use](docs/QUOTA-AND-FAIR-USE.md) rules. This is an independent,
non-official tool with no affiliation to the EPO. Large-scale retrieval
belongs on the [official bulk datasets](https://data.epo.org), not on loops
over this CLI.

## Contributing

Patent-searchers (no code required), doc writers, testers and coders are all
welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the claimable items in
[ROADMAP.md](ROADMAP.md). AI agents can contribute too, via the protocol in
AGENTS.md.

## License

[Apache-2.0](LICENSE)
