ip_research

IP Research

Async Python clients for patent and IP data. All clients use async with context managers. All shared scaffolding (HTTP, cache, retry, errors) lives in law_tools_core, shipped in the same wheel.

Routing

Task	Client / Module	Reference
Patent lookup / search by keywords	google_patents.GooglePatentsClient	google_patents.md
USPTO application status + file wrapper	uspto_odp.ApplicationsClient	uspto_odp.md
USPTO application high-level API	patent_client_agents.uspto_applications	uspto_applications.md
USPTO PTAB (IPR/PGR/CBM, ex parte appeals, interferences)	uspto_odp.PtabTrialsClient / PtabAppealsClient / PtabInterferencesClient	uspto_odp.md
USPTO petitions	uspto_odp.PetitionsClient or patent_client_agents.uspto_petitions	uspto_petitions.md
USPTO bulk data products	uspto_odp.BulkDataClient or patent_client_agents.uspto_bulkdata	uspto_bulkdata.md
USPTO assignments	uspto_assignments.AssignmentCenterClient	uspto_assignments.md
USPTO publications (PPUBS) full-text	uspto_publications.PublicSearchClient	uspto_publications.md
USPTO office actions	patent_client_agents.uspto_office_actions	uspto_office_actions.md
EPO bibliographic / family / legal events	epo_ops.EpoOpsClient	epo_ops.md
JPO application status	jpo.JpoClient	jpo.md
MPEP search + section lookup	patent_client_agents.mpep	mpep.md
CPC lookup / search / mapping	patent_client_agents.cpc	cpc.md

Quick Examples

Lookup patent by number

from patent_client_agents.google_patents import GooglePatentsClient

async with GooglePatentsClient() as client:
    patent = await client.get_patent_data("US10123456B2")

Search USPTO applications

from patent_client_agents.uspto_odp import ApplicationsClient

async with ApplicationsClient() as client:  # Requires USPTO_ODP_API_KEY
    results = await client.search(query="inventionTitle:laser", limit=25)
    for record in results.applicationBag:
        print(record.applicationNumberText, record.filingDate)

Find PTAB proceedings

from patent_client_agents.uspto_odp import PtabTrialsClient

async with PtabTrialsClient() as client:
    proceedings = await client.search_proceedings(query="patent:US10123456")

Look up MPEP section

from patent_client_agents.mpep import SearchInput, search

response = await search(SearchInput(query="obviousness rejection", per_page=10))
for hit in response.hits:
    print(hit.section_id, hit.title)

Resolve a CPC symbol

from patent_client_agents.cpc import retrieve_cpc

entry = await retrieve_cpc(symbol="H04L63/08", ancestors=True)

Error Handling

All clients raise typed exceptions from law_tools_core.exceptions. ApiError and its subclasses include a path to the log file in their string representation so agents can inspect stacktraces without keeping them in context.

from law_tools_core.exceptions import (
    LawToolsCoreError,
    NotFoundError,
    RateLimitError,
)

try:
    async with GooglePatentsClient() as client:
        patent = await client.get_patent_data("US99999999")
except NotFoundError as e:
    print(e)  # "... (HTTP 404, details: ~/.cache/patent_client_agents/patent_client_agents.log)"
except RateLimitError as e:
    if e.retry_after:
        await asyncio.sleep(e.retry_after)
except LawToolsCoreError as e:
    print(e)  # Fallback for any other typed error

Exception hierarchy (from law_tools_core.exceptions):

Exception	When
NotFoundError	Resource not found (404)
RateLimitError	Rate limit exceeded (429); retry_after set if server supplied it
AuthenticationError	Bad or missing API credentials (401/403)
ServerError	Remote API 5xx
ApiError	Other HTTP errors (base for all HTTP-level errors; appends log path)
ParseError	Failed to parse response data
ConfigurationError	Missing API key / invalid config
ValidationError	Invalid input; also inherits ValueError
LawToolsCoreError	Base for all typed errors

Log file: ~/.cache/patent_client_agents/patent_client_agents.log — full tracebacks, request/response details, debug info. Read this when concise error messages aren't enough.

Environment Variables

Variable	Required For
USPTO_ODP_API_KEY	All USPTO ODP clients (Applications, PTAB, BulkData, Petitions, Office Actions)
EPO_OPS_API_KEY	EPO OPS, CPC (CPC uses EPO OPS under the hood)
EPO_OPS_API_SECRET	EPO OPS, CPC
JPO_API_USERNAME	JPO client
JPO_API_PASSWORD	JPO client

USPTO Publications, USPTO Assignments, Google Patents, and MPEP require no API key.

Cache Management

All clients cache HTTP responses to ~/.cache/patent_client_agents/ using hishel with a SQLite backend and WAL pragmas. See cache.md for TTL, invalidation, and statistics APIs.

Issue Reporting

Source: parkerhancock/ip_tools

Report bugs with version, minimal reproduction code, and relevant API response if applicable.

References

• google_patents.md — Full-text search, patent documents, citations
• uspto_odp.md — Applications, PTAB, bulk data, petitions
• uspto_applications.md — High-level applications API
• uspto_petitions.md — Petition decisions
• uspto_bulkdata.md — Bulk data product catalog
• uspto_office_actions.md — Office action analytics
• uspto_assignments.md — Assignment/ownership lookup
• uspto_publications.md — PPUBS full-text
• epo_ops.md — EPO bibliographic, family, legal status
• jpo.md — Japan Patent Office
• mpep.md — Manual of Patent Examining Procedure
• cpc.md — CPC classification lookup
• cache.md — Cache management