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

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

@@ -0,0 +1,212 @@
+# Patent Examination Data System (PEDS) API Reference
+
+## Overview
+
+The Patent Examination Data System (PEDS) provides access to USPTO patent application and filing status records. It contains bibliographic data, published document information, and patent term extension data.
+
+**Data Coverage:** 1981 to present (some data back to 1935)
+
+**Base URL:** Access through USPTO Open Data Portal
+
+## What PEDS Provides
+
+PEDS gives comprehensive transaction history and status information for patent applications:
+
+- **Bibliographic data** - Application numbers, filing dates, titles, inventors, assignees
+- **Published documents** - Publication numbers and dates
+- **Transaction history** - All examination events with dates, codes, and descriptions
+- **Patent term adjustments** - PTA/PTE information
+- **Application status** - Current status and status codes
+- **File wrapper access** - Links to prosecution documents
+
+## Key Features
+
+1. **Transaction Activity** - Complete examination timeline with transaction dates, codes, and descriptions
+2. **Status Information** - Current application status and status codes
+3. **Bibliographic Updates** - Changes to inventors, assignees, titles over time
+4. **Family Data** - Related applications and continuity data
+5. **Office Action Tracking** - Mail dates and office action information
+
+## Python Library: uspto-opendata-python
+
+The recommended way to access PEDS is through the `uspto-opendata-python` library.
+
+### Installation
+
+```bash
+pip install uspto-opendata-python
+```
+
+### Basic Usage
+
+```python
+from uspto.peds import PE DSClient
+
+# Initialize client
+client = PEDSClient()
+
+# Search by application number
+app_number = "16123456"
+result = client.get_application(app_number)
+
+# Access application data
+print(f"Title: {result['title']}")
+print(f"Filing Date: {result['filing_date']}")
+print(f"Status: {result['status']}")
+
+# Get transaction history
+transactions = result['transactions']
+for trans in transactions:
+    print(f"{trans['date']}: {trans['code']} - {trans['description']}")
+```
+
+### Search Methods
+
+```python
+# By application number
+client.get_application("16123456")
+
+# By patent number
+client.get_patent("11234567")
+
+# By customer number (assignee)
+client.search_by_customer_number("12345")
+
+# Bulk retrieval
+app_numbers = ["16123456", "16123457", "16123458"]
+results = client.bulk_retrieve(app_numbers)
+```
+
+## Data Fields
+
+### Bibliographic Fields
+
+- `application_number` - Application number
+- `filing_date` - Filing date
+- `patent_number` - Patent number (if granted)
+- `patent_issue_date` - Issue date (if granted)
+- `title` - Application/patent title
+- `inventors` - List of inventors
+- `assignees` - List of assignees
+- `app_type` - Application type (utility, design, plant, reissue)
+- `app_status` - Current application status
+- `app_status_date` - Status date
+
+### Transaction Fields
+
+- `transaction_date` - Date of transaction
+- `transaction_code` - USPTO event code
+- `transaction_description` - Description of event
+- `mail_date` - Mail room date (for office actions)
+
+### Patent Term Data
+
+- `pta_pte_summary` - Patent term adjustment/extension summary
+- `pta_pte_history` - History of term calculations
+
+## Status Codes
+
+Common application status codes:
+
+- **Patented Case** - Patent has been granted
+- **Abandoned** - Application is abandoned
+- **Pending** - Application is under examination
+- **Allowed** - Application has been allowed, awaiting issue
+- **Final Rejection** - Final rejection issued
+- **Non-Final Rejection** - Non-final rejection issued
+- **Response Filed** - Applicant response filed
+
+## Transaction Codes
+
+Common transaction codes include:
+
+- **CTNF** - Non-final rejection mailed
+- **CTFR** - Final rejection mailed
+- **AOPF** - Office action mailed
+- **WRIT** - Response filed
+- **NOA** - Notice of allowance mailed
+- **ISS.FEE** - Issue fee payment
+- **ABND** - Application abandoned
+
+Full code list available in OCE Patent Examination Status/Event Codes API.
+
+## Use Cases
+
+### 1. Track Application Progress
+
+Monitor pending applications for office actions and status changes.
+
+```python
+# Get current status
+app = client.get_application("16123456")
+print(f"Current status: {app['app_status']}")
+print(f"Status date: {app['app_status_date']}")
+
+# Check for recent office actions
+recent_oas = [t for t in app['transactions']
+              if t['code'] in ['CTNF', 'CTFR', 'AOPF']
+              and t['date'] > '2024-01-01']
+```
+
+### 2. Portfolio Analysis
+
+Analyze prosecution history across a portfolio.
+
+```python
+# Get all applications for an assignee
+apps = client.search_by_customer_number("12345")
+
+# Calculate average pendency
+pendencies = []
+for app in apps:
+    if app['patent_issue_date']:
+        filing = datetime.strptime(app['filing_date'], '%Y-%m-%d')
+        issue = datetime.strptime(app['patent_issue_date'], '%Y-%m-%d')
+        pendencies.append((issue - filing).days)
+
+avg_pendency = sum(pendencies) / len(pendencies)
+print(f"Average pendency: {avg_pendency} days")
+```
+
+### 3. Examine Rejection Patterns
+
+Analyze types of rejections received.
+
+```python
+# Count rejection types
+rejections = {}
+for trans in app['transactions']:
+    if 'rejection' in trans['description'].lower():
+        code = trans['code']
+        rejections[code] = rejections.get(code, 0) + 1
+```
+
+## Integration with Other APIs
+
+PEDS data can be combined with other USPTO APIs:
+
+- **Office Action Text API** - Retrieve full text of office actions using application number
+- **Patent Assignment Search** - Find ownership changes
+- **PTAB API** - Check for appeal proceedings
+
+## Important Notes
+
+1. **PAIR Bulk Data (PBD) is decommissioned** - Use PEDS instead
+2. **Data updates** - PEDS is updated regularly but may have 1-2 day lag
+3. **Application numbers** - Use standardized format (no slashes or spaces)
+4. **Continuity data** - Parent/child applications tracked in transaction history
+
+## Best Practices
+
+1. **Batch requests** - Use bulk retrieval for multiple applications
+2. **Cache data** - Avoid redundant API calls for same application
+3. **Monitor updates** - Check for transaction updates regularly
+4. **Handle missing data** - Not all fields populated for all applications
+5. **Parse transaction codes** - Use code descriptions for user-friendly display
+
+## Resources
+
+- **Library Documentation**: https://docs.ip-tools.org/uspto-opendata-python/
+- **PyPI Package**: https://pypi.org/project/uspto-opendata-python/
+- **GitHub Repository**: https://github.com/ip-tools/uspto-opendata-python
+- **USPTO PEDS Portal**: https://ped.uspto.gov/

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

