patent-client-agents 0.2.0__tar.gz

patent_client_agents-0.2.0/.beads/.gitignore

@@ -0,0 +1,39 @@
+# SQLite databases
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Daemon runtime files
+daemon.lock
+daemon.log
+daemon.pid
+bd.sock
+sync-state.json
+last-touched
+
+# Local version tracking (prevents upgrade notification spam after git ops)
+.local_version
+
+# Legacy database files
+db.sqlite
+bd.db
+
+# Worktree redirect file (contains relative path to main repo's .beads/)
+# Must not be committed as paths would be wrong in other clones
+redirect
+
+# Merge artifacts (temporary files from 3-way merge)
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
+# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
+# They would override fork protection in .git/info/exclude, allowing
+# contributors to accidentally commit upstream issue databases.
+# The JSONL files (issues.jsonl, interactions.jsonl) and config files
+# are tracked by git by default since no pattern above ignores them.

patent_client_agents-0.2.0/.beads/README.md

@@ -0,0 +1,81 @@
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --status in_progress
+bd update <issue-id> --status done
+
+# Sync with git remote
+bd sync
+```
+
+### Working with Issues
+
+Issues in Beads are:
+- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Intelligent JSONL merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+*Beads: Issue tracking that moves at the speed of thought* ⚡

patent_client_agents-0.2.0/.beads/config.yaml

@@ -0,0 +1,62 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: load from JSONL, no SQLite, write back after each command
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# instead of SQLite database
+# no-db: false
+
+# Disable daemon for RPC communication (forces direct database access)
+# no-daemon: false
+
+# Disable auto-flush of database to JSONL after mutations
+# no-auto-flush: false
+
+# Disable auto-import from JSONL when it's newer than database
+# no-auto-import: false
+
+# Enable JSON output by default
+# json: false
+
+# Default actor for audit trails (overridden by BD_ACTOR or --actor)
+# actor: ""
+
+# Path to database (overridden by BEADS_DB or --db)
+# db: ""
+
+# Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON)
+# auto-start-daemon: true
+
+# Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)
+# flush-debounce: "5s"
+
+# Git branch for beads commits (bd sync will commit to this branch)
+# IMPORTANT: Set this for team projects so all clones use the same sync branch.
+# This setting persists across clones (unlike database config which is gitignored).
+# Can also use BEADS_SYNC_BRANCH env var for local override.
+# If not set, bd sync will require you to run 'bd config set sync.branch <branch>'.
+# sync-branch: "beads-sync"
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct JSONL
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo

patent_client_agents-0.2.0/.beads/issues.jsonl

@@ -0,0 +1,9 @@
+{"id":"ip-070","title":"Set up core module infrastructure","description":"Set up core infrastructure: base_client.py, cache.py, exceptions.py, resilience.py, tooling.py","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-06T10:46:49.155141-06:00","updated_at":"2026-01-06T10:51:43.877117-06:00","closed_at":"2026-01-06T10:51:43.877128-06:00","labels":["phase:1","type:infrastructure"]}
+{"id":"ip-0dz","title":"Implement EPO OPS client","description":"Patent families, legal status, CPC classification","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-06T10:46:57.756306-06:00","updated_at":"2026-01-06T10:56:35.639821-06:00","closed_at":"2026-01-06T10:56:35.639824-06:00","labels":["phase:3","type:feature"]}
+{"id":"ip-8js","title":"Implement JPO client","description":"Japanese patent lookup and English translations","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-06T10:47:10.934978-06:00","updated_at":"2026-01-06T10:56:35.697324-06:00","closed_at":"2026-01-06T10:56:35.697327-06:00","labels":["phase:3","type:feature"]}
+{"id":"ip-bb2","title":"Set up test infrastructure","description":"Configure pytest-asyncio, VCR-style request recording, integration test markers","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-06T10:46:52.17517-06:00","updated_at":"2026-01-06T10:56:35.46497-06:00","closed_at":"2026-01-06T10:56:35.464983-06:00","labels":["phase:1","type:testing"]}
+{"id":"ip-dtw","title":"Implement USPTO Assignments client","description":"Ownership lookup, assignment chain traversal","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-06T10:46:54.891412-06:00","updated_at":"2026-01-06T10:56:35.582979-06:00","closed_at":"2026-01-06T10:56:35.582982-06:00","labels":["phase:2","type:feature"]}
+{"id":"ip-g1f","title":"Implement USPTO Publications client","description":"Full-text search, patent/application lookup, claims and description access","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-06T10:46:53.638789-06:00","updated_at":"2026-01-06T10:56:35.524451-06:00","closed_at":"2026-01-06T10:56:35.524454-06:00","labels":["phase:2","type:feature"]}
+{"id":"ip-q0j","title":"Configure Claude Code plugin","description":"Plugin manifest, marketplace configuration, installation workflow","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-06T10:47:13.894843-06:00","updated_at":"2026-01-06T10:52:04.857349-06:00","closed_at":"2026-01-06T10:52:04.857351-06:00","labels":["phase:4","type:infrastructure"]}
+{"id":"ip-rv4","title":"Create IP Research skill","description":"Claude Code skill for natural language patent research queries","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-06T10:47:12.444263-06:00","updated_at":"2026-01-06T10:52:04.915617-06:00","closed_at":"2026-01-06T10:52:04.915619-06:00","labels":["phase:4","type:skill"]}
+{"id":"ip-zlx","title":"Implement Google Patents client","description":"Implement GooglePatentsClient: fetch by patent number, search, citation graph, Pydantic models","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-06T10:46:50.943909-06:00","updated_at":"2026-01-06T10:52:04.97252-06:00","closed_at":"2026-01-06T10:52:04.972523-06:00","labels":["phase:1","type:feature"]}

patent_client_agents-0.2.0/.beads/metadata.json

@@ -0,0 +1,5 @@
+{
+  "database": "beads.db",
+  "jsonl_export": "issues.jsonl",
+  "last_bd_version": "0.27.0"
+}

patent_client_agents-0.2.0/.cache/hishel/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by Hishel
+*

patent_client_agents-0.2.0/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "patent-client-agents",
+  "description": "Intellectual property research toolkit — async Python clients and 63 MCP tools for USPTO, EPO, Google Patents, JPO, MPEP, and CPC",
+  "version": "0.2.0",
+  "author": {
+    "name": "Parker Hancock",
+    "url": "https://github.com/parkerhancock"
+  },
+  "repository": "https://github.com/parkerhancock/ip_tools",
+  "license": "Apache-2.0",
+  "keywords": ["patent", "trademark", "intellectual-property", "uspto", "epo", "mcp"],
+  "skills": "src/ip_tools/skills",
+  "mcpServers": {
+    "patent-client-agents": {
+      "command": "uvx",
+      "args": ["--from", "${CLAUDE_PLUGIN_ROOT}[mcp]", "patent-client-agents-mcp"]
+    }
+  }
+}

patent_client_agents-0.2.0/.gitattributes

@@ -0,0 +1,3 @@
+
+# Use bd merge for beads JSONL files
+.beads/issues.jsonl merge=beads

patent_client_agents-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run ruff check
+        run: uv run ruff check .
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run type checking
+        run: uv run ty check src/
+        continue-on-error: true  # Type errors don't fail CI yet
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests with coverage
+        run: |
+          uv pip install pytest-cov
+          uv run pytest --cov=ip_tools --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          fail_ci_if_error: false

patent_client_agents-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Type checking
+.ty_cache/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+

patent_client_agents-0.2.0/.gitleaks.toml

@@ -0,0 +1,21 @@
+# Gitleaks configuration for patent-client-agents.
+#
+# Extends the default rule set and allowlists specific upstream documentation
+# files that contain illustrative placeholders and example URLs published by
+# USPTO / JPO / EPO themselves. These aren't secrets we control, and the
+# files are imported verbatim from upstream — reviewing them for leaks here
+# is redundant and produces false positives every time upstream ships new
+# examples.
+
+[extend]
+useDefault = true
+
+[[allowlists]]
+description = "Upstream USPTO / JPO / EPO OpenAPI specs and reference bundles"
+paths = [
+    '''resources/uspto/uspto_odp_swagger\.yaml''',
+    '''resources/epo/en-ops\.txt''',
+    '''resources/jpo/jpo_api_openapi\.json''',
+    '''resources/jpo/jpo_api_reference_e\.js''',
+    '''src/ip_tools/uspto_odp/data/odp_swagger\.yaml''',
+]

patent_client_agents-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: catalog-lint
+        name: Lint catalog pages against _TEMPLATE.md
+        entry: uv run python scripts/lint_catalog.py
+        language: system
+        pass_filenames: false
+        files: ^(src/ip_tools/catalog/|CATALOG\.md$)
+
+  # ty type checker disabled in pre-commit due to external library type issues
+  # Run manually with: uv run ty check src/ip_tools/

patent_client_agents-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

patent_client_agents-0.2.0/CATALOG.md

@@ -0,0 +1,39 @@
+# Patent & IP Data Connector Catalog
+
+Canonical index of the patent and IP data sources shipped by `patent-client-agents`.
+
+## Active connectors
+
+| Source | Description | Auth | MCP Tools | Downloads | Rate Limit |
+|---|---|---|---:|:---:|---|
+| [Google Patents](src/ip_tools/catalog/google-patents.md) | Global patent search, claims, figures, PDFs, families | None | 8 | ✓ | Unpublished (scraped) |
+| [USPTO ODP](src/ip_tools/catalog/uspto-odp.md) | Applications, file wrapper, PTAB trials/appeals/interferences, petitions, bulk data via Open Data Portal | `USPTO_ODP_API_KEY` | 26 | ✓ | 60 req/min |
+| [USPTO Applications](src/ip_tools/catalog/uspto-applications.md) | Function-level wrapper over `ApplicationsClient` (search, get, documents, family, PTAB) | `USPTO_ODP_API_KEY` | — | — | (inherits ODP) |
+| [USPTO Office Actions](src/ip_tools/catalog/uspto-office-actions.md) | OA rejection analytics, cited references, full-text OA retrieval, enriched citations | `USPTO_ODP_API_KEY` | 4 | — | 60 req/min |
+| [USPTO Publications](src/ip_tools/catalog/uspto-publications.md) | Patent Public Search (PPUBS) full-text and document retrieval | None | 4 | ✓ | Unpublished |
+| [USPTO Assignments](src/ip_tools/catalog/uspto-assignments.md) | Patent ownership transfers via Assignment Center | None | 7 | — | Unpublished |
+| [USPTO Petitions](src/ip_tools/catalog/uspto-petitions.md) | Wrapper for ODP petition decisions | `USPTO_ODP_API_KEY` | — | — | (inherits ODP) |
+| [USPTO Bulk Data](src/ip_tools/catalog/uspto-bulkdata.md) | Bulk data product catalog + download manifests | `USPTO_ODP_API_KEY` | — | — | (inherits ODP) |
+| [EPO OPS](src/ip_tools/catalog/epo-ops.md) | European patents — biblio, fulltext, families, legal events | `EPO_OPS_API_KEY` + `EPO_OPS_API_SECRET` | 12 | ✓ | 4 GB/week free tier |
+| [CPC](src/ip_tools/catalog/cpc.md) | Cooperative Patent Classification lookup / search / IPC mapping (via EPO OPS) | `EPO_OPS_API_KEY` + `EPO_OPS_API_SECRET` | 3 | — | (inherits EPO OPS) |
+| [MPEP](src/ip_tools/catalog/mpep.md) | Manual of Patent Examining Procedure search and section lookup | None | 2 | — | Unpublished (scraped) |
+
+**Wrapper modules** — `uspto_applications`, `uspto_petitions`, and
+`uspto_bulkdata` expose module-level functions that route through the same
+underlying `UsptoOdpClient`. Their MCP tools are counted under
+[uspto-odp](src/ip_tools/catalog/uspto-odp.md).
+
+## Inactive / deprecated
+
+| Source | Status | Notes |
+|---|---|---|
+| [JPO](src/ip_tools/catalog/jpo.md) | Disabled | Module present; requires `JPO_API_USERNAME` + `JPO_API_PASSWORD` which are not broadly available. All clients skip at runtime if credentials are absent. |
+| [patentsview](archive/patentsview/) | Deprecated | USPTO retired the PatentsView API (search.patentsview.org no longer resolves); module kept in `archive/` for reference only. |
+
+## By auth type
+
+**No credentials required:** Google Patents, USPTO Publications, USPTO Assignments, MPEP.
+
+**Free API key:** USPTO ODP (and wrappers — Applications, Office Actions, Petitions, Bulk Data) via `USPTO_ODP_API_KEY`; EPO OPS and CPC via `EPO_OPS_API_KEY` + `EPO_OPS_API_SECRET`.
+
+**Credentialed / disabled:** JPO via `JPO_API_USERNAME` + `JPO_API_PASSWORD`.

patent_client_agents-0.2.0/CLAUDE.md

@@ -0,0 +1,77 @@
+# IP Tools
+
+Async Python library for patent and IP data from USPTO, EPO, Google Patents, and JPO.
+
+## Development
+
+```bash
+uv sync --group dev              # Install dependencies
+uv run pytest                    # Run tests (767 tests, ~15s)
+uv run ruff check src/ tests/    # Lint
+uv run ruff format src/ tests/   # Format
+```
+
+## Testing
+
+Tests use `vcrpy` to replay recorded HTTP interactions. Cassettes live at
+`tests/cassettes/` with filenames derived from each test's nodeid.
+
+```bash
+uv run pytest                                # Replay from cassettes (default)
+uv run pytest --vcr-record=once              # Record missing cassettes
+uv run pytest --vcr-record=all               # Re-record all cassettes
+uv run pytest --run-live-uspto               # Run live USPTO tests
+uv run pytest --run-live-jpo                 # Run live JPO tests
+uv run pytest --cov=ip_tools --cov-report=term-missing  # Coverage
+```
+
+When recording new cassettes, ensure auth headers are scrubbed. The conftest
+redacts `authorization`, `x-api-key`, `api_key`, and `apiKey` automatically;
+verify with `gitleaks protect --staged` before committing.
+
+## Architecture
+
+```
+src/
+  law_tools_core/           # Shared HTTP scaffolding (BaseAsyncClient, cache, retry,
+                            #   exceptions, logging). Shipped in the same wheel.
+  ip_tools/
+    uspto_odp/              # USPTO Open Data Portal — applications, PTAB, petitions
+                            #   (needs USPTO_ODP_API_KEY)
+    uspto_applications/     # High-level wrapper over ODP applications endpoints
+    uspto_publications/     # USPTO Public Search (PPUBS)
+    uspto_assignments/      # USPTO Assignment Center records
+    uspto_petitions/        # USPTO petitions API
+    uspto_bulkdata/         # USPTO bulk data product catalog
+    uspto_office_actions/   # Office-action rejections, citations, full text
+    epo_ops/                # EPO Open Patent Services (needs EPO_OPS_API_KEY/SECRET)
+    google_patents/         # Scrapes Google Patents (no API key)
+    jpo/                    # Japan Patent Office (needs JPO_API_USERNAME/PASSWORD)
+    cpc/                    # CPC classification lookups (via EPO OPS)
+    mpep/                   # Manual of Patent Examining Procedure search
+    skills/ip_research/     # Skill content packaged with the wheel; downstream
+                            #   consumers can read it via importlib.resources.
+archive/                    # Deprecated modules kept for reference, not shipped.
+                            #   (patentsview: upstream API retired by USPTO.)
+```
+
+## Error Handling
+
+Log-first pattern for API errors: `ApiError.__str__()` appends the log-file
+path so agents can inspect details without keeping full stacktraces in
+context. Base class `LawToolsCoreError` (from `law_tools_core.exceptions`)
+and plain validation/config errors use vanilla `Exception.__str__`.
+
+File logging is configured per consumer app via
+`law_tools_core.logging.configure(app_name)`. `ip_tools` calls
+`configure("ip_tools")` on import → `~/.cache/ip_tools/ip_tools.log`.
+
+## Key Conventions
+
+- All clients extend `law_tools_core.BaseAsyncClient` and use async context managers.
+- HTTP caching: `hishel` + SQLite with WAL pragmas via `RetryingAsyncSqliteStorage`.
+- Retry: `tenacity` `default_retryer` (4 attempts, exponential jitter).
+- Models are Pydantic v2.
+- The skill is packaged inside the wheel at `ip_tools/skills/ip_research/` so
+  `importlib.resources.files("ip_tools") / "skills" / "ip_research"` works
+  regardless of filesystem layout.