@synsci/cli-darwin-x64-baseline 1.1.76 → 1.1.78

package/bin/skills/uspto-database/references/additional_apis.md

@@ -0,0 +1,394 @@
+# Additional USPTO APIs Reference
+
+## Overview
+
+Beyond patent search, PEDS, and trademarks, USPTO provides specialized APIs for citations, office actions, assignments, litigation, and other patent data.
+
+## 1. Enriched Citation API
+
+### Overview
+
+Provides insights into patent evaluation processes and cited references for the IP5 (USPTO, EPO, JPO, KIPO, CNIPA) and public use.
+
+**Versions:** v3, v2, v1
+
+**Base URL:** Access through USPTO Open Data Portal
+
+### Purpose
+
+Analyze which references examiners cite during patent examination and how patents cite prior art.
+
+### Key Features
+
+- **Forward citations** - Patents that cite a given patent
+- **Backward citations** - References cited by a patent
+- **Examiner citations** - References cited by examiner vs. applicant
+- **Citation context** - How and why references are cited
+
+### Use Cases
+
+- Prior art analysis
+- Patent landscape analysis
+- Identifying related technologies
+- Assessing patent strength based on citations
+
+## 2. Office Action APIs
+
+### 2.1 Office Action Text Retrieval API
+
+**Version:** v1
+
+### Purpose
+
+Retrieves complete full-text office action correspondence documents for patent applications.
+
+### Features
+
+- Full text of office actions
+- Restrictions, rejections, objections
+- Examiner amendments
+- Search information
+
+### Example Use
+
+```python
+# Retrieve office action text by application number
+def get_office_action_text(app_number, api_key):
+    """
+    Fetch full text of office actions for an application.
+    Note: Integrate with PEDS to identify which office actions exist.
+    """
+    # API implementation
+    pass
+```
+
+### 2.2 Office Action Citations API
+
+**Versions:** v2, beta v1
+
+### Purpose
+
+Provides patent citation data extracted from office actions, showing which references examiners used during examination.
+
+### Key Data
+
+- Patent and non-patent literature citations
+- Citation context (rejection, information, etc.)
+- Examiner search strategies
+- Prosecution research dataset
+
+### 2.3 Office Action Rejection API
+
+**Versions:** v2, beta v1
+
+### Purpose
+
+Details rejection reasons and examination outcomes with bulk rejection data through March 2025.
+
+### Rejection Types
+
+- **35 U.S.C. § 102** - Anticipation (lack of novelty)
+- **35 U.S.C. § 103** - Obviousness
+- **35 U.S.C. § 112** - Enablement, written description, indefiniteness
+- **35 U.S.C. § 101** - Subject matter eligibility
+
+### Use Cases
+
+- Analyze common rejection reasons
+- Identify problematic claim language
+- Prepare responses based on historical data
+- Portfolio analysis of rejection patterns
+
+### 2.4 Office Action Weekly Zips API
+
+**Version:** v1
+
+### Purpose
+
+Delivers bulk downloads of full-text office action documents organized by weekly release schedules.
+
+### Features
+
+- Weekly archive downloads
+- Complete office action text
+- Bulk access for large-scale analysis
+
+## 3. Patent Assignment Search API
+
+### Overview
+
+**Version:** v1.4
+
+Accesses USPTO patent assignment database for ownership records and transfers.
+
+**Base URL:** `https://assignment-api.uspto.gov/patent/`
+
+### Purpose
+
+Track patent ownership, assignments, security interests, and corporate transactions.
+
+### Search Methods
+
+#### By Patent Number
+
+```
+GET /v1.4/assignment/patent/{patent_number}
+```
+
+#### By Application Number
+
+```
+GET /v1.4/assignment/application/{application_number}
+```
+
+#### By Assignee Name
+
+```
+POST /v1.4/assignment/search
+{
+  "criteria": {
+    "assigneeName": "Company Name"
+  }
+}
+```
+
+### Response Format
+
+Returns XML with assignment records similar to trademark assignments:
+
+- Reel/frame numbers
+- Conveyance type
+- Dates (execution and recorded)
+- Assignors and assignees
+- Affected patents/applications
+
+### Common Uses
+
+```python
+def track_patent_ownership(patent_number, api_key):
+    """Track ownership history of a patent."""
+    url = f"https://assignment-api.uspto.gov/patent/v1.4/assignment/patent/{patent_number}"
+    headers = {"X-Api-Key": api_key}
+
+    response = requests.get(url, headers=headers)
+    if response.status_code == 200:
+        # Parse XML to extract assignment history
+        return response.text
+    return None
+
+def find_company_patents(company_name, api_key):
+    """Find patents assigned to a company."""
+    url = "https://assignment-api.uspto.gov/patent/v1.4/assignment/search"
+    headers = {"X-Api-Key": api_key}
+    data = {"criteria": {"assigneeName": company_name}}
+
+    response = requests.post(url, headers=headers, json=data)
+    return response.text
+```
+
+## 4. PTAB API (Patent Trial and Appeal Board)
+
+### Overview
+
+**Version:** v2
+
+Access to Patent Trial and Appeal Board proceedings data.
+
+### Purpose
+
+Retrieve information about:
+- Inter partes review (IPR)
+- Post-grant review (PGR)
+- Covered business method (CBM) review
+- Ex parte appeals
+
+### Data Available
+
+- Petition information
+- Trial decisions
+- Final written decisions
+- Petitioner and patent owner information
+- Claims challenged
+- Trial outcomes
+
+### Note
+
+Currently migrating to new Open Data Portal. Check current documentation for access details.
+
+## 5. Patent Litigation Cases API
+
+### Overview
+
+**Version:** v1
+
+Contains 74,623+ district court litigation records covering patent litigation data.
+
+### Purpose
+
+Access federal district court patent infringement cases.
+
+### Key Data
+
+- Case numbers and filing dates
+- Patents asserted
+- Parties (plaintiffs and defendants)
+- Venues
+- Case outcomes
+
+### Use Cases
+
+- Litigation risk analysis
+- Identify frequently litigated patents
+- Track litigation trends
+- Analyze venue preferences
+- Assess patent enforcement patterns
+
+## 6. Cancer Moonshot Patent Data Set API
+
+### Overview
+
+**Version:** v1.0.1
+
+Specialized dataset for cancer-related patent discoveries.
+
+### Purpose
+
+Search and download patents related to cancer research, treatment, and diagnostics.
+
+### Features
+
+- Curated cancer-related patents
+- Bulk data download
+- Classification by cancer type
+- Treatment modality categorization
+
+### Use Cases
+
+- Cancer research prior art
+- Technology landscape analysis
+- Identify research trends
+- Licensing opportunities
+
+## 7. OCE Patent Examination Status/Event Codes APIs
+
+### Overview
+
+**Version:** v1
+
+Provides official descriptions of USPTO status and event codes used in patent examination.
+
+### Purpose
+
+Decode transaction codes and status codes found in PEDS and other examination data.
+
+### Data Provided
+
+- **Status codes** - Application status descriptions
+- **Event codes** - Transaction/event descriptions
+- **Code definitions** - Official meanings
+
+### Integration
+
+Use with PEDS data to interpret transaction codes:
+
+```python
+def get_code_description(code, api_key):
+    """Get human-readable description of USPTO code."""
+    # Fetch from OCE API
+    pass
+
+def enrich_peds_data(peds_transactions, api_key):
+    """Add descriptions to PEDS transaction codes."""
+    for trans in peds_transactions:
+        trans['description'] = get_code_description(trans['code'], api_key)
+    return peds_transactions
+```
+
+## API Integration Patterns
+
+### Combined Workflow Example
+
+```python
+def comprehensive_patent_analysis(patent_number, api_key):
+    """
+    Comprehensive analysis combining multiple APIs.
+    """
+    results = {}
+
+    # 1. Get patent details from PatentSearch
+    results['patent_data'] = search_patent(patent_number, api_key)
+
+    # 2. Get examination history from PEDS
+    results['prosecution'] = get_peds_data(patent_number, api_key)
+
+    # 3. Get assignment history
+    results['assignments'] = get_assignments(patent_number, api_key)
+
+    # 4. Get citation data
+    results['citations'] = get_citations(patent_number, api_key)
+
+    # 5. Check litigation history
+    results['litigation'] = get_litigation(patent_number, api_key)
+
+    # 6. Get PTAB challenges
+    results['ptab'] = get_ptab_proceedings(patent_number, api_key)
+
+    return results
+```
+
+### Portfolio Analysis Example
+
+```python
+def analyze_company_portfolio(company_name, api_key):
+    """
+    Analyze a company's patent portfolio using multiple APIs.
+    """
+    # 1. Find all assigned patents
+    assignments = find_company_patents(company_name, api_key)
+    patent_numbers = extract_patent_numbers(assignments)
+
+    # 2. Get details for each patent
+    portfolio = []
+    for patent_num in patent_numbers:
+        patent_data = {
+            'number': patent_num,
+            'details': search_patent(patent_num, api_key),
+            'citations': get_citations(patent_num, api_key),
+            'litigation': get_litigation(patent_num, api_key)
+        }
+        portfolio.append(patent_data)
+
+    # 3. Aggregate statistics
+    stats = {
+        'total_patents': len(portfolio),
+        'cited_by_count': sum(len(p['citations']) for p in portfolio),
+        'litigated_count': sum(1 for p in portfolio if p['litigation']),
+        'technology_areas': aggregate_tech_areas(portfolio)
+    }
+
+    return {'portfolio': portfolio, 'statistics': stats}
+```
+
+## Best Practices
+
+1. **API Key Management** - Use environment variables, never hardcode
+2. **Rate Limiting** - Implement exponential backoff for all APIs
+3. **Caching** - Cache API responses to minimize redundant calls
+4. **Error Handling** - Gracefully handle API errors and missing data
+5. **Data Validation** - Validate input formats before API calls
+6. **Combining APIs** - Use appropriate APIs together for comprehensive analysis
+7. **Documentation** - Keep track of API versions and changes
+
+## API Key Registration
+
+All APIs require registration at:
+**https://account.uspto.gov/api-manager/**
+
+Single API key works across most USPTO APIs.
+
+## Resources
+
+- **Developer Portal**: https://developer.uspto.gov/
+- **Open Data Portal**: https://data.uspto.gov/
+- **API Catalog**: https://developer.uspto.gov/api-catalog
+- **Swagger Docs**: Available for individual APIs

