Metadata-Version: 2.4
Name: paive-agents
Version: 0.3.0
Summary: Official Python SDK for the Paive patent intelligence report API
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Requires-Dist: httpx>=0.24

# paive-agents

Official Python SDK for the Paive patent intelligence report API.

## Install

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

## API endpoint

The SDK connects to the production Paive API over HTTPS by default:

```python
DEFAULT_BASE_URL = "https://paive.patentelligence.ai"
```

For local development or testing, override the URL with the `PAIVE_BASE_URL`
environment variable or the `base_url` client argument.

## Sync usage

```python
from paive_agents import Client

client = Client(api_key="YOUR_API_KEY")

report = client.generate_report(
    patent_id="US12093418B2",
    patent_type="Normal",
    tech_sector="Biotech / Therapeutics",
    clp_analysis="Medium",
    market_analysis="High",
    licensing_analysis="Low",
)

print(report.pdf_file)
```

## Async usage

```python
from paive_agents import AsyncClient

client = AsyncClient(api_key="YOUR_API_KEY")
report = await client.generate_report(
    patent_id="US12093418B2",
    patent_type="Normal",
)
```

## PDF upload instead of patent_id

```python
report = client.generate_report(
    pdf_path="/path/to/patent.pdf",
    patent_type="Normal",
)
```

## Analysis depth

`clp_analysis`, `market_analysis`, and `licensing_analysis` accept the same
four values:

- `"Low"` — focused analysis
- `"Medium"` — standard analysis
- `"Medium-high"` — expanded analysis
- `"High"` — full analysis (default)

The API chooses the internal factors for each level; SDK users do not need to
provide factor names.

## Errors

All errors subclass `paive_agents.PaiveError` and carry `.status_code` and `.response_body`:

- `AuthenticationError` — invalid/missing API key (401)
- `PermissionDeniedError` — user lacks permission (403)
- `InvalidRequestError` — bad request (400/404)
- `RateLimitError` — usage limit exceeded (429)
- `ServerError` — server-side failure (500+)
- `APIConnectionError` — network/connection failure

## API compatibility

This package talks to `/api/keys/generate_report` over HTTPS and uses
`X-API-Key` authentication.
