Metadata-Version: 2.4
Name: paive-agents
Version: 0.0.2
Summary: Official Python library for the PAIVE API.
Author: PAIVE
Maintainer: PAIVE
License: LicenseRef-Proprietary
Project-URL: Homepage, https://paive.patentelligence.ai
Keywords: paive,patents,patent intelligence,api,sdk,reports
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Requires-Dist: httpx>=0.24

# 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](https://paive.patentelligence.ai) | [PyPI](https://pypi.org/project/paive-agents/)

## Installation

Requires Python 3.8 or later.

```bash
pip install paive-agents
```

To update an existing installation:

```bash
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):**

```powershell
$env:PAIVE_API_KEY = "YOUR_PAIVE_API_KEY"
```

**macOS or Linux:**

```bash
export PAIVE_API_KEY="YOUR_PAIVE_API_KEY"
```

## Quick start

Save the following as `generate_report.py`:

```python
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:

```bash
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:

```python
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:

```python
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

```python
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:

```python
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:

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

Typical output:

```text
[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:

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

## Asynchronous usage

Use `AsyncClient` in asynchronous Python applications:

```python
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:

```python
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:

```python
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](https://paive.patentelligence.ai) for access to the product. Obtain
API keys and confirm report permissions and credits through your PAIVE account
or the PAIVE team.
