PAIVE Python API library

The official PAIVE Python library provides access to the PAIVE REST API from Python 3.8+ applications. The library offers synchronous and asynchronous clients for patent intelligence report generation, with support for patent number submissions, PDF uploads, configurable analysis parameters, and automatic downloads in PDF, DOCX, and TXT formats.

Access to the API requires a PAIVE API key.

PAIVE | PyPI

Installation

Requires Python 3.8 or later.

pip install paive-agents

To update an existing installation:

pip install --upgrade paive-agents

API key

Obtain a PAIVE API key from your PAIVE account or the PAIVE team. Your account must have report generation enabled, permission for the selected report, and available report credits.

The SDK connects automatically to the hosted PAIVE API over HTTPS.

Set your key in the terminal where you will run your Python script.

Windows (PowerShell):

$env:PAIVE_API_KEY = "YOUR_PAIVE_API_KEY"

macOS or Linux:

export PAIVE_API_KEY="YOUR_PAIVE_API_KEY"

Quick start

Save the following as generate_report.py:

import os

from paive_agents import Client

client = Client(api_key=os.environ["PAIVE_API_KEY"])

report = client.generate_report(
    patent_id="US11604988B2",
    patent_type="non-regulated",
    output_dir="paive_reports",
)

for file_type, path in report.files.items():
    print(f"{file_type.upper()} report saved to: {path}")

Run it with:

python generate_report.py

generate_report() waits for report generation to finish and downloads the requested files before returning. The example generates an IP Brief with all three analysis levels set to High.

PDF, DOCX, and TXT are requested by default. The SDK creates paive_reports when the completed files are available. A relative output folder is resolved from the directory where you run the script.

report.files maps each downloaded format to its local file path. You can also access individual paths using report.pdf_file, report.docx_file, and report.txt_file.

Report options

Report	report_type
IP Brief (default)	brief_IP_decision_support_intelligence
IP 360 without valuation	ip_360_no_valuation_intelligence_strategic_guide

To generate IP 360 without valuation, select its report type:

report = client.generate_report(
    patent_id="US11604988B2",
    patent_type="non-regulated",
    report_type="ip_360_no_valuation_intelligence_strategic_guide",
    output_dir="paive_reports",
)

Access to each report depends on your PAIVE account permissions.

Inputs and parameters

Provide exactly one of patent_id or pdf_path, together with patent_type.

Parameter	Description	Default
patent_id	Patent number, such as US11604988B2. Use this or pdf_path.	None
pdf_path	Path to a patent PDF on your computer. Use this or patent_id.	None
patent_type	Product category: non-regulated or regulated.	Required
report_type	One of the report identifiers above.	IP Brief
tech_sector	Optional technology sector; use an exact sector name available in PAIVE.	None
clp_analysis	CLP analysis depth.	High
market_analysis	Market analysis depth.	High
licensing_analysis	Licensing analysis depth.	High
output_type	One format or a list of formats: pdf, docx, txt.	All three
output_dir	Folder for downloaded report files.	generated_reports

Analysis depth

Each analysis parameter accepts these values:

Value	Depth
Low	Focused analysis
Medium	Standard analysis
Medium-high	Expanded analysis
High	Full analysis

For example:

report = client.generate_report(
    patent_id="US11604988B2",
    patent_type="non-regulated",
    clp_analysis="Medium",
    market_analysis="High",
    licensing_analysis="Medium-high",
    output_type=["pdf", "docx"],
    output_dir="paive_reports",
)

Upload a patent PDF

report = client.generate_report(
    pdf_path="patent.pdf",
    patent_type="non-regulated",
    output_dir="paive_reports",
)

Optional questionnaire context

You can include business and technology context, such as:

report = client.generate_report(
    patent_id="US11604988B2",
    patent_type="non-regulated",
    role="Founder/Operator",
    trl_level="TRL 5-6 (Prototype/Lab Validation)",
    output_dir="paive_reports",
)

Questionnaire selections must use PAIVE's predefined choices. Invalid answers return a validation error identifying the affected fields.

Some selections require related answers:

• traction_type="customer_discovery" requires customer_discovery, pilots_trials, and industry_interest.
• traction_type="rpp" requires rpp_stage and rpp_deal.
• infringement_suspected="Yes" or "Possibly" requires suspicion_triggers.

Track progress

Safe progress is printed automatically while a report is generated. No callback is required:

report = client.generate_report(
    patent_id="US11604988B2",
    patent_type="non-regulated",
    output_dir="paive_reports",
)

Typical output:

[pending] Report queued (0%)
[running] Analyzing patent (20%)
[running] Generating report files (85%)
[succeeded] Report generation completed (100%)

Repeated polling states are printed only once. Internal factor names, counts, scores, weights, prompts, and provider details are never printed.

on_progress remains available as an additional application callback for UI updates or metrics. The SDK's safe console progress still prints when a custom callback is supplied.

Generation time depends on the report and analysis depth. The default overall waiting limit is 40 minutes. For a longer waiting limit, set timeout in seconds when creating the client:

client = Client(api_key=os.environ["PAIVE_API_KEY"], timeout=7200)

Asynchronous usage

Use AsyncClient in asynchronous Python applications:

import asyncio
import os

from paive_agents import AsyncClient


async def main():
    client = AsyncClient(api_key=os.environ["PAIVE_API_KEY"])
    report = await client.generate_report(
        patent_id="US11604988B2",
        patent_type="non-regulated",
        output_dir="paive_reports",
    )
    for file_type, path in report.files.items():
        print(f"{file_type.upper()} report saved to: {path}")


if __name__ == "__main__":
    asyncio.run(main())

Errors and troubleshooting

API and connection errors inherit from paive_agents.PaiveError. They expose status_code and response_body when available.

Error	What to check
AuthenticationError	Your PAIVE API key is valid and active.
PermissionDeniedError	Your account has generation access and permission for the selected report.
InvalidRequestError	Inputs, questionnaire choices, and available report credits; inspect the error details.
RateLimitError	Your account's usage limits; follow the API error details before retrying.
APIConnectionError	Your internet connection and service availability.
ServerError	PAIVE service availability; retain the error details for support.
ReportJobFailedError	The report could not be completed; inspect the error details.
ReportJobCancelledError	The report was cancelled.
ReportJobTimeoutError	The waiting limit expired; the report may still be processing.

For example:

from paive_agents import PaiveError

try:
    report = client.generate_report(
        patent_id="US11604988B2",
        patent_type="non-regulated",
        output_dir="paive_reports",
    )
except PaiveError as error:
    print(f"PAIVE request failed: {error}")
    print(f"Status: {error.status_code}")

Advanced report jobs

For applications that manage report jobs separately, submit a report and retain its job ID:

job = client.submit_report(
    patent_id="US11604988B2",
    patent_type="non-regulated",
)
print(job.id)

current = client.get_report_job(job.id)
print(current.status)

# Wait for completion, or cancel the job if needed:
# completed = client.wait_for_report(job.id)
# client.cancel_report(job.id)

These methods return job information. generate_report() handles waiting and automatic file downloads for you.

A report continues processing on PAIVE if the client's connection is interrupted. For retries of the same report request, supply the same idempotency_key to retrieve the existing job and download its files when complete. Use a new key when requesting a new report.

Account access

Visit PAIVE for access to the product. Obtain API keys and confirm report permissions and credits through your PAIVE account or the PAIVE team.