@@ -0,0 +1,358 @@
+# USPTO Trademark APIs Reference
+
+## Overview
+
+USPTO provides two main APIs for trademark data:
+
+1. **Trademark Status & Document Retrieval (TSDR)** - Retrieve trademark case status and documents
+2. **Trademark Assignment Search** - Search trademark assignment records
+
+## 1. Trademark Status & Document Retrieval (TSDR) API
+
+### Overview
+
+TSDR enables programmatic retrieval of trademark case status documents and information.
+
+**API Version:** v1.0
+
+**Base URL:** `https://tsdrapi.uspto.gov/ts/cd/`
+
+### Authentication
+
+Requires API key registration at: https://account.uspto.gov/api-manager/
+
+Include API key in request header:
+```
+X-Api-Key: YOUR_API_KEY
+```
+
+### Endpoints
+
+#### Get Trademark Status by Serial Number
+
+```
+GET /ts/cd/casedocs/sn{serial_number}/info.json
+```
+
+**Example:**
+```bash
+curl -H "X-Api-Key: YOUR_KEY" \
+  "https://tsdrapi.uspto.gov/ts/cd/casedocs/sn87654321/info.json"
+```
+
+#### Get Trademark Status by Registration Number
+
+```
+GET /ts/cd/casedocs/rn{registration_number}/info.json
+```
+
+### Response Format
+
+Returns JSON with comprehensive trademark information:
+
+```json
+{
+  "TradeMarkAppln": {
+    "ApplicationNumber": "87654321",
+    "ApplicationDate": "2017-10-15",
+    "RegistrationNumber": "5678901",
+    "RegistrationDate": "2019-03-12",
+    "MarkVerbalElementText": "EXAMPLE MARK",
+    "MarkCurrentStatusExternalDescriptionText": "REGISTERED",
+    "MarkCurrentStatusDate": "2019-03-12",
+    "GoodsAndServices": [...],
+    "Owners": [...],
+    "Correspondents": [...]
+  }
+}
+```
+
+### Key Data Fields
+
+- **Application Information:**
+  - `ApplicationNumber` - Serial number
+  - `ApplicationDate` - Filing date
+  - `ApplicationType` - Type (TEAS Plus, TEAS Standard, etc.)
+
+- **Registration Information:**
+  - `RegistrationNumber` - Registration number (if registered)
+  - `RegistrationDate` - Registration date
+
+- **Mark Information:**
+  - `MarkVerbalElementText` - Text of the mark
+  - `MarkCurrentStatusExternalDescriptionText` - Current status
+  - `MarkCurrentStatusDate` - Status date
+  - `MarkDrawingCode` - Type of mark (words, design, etc.)
+
+- **Classification:**
+  - `GoodsAndServices` - Array of goods/services with classes
+
+- **Owner Information:**
+  - `Owners` - Array of trademark owners/applicants
+
+- **Prosecution History:**
+  - `ProsecutionHistoryEntry` - Array of events in prosecution
+
+### Common Status Values
+
+- **REGISTERED** - Mark is registered and active
+- **PENDING** - Application under examination
+- **ABANDONED** - Application/registration abandoned
+- **CANCELLED** - Registration cancelled
+- **SUSPENDED** - Examination suspended
+- **PUBLISHED FOR OPPOSITION** - Published, in opposition period
+- **REGISTERED AND RENEWED** - Registration renewed
+
+### Python Example
+
+```python
+import requests
+
+def get_trademark_status(serial_number, api_key):
+    """Retrieve trademark status by serial number."""
+    url = f"https://tsdrapi.uspto.gov/ts/cd/casedocs/sn{serial_number}/info.json"
+    headers = {"X-Api-Key": api_key}
+
+    response = requests.get(url, headers=headers)
+    if response.status_code == 200:
+        return response.json()
+    else:
+        raise Exception(f"API error: {response.status_code}")
+
+# Usage
+data = get_trademark_status("87654321", "YOUR_API_KEY")
+trademark = data['TradeMarkAppln']
+
+print(f"Mark: {trademark['MarkVerbalElementText']}")
+print(f"Status: {trademark['MarkCurrentStatusExternalDescriptionText']}")
+print(f"Application Date: {trademark['ApplicationDate']}")
+if 'RegistrationNumber' in trademark:
+    print(f"Registration #: {trademark['RegistrationNumber']}")
+```
+
+## 2. Trademark Assignment Search API
+
+### Overview
+
+Retrieves trademark assignment records from the USPTO assignment database. Shows ownership transfers and security interests.
+
+**API Version:** v1.4
+
+**Base URL:** `https://assignment-api.uspto.gov/trademark/`
+
+### Authentication
+
+Requires API key in header:
+```
+X-Api-Key: YOUR_API_KEY
+```
+
+### Search Methods
+
+#### By Registration Number
+
+```
+GET /v1.4/assignment/application/{registration_number}
+```
+
+#### By Serial Number
+
+```
+GET /v1.4/assignment/application/{serial_number}
+```
+
+#### By Assignee Name
+
+```
+POST /v1.4/assignment/search
+```
+
+**Request body:**
+```json
+{
+  "criteria": {
+    "assigneeName": "Company Name"
+  }
+}
+```
+
+### Response Format
+
+Returns XML containing assignment records:
+
+```xml
+<assignments>
+  <assignment>
+    <reelFrame>12345/0678</reelFrame>
+    <conveyanceText>ASSIGNMENT OF ASSIGNORS INTEREST</conveyanceText>
+    <recordedDate>2020-01-15</recordedDate>
+    <executionDate>2020-01-10</executionDate>
+    <assignors>
+      <assignor>
+        <name>Original Owner LLC</name>
+      </assignor>
+    </assignors>
+    <assignees>
+      <assignee>
+        <name>New Owner Corporation</name>
+      </assignee>
+    </assignees>
+  </assignment>
+</assignments>
+```
+
+### Key Fields
+
+- `reelFrame` - USPTO reel and frame number
+- `conveyanceText` - Type of transaction
+- `recordedDate` - Date recorded at USPTO
+- `executionDate` - Date document was executed
+- `assignors` - Original owners
+- `assignees` - New owners
+- `propertyNumbers` - Affected serial/registration numbers
+
+### Common Conveyance Types
+
+- **ASSIGNMENT OF ASSIGNORS INTEREST** - Ownership transfer
+- **SECURITY AGREEMENT** - Collateral/security interest
+- **MERGER** - Corporate merger
+- **CHANGE OF NAME** - Name change
+- **ASSIGNMENT OF PARTIAL INTEREST** - Partial ownership transfer
+
+### Python Example
+
+```python
+import requests
+import xml.etree.ElementTree as ET
+
+def search_trademark_assignments(registration_number, api_key):
+    """Search assignments for a trademark registration."""
+    url = f"https://assignment-api.uspto.gov/trademark/v1.4/assignment/application/{registration_number}"
+    headers = {"X-Api-Key": api_key}
+
+    response = requests.get(url, headers=headers)
+    if response.status_code == 200:
+        return response.text  # Returns XML
+    else:
+        raise Exception(f"API error: {response.status_code}")
+
+# Usage
+xml_data = search_trademark_assignments("5678901", "YOUR_API_KEY")
+root = ET.fromstring(xml_data)
+
+for assignment in root.findall('.//assignment'):
+    reel_frame = assignment.find('reelFrame').text
+    recorded_date = assignment.find('recordedDate').text
+    conveyance = assignment.find('conveyanceText').text
+
+    assignor = assignment.find('.//assignor/name').text
+    assignee = assignment.find('.//assignee/name').text
+
+    print(f"{recorded_date}: {assignor} -> {assignee}")
+    print(f"  Type: {conveyance}")
+    print(f"  Reel/Frame: {reel_frame}\n")
+```
+
+## Use Cases
+
+### 1. Monitor Trademark Status
+
+Check status of pending applications or registrations:
+
+```python
+def check_trademark_health(serial_number, api_key):
+    """Check if trademark needs attention."""
+    data = get_trademark_status(serial_number, api_key)
+    tm = data['TradeMarkAppln']
+
+    status = tm['MarkCurrentStatusExternalDescriptionText']
+    alerts = []
+
+    if 'ABANDON' in status:
+        alerts.append("⚠️ ABANDONED")
+    elif 'PUBLISHED' in status:
+        alerts.append("📢 In opposition period")
+    elif 'SUSPENDED' in status:
+        alerts.append("⏸️ Examination suspended")
+    elif 'REGISTERED' in status:
+        alerts.append("✅ Active")
+
+    return alerts
+```
+
+### 2. Track Ownership Changes
+
+Monitor assignment records for ownership changes:
+
+```python
+def get_current_owner(registration_number, api_key):
+    """Find current trademark owner from assignment records."""
+    xml_data = search_trademark_assignments(registration_number, api_key)
+    root = ET.fromstring(xml_data)
+
+    assignments = []
+    for assignment in root.findall('.//assignment'):
+        date = assignment.find('recordedDate').text
+        assignee = assignment.find('.//assignee/name').text
+        assignments.append((date, assignee))
+
+    # Most recent assignment
+    if assignments:
+        assignments.sort(reverse=True)
+        return assignments[0][1]
+    return None
+```
+
+### 3. Portfolio Management
+
+Analyze trademark portfolio:
+
+```python
+def analyze_portfolio(serial_numbers, api_key):
+    """Analyze status of multiple trademarks."""
+    results = {
+        'active': 0,
+        'pending': 0,
+        'abandoned': 0,
+        'expired': 0
+    }
+
+    for sn in serial_numbers:
+        data = get_trademark_status(sn, api_key)
+        status = data['TradeMarkAppln']['MarkCurrentStatusExternalDescriptionText']
+
+        if 'REGISTERED' in status:
+            results['active'] += 1
+        elif 'PENDING' in status or 'PUBLISHED' in status:
+            results['pending'] += 1
+        elif 'ABANDON' in status:
+            results['abandoned'] += 1
+        elif 'EXPIRED' in status or 'CANCELLED' in status:
+            results['expired'] += 1
+
+    return results
+```
+
+## Rate Limits and Best Practices
+
+1. **Respect rate limits** - Implement retry logic with exponential backoff
+2. **Cache responses** - Trademark data changes infrequently
+3. **Batch processing** - Spread requests over time for large portfolios
+4. **Error handling** - Handle missing data gracefully (not all marks have all fields)
+5. **Data validation** - Verify serial/registration numbers before API calls
+
+## Integration with Other Data
+
+Combine trademark data with other sources:
+
+- **TSDR + Assignment** - Current status + ownership history
+- **Multiple marks** - Analyze related marks in a family
+- **Patent data** - Cross-reference IP portfolio
+
+## Resources
+
+- **TSDR API**: https://developer.uspto.gov/api-catalog/tsdr-data-api
+- **Assignment API**: https://developer.uspto.gov/api-catalog/trademark-assignment-search-data-api
+- **API Key Registration**: https://account.uspto.gov/api-manager/
+- **Trademark Search**: https://tmsearch.uspto.gov/
+- **Swagger Documentation**: https://developer.uspto.gov/swagger/tsdr-api-v1