paive-agents 0.0.1__tar.gz

paive_agents-0.0.1/PKG-INFO

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: paive-agents
+Version: 0.0.1
+Summary: Official PAIVE API SDK for patent intelligence reports in PDF, Word, and text
+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
+
+Use `on_progress` to display status while the report is being generated:
+
+```python
+def show_progress(job):
+    print(f"{job.status}: {job.current_factor}/{job.total_factors}")
+
+report = client.generate_report(
+    patent_id="US11604988B2",
+    patent_type="non-regulated",
+    output_dir="paive_reports",
+    on_progress=show_progress,
+)
+```
+
+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.

paive_agents-0.0.1/README.md

@@ -0,0 +1,299 @@
+# 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
+
+Use `on_progress` to display status while the report is being generated:
+
+```python
+def show_progress(job):
+    print(f"{job.status}: {job.current_factor}/{job.total_factors}")
+
+report = client.generate_report(
+    patent_id="US11604988B2",
+    patent_type="non-regulated",
+    output_dir="paive_reports",
+    on_progress=show_progress,
+)
+```
+
+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.

paive_agents-0.0.1/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "paive-agents"
+version = "0.0.1"
+description = "Official PAIVE API SDK for patent intelligence reports in PDF, Word, and text"
+authors = [{name = "PAIVE"}]
+maintainers = [{name = "PAIVE"}]
+keywords = ["paive", "patents", "patent intelligence", "api", "sdk", "reports"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Operating System :: OS Independent",
+]
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "LicenseRef-Proprietary"}
+dependencies = [
+    "requests>=2.28",
+    "httpx>=0.24",
+]
+
+[project.urls]
+Homepage = "https://paive.patentelligence.ai"
+
+[tool.setuptools.packages.find]
+where = ["src"]

paive_agents-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

paive_agents-0.0.1/src/paive_agents/__init__.py

@@ -0,0 +1,39 @@
+from .async_client import AsyncClient
+from .client import Client, DEFAULT_BASE_URL
+from .exceptions import (
+    APIConnectionError,
+    AuthenticationError,
+    InvalidRequestError,
+    PaiveError,
+    PermissionDeniedError,
+    RateLimitError,
+    ReportJobCancelledError,
+    ReportJobError,
+    ReportJobFailedError,
+    ReportJobTimeoutError,
+    ServerError,
+)
+from .models import Report, ReportJob
+
+
+__version__ = "0.0.1"
+
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "Report",
+    "ReportJob",
+    "DEFAULT_BASE_URL",
+    "PaiveError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "InvalidRequestError",
+    "RateLimitError",
+    "ServerError",
+    "APIConnectionError",
+    "ReportJobError",
+    "ReportJobFailedError",
+    "ReportJobCancelledError",
+    "ReportJobTimeoutError",
+]

paive_agents-0.0.1/src/paive_agents/_analysis.py

@@ -0,0 +1,21 @@
+ANALYSIS_LEVELS = ("Low", "Medium", "Medium-high", "High")
+
+_CANONICAL_LEVELS = {
+    level.lower(): level
+    for level in ANALYSIS_LEVELS
+}
+
+
+def normalize_analysis_level(value, argument_name):
+    """Validate an SDK analysis level and return its canonical spelling."""
+    if value is None or not str(value).strip():
+        return "High"
+
+    normalized = str(value).strip().lower()
+    try:
+        return _CANONICAL_LEVELS[normalized]
+    except KeyError as exc:
+        raise ValueError(
+            f"{argument_name} must be one of: "
+            f"{', '.join(ANALYSIS_LEVELS)}"
+        ) from exc