package/bin/skills/uspto-database/references/patentsearch_api.md

@@ -0,0 +1,266 @@
+# PatentSearch API Reference
+
+## Overview
+
+The PatentSearch API is USPTO's modern ElasticSearch-based patent search system that replaced the legacy PatentsView API in May 2025. It provides access to patent data through June 30, 2025, with regular updates.
+
+**Base URL:** `https://search.patentsview.org/api/v1/`
+
+## Authentication
+
+All API requests require authentication using an API key in the request header:
+
+```
+X-Api-Key: YOUR_API_KEY
+```
+
+Register for an API key at: https://account.uspto.gov/api-manager/
+
+## Rate Limits
+
+- **45 requests per minute** per API key
+- Exceeding rate limits results in HTTP 429 errors
+
+## Available Endpoints
+
+### Core Patent & Publication Endpoints
+
+- **`/patent`** - General patent data (granted patents)
+- **`/publication`** - Pregrant publication data
+- **`/publication/rel_app_text`** - Related application data for publications
+
+### Entity Endpoints
+
+- **`/inventor`** - Inventor information with location and gender code fields
+- **`/assignee`** - Assignee details with location identifiers
+- **`/location`** - Geographic data including latitude/longitude coordinates
+- **`/attorney`** - Legal representative information
+
+### Classification Endpoints
+
+- **`/cpc_subclass`** - Cooperative Patent Classification at subclass level
+- **`/cpc_at_issue`** - CPC classification as of patent issue date
+- **`/uspc`** - US Patent Classification data
+- **`/wipo`** - World Intellectual Property Organization classifications
+- **`/ipc`** - International Patent Classification
+
+### Text Data Endpoints (Beta)
+
+- **`/brief_summary_text`** - Patent brief summaries (granted and pre-grant)
+- **`/claims`** - Patent claims text
+- **`/drawing_description_text`** - Drawing descriptions
+- **`/detail_description_text`** - Detailed description text
+
+*Note: Text endpoints are in beta with data primarily from 2023 onward. Historical backfilling is in progress.*
+
+### Supporting Endpoints
+
+- **`/other_reference`** - Patent reference materials
+- **`/related_document`** - Cross-references between patents
+
+## Query Parameters
+
+All endpoints support four main parameters:
+
+### 1. Query String (`q`)
+
+Filters data using JSON query objects. **Required parameter.**
+
+**Query Operators:**
+
+- **Equality**: `{"field": "value"}` or `{"field": {"_eq": "value"}}`
+- **Not equal**: `{"field": {"_neq": "value"}}`
+- **Comparison**: `_gt`, `_gte`, `_lt`, `_lte`
+- **String matching**:
+  - `_begins` - starts with
+  - `_contains` - substring match
+- **Full-text search** (recommended for text fields):
+  - `_text_all` - all terms must match
+  - `_text_any` - any term matches
+  - `_text_phrase` - exact phrase match
+- **Logical operators**: `_and`, `_or`, `_not`
+- **Array matching**: Use arrays for OR conditions
+
+**Examples:**
+
+```json
+// Simple equality
+{"patent_number": "11234567"}
+
+// Date range
+{"patent_date": {"_gte": "2020-01-01", "_lte": "2020-12-31"}}
+
+// Text search (preferred for text fields)
+{"patent_abstract": {"_text_all": ["machine", "learning"]}}
+
+// Inventor name
+{"inventor_name": {"_text_phrase": "John Smith"}}
+
+// Complex query with logical operators
+{
+  "_and": [
+    {"patent_date": {"_gte": "2020-01-01"}},
+    {"assignee_organization": {"_text_any": ["Google", "Alphabet"]}}
+  ]
+}
+
+// Array for OR conditions
+{"cpc_subclass_id": ["H04N", "H04L"]}
+```
+
+### 2. Field List (`f`)
+
+Specifies which fields to return in the response. Optional - each endpoint has default fields.
+
+**Format:** JSON array of field names
+
+```json
+["patent_number", "patent_title", "patent_date", "inventor_name"]
+```
+
+### 3. Sorting (`s`)
+
+Orders results by specified fields. Optional.
+
+**Format:** JSON array with field name and direction
+
+```json
+[{"patent_date": "desc"}]
+```
+
+### 4. Options (`o`)
+
+Controls pagination and additional settings. Optional.
+
+**Available options:**
+
+- `page` - Page number (default: 1)
+- `per_page` - Records per page (default: 100, max: 1,000)
+- `pad_patent_id` - Pad patent IDs with leading zeros (default: false)
+- `exclude_withdrawn` - Exclude withdrawn patents (default: true)
+
+**Format:** JSON object
+
+```json
+{
+  "page": 1,
+  "per_page": 500,
+  "exclude_withdrawn": false
+}
+```
+
+## Response Format
+
+All responses follow this structure:
+
+```json
+{
+  "error": false,
+  "count": 100,
+  "total_hits": 5432,
+  "patents": [...],
+  // or "inventors": [...], "assignees": [...], etc.
+}
+```
+
+- `error` - Boolean indicating if an error occurred
+- `count` - Number of records in current response
+- `total_hits` - Total number of matching records
+- Endpoint-specific data array (e.g., `patents`, `inventors`)
+
+## Complete Request Example
+
+### Using curl
+
+```bash
+curl -X POST "https://search.patentsview.org/api/v1/patent" \
+  -H "X-Api-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "q": {
+      "_and": [
+        {"patent_date": {"_gte": "2024-01-01"}},
+        {"patent_abstract": {"_text_all": ["artificial", "intelligence"]}}
+      ]
+    },
+    "f": ["patent_number", "patent_title", "patent_date", "assignee_organization"],
+    "s": [{"patent_date": "desc"}],
+    "o": {"per_page": 100}
+  }'
+```
+
+### Using Python
+
+```python
+import requests
+
+url = "https://search.patentsview.org/api/v1/patent"
+headers = {
+    "X-Api-Key": "YOUR_API_KEY",
+    "Content-Type": "application/json"
+}
+data = {
+    "q": {
+        "_and": [
+            {"patent_date": {"_gte": "2024-01-01"}},
+            {"patent_abstract": {"_text_all": ["artificial", "intelligence"]}}
+        ]
+    },
+    "f": ["patent_number", "patent_title", "patent_date", "assignee_organization"],
+    "s": [{"patent_date": "desc"}],
+    "o": {"per_page": 100}
+}
+
+response = requests.post(url, headers=headers, json=data)
+results = response.json()
+```
+
+## Common Field Names
+
+### Patent Endpoint Fields
+
+- `patent_number` - Patent number
+- `patent_title` - Title of the patent
+- `patent_date` - Grant date
+- `patent_abstract` - Abstract text
+- `patent_type` - Type of patent
+- `inventor_name` - Inventor names (array)
+- `assignee_organization` - Assignee company names (array)
+- `cpc_subclass_id` - CPC classification codes
+- `uspc_class` - US classification codes
+- `cited_patent_number` - Citations to other patents
+- `citedby_patent_number` - Patents citing this patent
+
+Refer to the full field dictionary at: https://search.patentsview.org/docs/
+
+## Best Practices
+
+1. **Use `_text*` operators for text fields** - More performant than `_contains` or `_begins`
+2. **Request only needed fields** - Reduces response size and improves performance
+3. **Implement pagination** - Handle large result sets efficiently
+4. **Respect rate limits** - Implement backoff/retry logic for 429 errors
+5. **Cache results** - Reduce redundant API calls
+6. **Use date ranges** - Narrow searches to improve performance
+
+## Error Handling
+
+Common HTTP status codes:
+
+- **200** - Success
+- **400** - Bad request (invalid query syntax)
+- **401** - Unauthorized (missing or invalid API key)
+- **429** - Too many requests (rate limit exceeded)
+- **500** - Server error
+
+## Recent Updates (February 2025)
+
+- Data updated through December 31, 2024
+- New `pad_patent_id` option for formatting patent IDs
+- New `exclude_withdrawn` option to show withdrawn patents
+- Text endpoints continue beta backfilling
+
+## Resources
+
+- **Official Documentation**: https://search.patentsview.org/docs/
+- **API Key Registration**: https://account.uspto.gov/api-manager/
+- **Legacy API Notice**: The old PatentsView API was discontinued May 1, 2025