### Install from Wheel File

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/CONTRIBUTING.md

Install the package efficiently after building it by providing the path to the generated wheel file.

```sh
$ pip install ./path-to-wheel-file.whl
```

--------------------------------

### Install Reducto Python SDK

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/README.md

Install the Reducto Python library from PyPI using pip.

```sh
pip install reductoai
```

--------------------------------

### Install Reducto Python SDK

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/README.md

Provides commands for installing the Reducto Python SDK using pip. Includes standard installation and an optional installation with the aiohttp backend for asynchronous operations.

```bash
# Standard installation
pip install reductoai

# With aiohttp backend for async (optional)
pip install reductoai[aiohttp]
```

--------------------------------

### Add and Run Example Script

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/CONTRIBUTING.md

Add new example scripts to the 'examples/' directory and make them executable to run against your API.

```py
# add an example to examples/<your-example>.py

#!/usr/bin/env -S rye run python
…
```

```sh
$ chmod +x examples/<your-example>.py
# run the example against your api
$ ./examples/<your-example>.py
```

--------------------------------

### Install SDK from Git

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/CONTRIBUTING.md

Install the Reducto Python SDK directly from its Git repository using SSH.

```sh
$ pip install git+ssh://git@github.com/reductoai/reducto-python-sdk.git
```

--------------------------------

### Install Reducto with aiohttp support

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/README.md

Install the Reducto Python library with optional aiohttp support for improved concurrency.

```sh
pip install reductoai[aiohttp]
```

--------------------------------

### Async Webhook Portal Access Example

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/webhook.md

Example demonstrating how to obtain the webhook configuration portal URL using the asynchronous client. Ensure you are within an asyncio event loop.

```python
import asyncio
from reducto import AsyncReducto

async def main():
    async with AsyncReducto(api_key="your_api_key") as client:
        portal_url = await client.webhook.run()
        print(f"Configure webhooks at: {portal_url}")

asyncio.run(main())
```

--------------------------------

### Example: Upload Local File and Parse

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/uploads.md

A complete example demonstrating how to upload a local PDF file using its path and then use the returned document URL to parse it.

```python
from pathlib import Path
from reducto import Reducto

client = Reducto(api_key="your_api_key")

# Upload local file
result = client.upload(file=Path("/path/to/document.pdf"))
print(f"Document URL: {result.url}")

# Use uploaded document in parse
response = client.parse.run(input=result.url)
print(f"Parsed successfully: {len(response.result.chunks)} chunks")
```

--------------------------------

### Basic Document Split Example

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/split.md

Demonstrates how to split a document into predefined categories using the synchronous `run` method. It shows how to initialize the client and process the response.

```python
from reducto import Reducto

client = Reducto(api_key="your_api_key")

# Split document into categories
response = client.split.run(
    input="https://example.com/multipage_document.pdf",
    split_description=[
        {"name": "cover", "description": "Front cover page"},
        {"name": "toc", "description": "Table of contents"},
        {"name": "chapters", "description": "Main content chapters"},
        {"name": "appendix", "description": "Appendix and references"}
    ]
)

# Access split results
for section in response.sections:
    print(f"Section: {section.category}")
    print(f"Pages: {section.page_range}")
```

--------------------------------

### Complete Upload Workflow Example

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/uploads.md

Demonstrates the full process of uploading a local document, parsing it, and extracting structured data. Ensure the file path is correct.

```python
from pathlib import Path
from reducto import Reducto

def process_local_document(file_path: str) -> None:
    client = Reducto(api_key="your_api_key")
    
    # 1. Upload document
    print("Uploading document...")
    upload_result = client.upload(file=Path(file_path))
    print(f"Upload complete: {upload_result.url}")
    
    # 2. Parse uploaded document
    print("Parsing...")
    parse_result = client.parse.run(input=upload_result.url)
    print(f"Parsed {len(parse_result.result.chunks)} chunks")
    
    # 3. Extract data
    print("Extracting structured data...")
    extract_result = client.extract.run(
        input=upload_result.url,
        instructions={
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "author": {"type": "string"}
            }
        }
    )
    print(f"Extracted: {extract_result.result.data}")

# Usage
process_local_document("/path/to/document.pdf")
```

--------------------------------

### Example: Asynchronous Upload and Parse

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/uploads.md

An example of using the asynchronous `AsyncReducto` client to upload a local file and then use its URL for asynchronous parsing. Requires an `asyncio` event loop.

```python
import asyncio
from pathlib import Path
from reducto import AsyncReducto

async def main():
    async with AsyncReducto(api_key="your_api_key") as client:
        result = await client.upload(file=Path("/path/to/document.pdf"))
        print(f"Uploaded: {result.url}")
        
        # Use in parse
        response = await client.parse.run(input=result.url)
        print(f"Parsed: {len(response.result.chunks)} chunks")

asyncio.run(main())
```

--------------------------------

### Access Webhook Portal URL

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/webhook.md

Example of how to get the webhook configuration portal URL using the synchronous client. Visit the returned URL in a browser to configure webhooks.

```python
from reducto import Reducto

client = Reducto(api_key="your_api_key")

# Get webhook configuration portal URL
portal_url = client.webhook.run()
print(f"Configure webhooks at: {portal_url}")
# Visit URL in browser to configure webhooks
```

--------------------------------

### Install Dependencies with Pip

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/CONTRIBUTING.md

If you prefer not to use Rye, install development dependencies using pip and the requirements-dev.lock file.

```sh
$ pip install -r requirements-dev.lock
```

--------------------------------

### Async Job Status Check Example

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/job.md

This example demonstrates how to asynchronously poll for job completion using the `get` method. It checks the job status periodically and breaks the loop once the job is completed or failed.

```python
import asyncio
from reducto import AsyncReducto

async def main():
    async with AsyncReducto(api_key="your_api_key") as client:
        # Poll for job completion
        for i in range(30):
            response = await client.job.get("job_abc123")
            if response.status == "completed":
                print(f"Job completed: {response.result}")
                break
            elif response.status == "failed":
                print(f"Job failed: {response.error}")
                break
            print(f"Status: {response.status}, waiting...")
            await asyncio.sleep(5)

asyncio.run(main())
```

--------------------------------

### Complete Citation Workflow Example

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/lib.md

Demonstrates a full workflow using Reducto to parse a document, find specific text citations using CitationFinder, and export the results.

```python
from reducto import Reducto
from reducto.lib.citations import CitationFinder
from reducto.types import BoundingBox

# Create client and parse document
client = Reducto(api_key="your_key")

response = client.parse.run(
    input="https://example.com/contract.pdf",
    settings={\"return_ocr_data\": True}  # Enable OCR for citations
)

# Find all instances of a phrase
finder = CitationFinder(response)
citations = finder.cite("termination clause")

# Export results
import json
results = []
for citation in citations:
    results.append({
        "page": citation.page,
        "locations": [
            {
                "left": bbox.left,
                "top": bbox.top,
                "width": bbox.width,
                "height": bbox.height
            }
            for bbox in citation.bboxes
        ]
    })

print(json.dumps(results, indent=2))
```

--------------------------------

### Get Reducto SDK Version

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/configuration.md

Retrieve the currently installed version of the Reducto SDK at runtime. This is useful for compatibility checks or reporting.

```python
import reducto

print(reducto.__version__)  # e.g., "0.22.0"
```

--------------------------------

### Example: Upload Bytes from Remote File

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/uploads.md

This example shows downloading a file from a remote URL using the `requests` library, extracting its content as bytes, and then uploading those bytes to Reducto, specifying the extension.

```python
import requests
from reducto import Reducto

client = Reducto(api_key="your_api_key")

# Download remote file and upload
remote_url = "https://example.com/document.pdf"
response = requests.get(remote_url)
pdf_content = response.content

# Upload
result = client.upload(
    file=pdf_content,
    extension="pdf"
)
print(f"Uploaded as: {result.url}")
```

--------------------------------

### File Upload Example

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/README.md

Shows how to upload a file using the Reducto client. Files can be provided as bytes, a PathLike instance, or a tuple containing filename, contents, and media type.

```python
from pathlib import Path
from reducto import Reducto

client = Reducto()

client.upload(
    file=Path("/path/to/file"),
)
```

--------------------------------

### Import Reducto SDK

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/reducto-shim/README.md

Demonstrates the import statement for the Reducto Python SDK, whether installed as 'reducto' or 'reductoai'.

```python
import reducto
```

--------------------------------

### Nested Parameters Example

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/README.md

Demonstrates how to use nested parameters, which are represented as dictionaries and typed using TypedDict. The 'enhance' parameter is shown as an example.

```python
from reducto import Reducto

client = Reducto()

response = client.parse.run(
    input="string",
    enhance={},
)
print(response.enhance)
```

--------------------------------

### Asynchronous Extraction Example

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/extract.md

Demonstrates how to use the asynchronous `run` method to extract data from a PDF URL. Ensure you have initialized `AsyncReducto` with your API key.

```python
import asyncio
from reducto import AsyncReducto

async def main():
    async with AsyncReducto(api_key="your_api_key") as client:
        response = await client.extract.run(
            input="https://example.com/invoice.pdf",
            instructions={"type": "object", "properties": {...}}
        )
        print(f"Extracted: {response.result.data}")

asyncio.run(main())
```

--------------------------------

### Example: Upload with Custom Extension

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/uploads.md

Demonstrates uploading a file with a custom extension specified, overriding any inferred extension from the filename. This is useful when the file's actual type is not reflected in its name.

```python
result = client.upload(
    file=Path("/path/to/unknown_file"),
    extension="pdf"  # Force interpretation as PDF
)
```

--------------------------------

### Sync Dependencies with Rye

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/CONTRIBUTING.md

Alternatively, install Rye manually and sync all dependencies and features for the project.

```sh
$ rye sync --all-features
```

--------------------------------

### Parse with Direct Webhook Delivery

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/webhook.md

Example of initiating a parse job with direct webhook delivery configured. Results will be POST'd to the specified webhook URL upon completion.

```python
response = client.parse.run(
    input="https://example.com/document.pdf",
    async_={
        "webhook": {
            "type": "direct",
            "url": "https://your-server.com/reducto-webhook"
        }
    }
)

print(f"Job ID: {response.job_id}")
# When processing completes, results are POST'd to your webhook URL
```

--------------------------------

### Determine Installed Reducto Version

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/README.md

Check the installed version of the reducto package at runtime by importing the library and accessing the `__version__` attribute.

```python
import reducto
print(reducto.__version__)
```

--------------------------------

### Initialize Synchronous and Asynchronous Clients

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/README.md

Demonstrates how to initialize both synchronous and asynchronous clients for the Reducto SDK. The asynchronous client requires an `async with` block for proper management.

```python
# Synchronous
from reducto import Reducto
client = Reducto(api_key="key")
response = client.parse.run(input="...")

# Asynchronous
from reducto import AsyncReducto
async with AsyncReducto(api_key="key") as client:
    response = await client.parse.run(input="...")
```

--------------------------------

### get

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/job.md

Retrieves the status and details of a specific job using its ID. This is the asynchronous version of the get() method.

```APIDOC
## get (async)

### Description
Retrieves the status and details of a specific job using its ID. This is the asynchronous version of the get() method.

### Method
GET

### Endpoint
/jobs/{job_id}

### Parameters
#### Path Parameters
- **job_id** (str) - Required - The unique identifier of the job.

#### Query Parameters
None explicitly documented.

#### Request Body
None explicitly documented.

### Response
#### Success Response (200)
- **status** (str) - The current status of the job (e.g., 'processing', 'completed', 'failed').
- **result** (any) - The result of the job if completed.
- **error** (str) - The error message if the job failed.

#### Response Example
```json
{
  "status": "completed",
  "result": {
    "output_url": "http://example.com/result.zip"
  }
}
```
```

--------------------------------

### Initialize Reducto with Full Custom HTTP Client

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/configuration.md

Initialize the Reducto client using a fully customized httpx.Client instance with specific connection limits and timeouts.

```python
from reducto import Reducto
import httpx

custom_client = httpx.Client(
    limits=httpx.Limits(max_connections=20),
    timeout=httpx.Timeout(30.0)
)
client = Reducto(api_key="key", http_client=custom_client)
```

--------------------------------

### Initialize Reducto with DefaultHttpxClient and Proxy

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/configuration.md

Configure the Reducto client using DefaultHttpxClient, specifying a proxy server and disabling SSL verification. Note: Disabling SSL verification is not recommended for production environments.

```python
from reducto import Reducto, DefaultHttpxClient

client = Reducto(
    api_key="key",
    http_client=DefaultHttpxClient(
        proxy="http://proxy.example.com:8080",
        verify=False  # Disable SSL verification (not recommended)
    )
)
```

--------------------------------

### Initialize Asynchronous Reducto Client

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/client.md

Instantiate the asynchronous Reducto client using an async context manager. This client is designed for use with async/await syntax and accepts an asynchronous HTTP client.

```python
import asyncio
from reducto import AsyncReducto

async def main():
    # Basic async client
    async with AsyncReducto(api_key="your_api_key") as client:
        response = await client.parse.run(
            input="https://example.com/document.pdf"
        )
        print(response.job_id)

asyncio.run(main())
```

--------------------------------

### Initialize Reducto Client with API Key

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/configuration.md

Initialize the Reducto client using an API key. The key can be provided directly or read from the REDUCTO_API_KEY environment variable.

```python
from reducto import Reducto

# From environment variable
client = Reducto()

# Explicit API key
client = Reducto(api_key="your_api_key_here")
```

--------------------------------

### api_version

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/uploads.md

Get the current API version.

```APIDOC
## api_version

### Description
Get the current API version.

### Method
GET

### Endpoint
/api-version

### Response
#### Success Response (200)
- **version** (str) - The current API version string.

#### Response Example
```json
{
  "version": "v1"
}
```
```

--------------------------------

### Async Client Usage

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/README.md

Demonstrates the basic usage of the asynchronous Reducto client. API calls are made using 'await'. The client can be instantiated with an API key and environment, similar to the synchronous client.

```python
import os
import asyncio
from reducto import AsyncReducto

client = AsyncReducto(
    api_key=os.environ.get("REDUCTO_API_KEY"),  # This is the default and can be omitted
    # or 'production' | 'au'; defaults to "production".
    environment="eu",
)


async def main() -> None:
    response = await client.parse.run(
        input="https://pdfobject.com/pdf/sample.pdf",
    )


asyncio.run(main())
```

--------------------------------

### Get API Version

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/api.md

Retrieves the current API version of the Reducto service.

```APIDOC
## GET /version

### Description
Retrieves the current API version of the Reducto service.

### Method
GET

### Endpoint
/version

### Response
#### Success Response (200)
- **version** (string) - The API version string.
```

--------------------------------

### Initialize Synchronous Reducto Client

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/client.md

Instantiate the synchronous Reducto client. It can be initialized with an API key from the environment, explicitly provided, or configured for different environments. Advanced options include custom timeouts, retry counts, default headers/query parameters, and a custom httpx client.

```python
import os
from reducto import Reducto

# Basic initialization with API key from environment
client = Reducto()

# Explicit API key
client = Reducto(api_key="your_api_key_here")

# EU environment
client = Reducto(api_key="your_api_key", environment="eu")

# Custom timeout and retries
client = Reducto(
    api_key="your_api_key",
    timeout=20.0,
    max_retries=5,
)

# Custom httpx client with proxy
import httpx
from reducto import DefaultHttpxClient

client = Reducto(
    api_key="your_api_key",
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.example.com:8080"
    ),
)

# Context manager for resource cleanup
with Reducto(api_key="your_api_key") as client:
    response = client.parse.run(input="https://example.com/document.pdf")
```

--------------------------------

### Get Raw Response

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/job.md

Access the raw HTTP response for a job retrieval operation.

```APIDOC
## with_raw_response.get

### Description
Access raw HTTP response.

### Method
GET

### Endpoint
/job/{job_id}

### Parameters
#### Path Parameters
- **job_id** (str) - Yes - The ID of the job to retrieve

### Response
#### Success Response (200)
- **APIResponse** - Raw HTTP response object
```

--------------------------------

### Bootstrap Environment with Rye

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/CONTRIBUTING.md

Use this command to set up the development environment with Rye, which automatically provisions the correct Python version.

```sh
$ ./scripts/bootstrap
```

--------------------------------

### Get Job Details

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/job.md

Retrieve the status and details of a specific job using its ID.

```APIDOC
## get

### Description
Retrieve the status and details of a job.

### Method
GET

### Endpoint
/job/{job_id}

### Parameters
#### Path Parameters
- **job_id** (str) - Yes - The ID of the job to retrieve

#### Query Parameters
- **extra_query** (Query) - No - Additional query parameters

#### Request Body
- **extra_body** (Body) - No - Additional JSON body fields

#### Headers
- **extra_headers** (Headers) - No - Additional headers

#### Timeout
- **timeout** (float | httpx.Timeout) - No - Request timeout override

### Response
#### Success Response (200)
- **JobGetResponse** - Job status and metadata
  Contains: job_id, status (pending/processing/completed/failed), result data if available, creation time, completion time.

#### Error Handling
- **NotFoundError** - Job not found (HTTP 404)
- **APIStatusError** - Other HTTP errors
```

--------------------------------

### Client Initialization

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/README.md

Initialize the synchronous or asynchronous Reducto client with your API key. The client can be configured with different environments.

```APIDOC
## Client Initialization

### Description
Initialize the synchronous or asynchronous Reducto client with your API key. The client can be configured with different environments.

### Synchronous Client
```python
from reducto import Reducto

# With API key
client = Reducto(api_key="your_key")

# From environment variable
import os
os.environ["REDUCTO_API_KEY"] = "your_key"
client = Reducto()

# With specific environment
client = Reducto(api_key="key", environment="eu")
```

### Asynchronous Client
```python
from reducto import AsyncReducto

async with AsyncReducto(api_key="your_key") as client:
    # Use client here
    pass

# With specific environment
async with AsyncReducto(api_key="key", environment="au") as client:
    # Use client here
    pass
```

### Environments
- **production** (default): `https://platform.reducto.ai`
- **eu**: `https://eu.platform.reducto.ai`
- **au**: `https://au.platform.reducto.ai`
```

--------------------------------

### Get API Version (Asynchronous)

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/uploads.md

Asynchronous version of the api_version() function. Use this in async contexts.

```python
async def api_version(
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> str:
    pass
```

--------------------------------

### Authenticate with API Key

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/README.md

Demonstrates two methods for setting the API key: by setting the REDUCTO_API_KEY environment variable or by passing the key directly to the Reducto constructor.

```python
import os
from reducto import Reducto

# From environment
os.environ["REDUCTO_API_KEY"] = "your_key"
client = Reducto()

# Explicit
client = Reducto(api_key="your_key")
```

--------------------------------

### Get API Version (Synchronous)

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/uploads.md

Retrieves the API version string for the Reducto service. This is useful for compatibility checks.

```python
from reducto import Reducto

client = Reducto(api_key="your_api_key")

version = client.api_version()
print(f"API version: {version}")
```

--------------------------------

### Build Distributable Package

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/CONTRIBUTING.md

Create a distributable version of the library, generating source and wheel files in the 'dist/' directory.

```sh
$ rye build
# or
$ python -m build
```

--------------------------------

### Get API Version

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/api.md

Retrieves the current API version using the client. This method returns the API version as a string.

```python
client.api_version() -> str
```

--------------------------------

### Initialize Reducto Client and Parse Document

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/INDEX.md

Initializes the Reducto client with an API key and performs a document parsing operation using a provided URL. Ensure you have your API key and the correct input URL.

```python
from reducto import Reducto

client = Reducto(api_key="key")
response = client.parse.run(input="https://example.com/doc.pdf")
```

--------------------------------

### Get Raw HTTP Response

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/parse.md

Access the raw HTTP response instead of parsed data. Useful for examining headers, status codes, and raw body.

```python
response = client.parse.with_raw_response.run(
    input="https://example.com/document.pdf"
)
print(response.headers.get("X-Request-ID"))
parsed = response.parse()  # Get the ParseRunResponse
```

--------------------------------

### webhook.run()

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/INDEX.md

Configures a webhook. This can be called synchronously or asynchronously.

```APIDOC
## POST /configure_webhook

### Description
Configures a webhook. This can be called synchronously or asynchronously.

### Method
POST

### Endpoint
/configure_webhook

### Returns
str
```

--------------------------------

### Initialize Reducto with Custom HTTP Transport

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/configuration.md

Configure the Reducto client with a custom httpx transport, specifying a local address.

```python
from reducto import Reducto
import httpx

client = Reducto(
    api_key="key",
    http_client=httpx.HTTPTransport(
        local_address="0.0.0.0"
    )
)
```

--------------------------------

### Parse and Extract Document Data

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/README.md

Parse a document to get its structured content and then extract specific data based on provided instructions. This pattern is useful for retrieving targeted information.

```python
from reducto import Reducto

client = Reducto(api_key="key")

# Get parsed document
parse_result = client.parse.run(input="https://example.com/doc.pdf")

# Extract specific data
extract_result = client.extract.run(
    input="https://example.com/doc.pdf",
    instructions={
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "email": {"type": "string"}
        }
    }
)
```

--------------------------------

### Upload File using Bytes

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/uploads.md

Demonstrates uploading raw file content as bytes. Ensure the 'extension' parameter is provided if it cannot be inferred from the file name.

```python
with open("/path/to/document.pdf", "rb") as f:
    file_content = f.read()
response = client.upload(file=file_content)
```

--------------------------------

### client.with_options

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/client.md

Creates a new client instance with overridden options. This is useful for per-request customization without affecting the original client instance.

```APIDOC
## client.with_options

### Description
Creates a new client instance with overridden options. Used for per-request customization.

### Method Signature
```python
client.with_options(
    api_key: str | Omit = omit,
    base_url: str | httpx.URL | None | Omit = omit,
    timeout: float | Timeout | None | Omit = omit,
    max_retries: int | Omit = omit,
    default_headers: Mapping[str, str] | None | Omit = omit,
    default_query: Mapping[str, object] | None | Omit = omit,
    http_client: httpx.Client | None | Omit = omit,
) -> Self
```

### Parameters
#### Optional Parameters
- **api_key** (str | Omit) - Override API key for requests.
- **base_url** (str | httpx.URL | None | Omit) - Override base URL.
- **timeout** (float | Timeout | None | Omit) - Override timeout.
- **max_retries** (int | Omit) - Override retry count.
- **default_headers** (Mapping[str, str] | None | Omit) - Override default headers.
- **default_query** (Mapping[str, object] | None | Omit) - Override default query parameters.
- **http_client** (httpx.Client | None | Omit) - Override HTTP client.

### Returns
New client instance with modified options.

### Example
```python
# Override timeout for a specific request
client.with_options(timeout=10.0).parse.run(
    input="https://example.com/document.pdf"
)

# Use custom HTTP client for specific requests
client.with_options(
    http_client=custom_httpx_client
).parse.run(input="https://example.com/document.pdf")
```
```

--------------------------------

### Upload File using Tuple (filename, content, media_type)

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/uploads.md

Illustrates uploading a file by providing a tuple containing the filename, its content as bytes, and the media type. This is useful for in-memory file data.

```python
response = client.upload(
    file=("document.pdf", b"PDF content...", "application/pdf")
)
```

--------------------------------

### Handle Async Reducto API Errors in Python

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/errors.md

Handle errors asynchronously when using the Reducto SDK, including connection errors and rate limits. This example shows how to retry a failed asynchronous operation.

```python
import asyncio
import reducto

async def parse_document():
    async with reducto.AsyncReducto(api_key="key") as client:
        try:
            response = await client.parse.run(
                input="https://example.com/doc.pdf"
            )
            return response
        except reducto.APIConnectionError:
            print("Connection failed")
            return None
        except reducto.RateLimitError:
            await asyncio.sleep(60)
            return await parse_document()  # Retry

asyncio.run(parse_document())
```

--------------------------------

### Async Client Usage with aiohttp

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/README.md

Instantiate and use the asynchronous Reducto client with aiohttp as the HTTP backend. Use 'async with' for proper resource management. The environment and API key can be configured similarly to the synchronous client.

```python
import os
import asyncio
from reducto import DefaultAioHttpClient
from reducto import AsyncReducto


async def main() -> None:
    async with AsyncReducto(
        api_key=os.environ.get("REDUCTO_API_KEY"),  # This is the default and can be omitted
        http_client=DefaultAioHttpClient(),
    ) as client:
        response = await client.parse.run(
            input="https://pdfobject.com/pdf/sample.pdf",
        )


asyncio.run(main())
```

--------------------------------

### Configure Reducto Client with Custom HTTP Client

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/configuration.md

Use a custom httpx client instance for advanced HTTP configurations such as proxy settings, custom transports, connection pooling, and TLS/SSL settings. Use DefaultHttpxClient or DefaultAsyncHttpxClient to preserve SDK defaults while extending.

```python
import httpx
from reducto import Reducto, DefaultHttpxClient

# With proxy
client = Reducto(
    api_key="key",
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.com:8080"
    )
)
```

--------------------------------

### Reducto Constructor

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/client.md

Construct a new synchronous Reducto client instance. It allows configuration of API key, environment, base URL, timeout, retries, headers, query parameters, and an HTTP client.

```APIDOC
## Reducto Constructor

### Description
Construct a new synchronous Reducto client instance. It allows configuration of API key, environment, base URL, timeout, retries, headers, query parameters, and an HTTP client.

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| api_key | str \| None | No | None | API key for authentication. If not provided, reads from REDUCTO_API_KEY environment variable. Raises ReductoError if neither is set. |
| environment | Literal["production", "eu", "au"] \| NotGiven | No | not_given | Environment to connect to: "production" (https://platform.reducto.ai), "eu" (https://eu.platform.reducto.ai), or "au" (https://au.platform.reducto.ai). Defaults to "production". |
| base_url | str \| httpx.URL \| None \| NotGiven | No | not_given | Base URL for API requests. If provided, overrides environment setting. Can also be set via REDUCTO_BASE_URL environment variable. |
| timeout | float \| Timeout \| None \| NotGiven | No | not_given | Request timeout in seconds. Defaults to 1 hour (3600 seconds). Can be a float for a single timeout value, or httpx.Timeout for granular control. |
| max_retries | int | No | DEFAULT_MAX_RETRIES | Maximum number of retries for failed requests. Retried errors: connection errors, 408, 409, 429, and >=500 status codes. |
| default_headers | Mapping[str, str] \| None | No | None | Custom headers to include in all requests. |
| default_query | Mapping[str, object] \| None | No | None | Custom query parameters to include in all requests. |
| http_client | httpx.Client \| None | No | None | Custom httpx client instance. Allows configuration of proxies, transports, and other httpx options. Use DefaultHttpxClient to preserve defaults. |
| _strict_response_validation | bool | No | False | Enable strict validation of API responses against the schema. Raises APIResponseValidationError on validation failure. |

### Request Example
```python
import os
from reducto import Reducto

# Basic initialization with API key from environment
client = Reducto()

# Explicit API key
client = Reducto(api_key="your_api_key_here")

# EU environment
client = Reducto(api_key="your_api_key", environment="eu")

# Custom timeout and retries
client = Reducto(
    api_key="your_api_key",
    timeout=20.0,
    max_retries=5,
)

# Custom httpx client with proxy
import httpx
from reducto import DefaultHttpxClient

client = Reducto(
    api_key="your_api_key",
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.example.com:8080"
    ),
)

# Context manager for resource cleanup
with Reducto(api_key="your_api_key") as client:
    response = client.parse.run(input="https://example.com/document.pdf")
```

### Response
#### Success Response (200)
None

#### Response Example
None

### Raises

| Error | Condition |
|-------|-----------|
| ReductoError | api_key is not provided and REDUCTO_API_KEY environment variable is not set |
| ValueError | Unknown environment string provided, or both REDUCTO_BASE_URL and environment arguments are given |
```

--------------------------------

### Run Tests

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/CONTRIBUTING.md

Execute all tests for the repository using the provided script.

```sh
$ ./scripts/test
```

--------------------------------

### Configure HTTP Client with Proxies and Transports

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/README.md

Customize the underlying httpx client by providing a `DefaultHttpxClient` instance to the `Reducto` constructor. This allows for proxy configuration and custom transports.

```python
import httpx
from reducto import Reducto, DefaultHttpxClient

client = Reducto(
    # Or use the `REDUCTO_BASE_URL` env var
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)
```

--------------------------------

### Configure API Environments

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/README.md

Shows how to configure the Reducto client to use different API environments: production (default), Europe (eu), and Australia (au), by specifying the environment in the constructor.

```python
# Production (default)
client = Reducto(api_key="key", environment="production")
# https://platform.reducto.ai

# Europe
client = Reducto(api_key="key", environment="eu")
# https://eu.platform.reducto.ai

# Australia
client = Reducto(api_key="key", environment="au")
# https://au.platform.reducto.ai
```

--------------------------------

### Configure Webhook

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/api.md

Configures webhook settings for the Reducto service. This is a synchronous operation.

```APIDOC
## POST /configure_webhook

### Description
Configures webhook settings for the Reducto service. This is a synchronous operation.

### Method
POST

### Endpoint
/configure_webhook

### Response
#### Success Response (200)
- **string** - A confirmation message indicating the webhook configuration status.
```

--------------------------------

### Publish Manually to PyPI

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/CONTRIBUTING.md

Manually release a package by running the 'bin/publish-pypi' script with a PYPI_TOKEN set in the environment.

```sh
bin/publish-pypi
```

--------------------------------

### Manage HTTP Resources with a Context Manager

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/README.md

Use `Reducto` as a context manager to ensure that underlying HTTP connections are reliably closed when exiting the `with` block.

```python
from reducto import Reducto

with Reducto() as client:
  # make requests here
  ...
```

--------------------------------

### Use Custom HTTP Client for Specific Requests

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/client.md

Provide a custom `httpx.Client` instance to `with_options` for fine-grained control over the HTTP communication for a particular request.

```python
client.with_options(
    http_client=custom_httpx_client
).parse.run(input="https://example.com/document.pdf")
```

--------------------------------

### Upload File using PathLike

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/uploads.md

Shows how to upload a file by providing its local file path. This method infers the file extension from the path.

```python
from pathlib import Path
response = client.upload(file=Path("/path/to/document.pdf"))
```

--------------------------------

### pipeline.run()

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/INDEX.md

Initiates a pipeline job. This can be called synchronously or asynchronously.

```APIDOC
## POST /pipeline

### Description
Initiates a pipeline job. This can be called synchronously or asynchronously.

### Method
POST

### Endpoint
/pipeline

### Returns
PipelineResponse
```

--------------------------------

### Initialize CitationFinder

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/lib.md

Instantiate CitationFinder with a parse result. Ensure OCR data is enabled during parsing.

```python
from reducto.lib.citations import CitationFinder
from reducto import Reducto
from pathlib import Path

finder = CitationFinder(result)  # ParseResponse or Path to JSON file
citations = finder.cite(target, bbox_filter=None)
```

--------------------------------

### Synchronous Split Resource Run Method

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/split.md

Defines the signature for synchronous document splitting operations. It accepts input, split descriptions, and optional parsing and settings parameters.

```python
def run(
    *,
    input: split_run_params.Input,
    split_description: Iterable[SplitCategoryParam],
    parsing: ParseOptionsParam | Omit = omit,
    settings: SplitTableOptionsParam | Omit = omit,
    split_rules: str | Omit = omit,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> SplitResponse
```

--------------------------------

### Custom HTTP Client with Proxies

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/README.md

Configure a custom HTTP client, such as DefaultHttpxClient, to specify proxy settings for network requests.

```python
import httpx
from reducto import Reducto, DefaultHttpxClient

client = Reducto(
    api_key="key",
    http_client=DefaultHttpxClient(
        proxy="http://proxy.example.com:8080"
    )
)
```

--------------------------------

### Use Reducto Client as a Synchronous Context Manager

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/configuration.md

Manage resource cleanup by using the Reducto client as a synchronous context manager. HTTP connections are automatically closed upon exiting the 'with' block.

```python
# Synchronous
with Reducto(api_key="key") as client:
    response = client.parse.run(input="...")
# HTTP connections automatically closed
```

--------------------------------

### Configure Reducto Client Environment

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/configuration.md

Specify the API environment or region for the Reducto client. This determines the base URL for API requests. Supported environments are 'production', 'eu', and 'au'.

```python
# Connect to EU region
client = Reducto(api_key="key", environment="eu")

# Connect to AU region
client = Reducto(api_key="key", environment="au")
```

--------------------------------

### Synchronous Client Usage

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/README.md

Instantiate and use the synchronous Reducto client to make API calls. Ensure the REDUCTO_API_KEY environment variable is set or provide it directly. The environment can be specified as 'eu', 'au', or 'production'.

```python
import os
from reducto import Reducto

client = Reducto(
    api_key=os.environ.get("REDUCTO_API_KEY"),  # This is the default and can be omitted
    # or 'production' | 'au'; defaults to "production".
    environment="eu",
)

response = client.parse.run(
    input="https://pdfobject.com/pdf/sample.pdf",
)
```

--------------------------------

### Enable Reducto Logging via Environment Variable

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/README.md

Set the `REDUCTO_LOG` environment variable to `info` to enable logging of API requests and responses. Use `debug` for more verbose output.

```shell
$ export REDUCTO_LOG=info
```

--------------------------------

### PipelineResource.run

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/pipeline.md

Synchronously executes a custom pipeline on a document. It takes document input and a pipeline ID, with optional settings and extra headers/query/body parameters.

```APIDOC
## PipelineResource.run

### Description
Execute a custom pipeline on a document.

### Method
POST

### Endpoint
/pipeline/run

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **input** (str | list[str]) - Required - Document URL or list of URLs. Accepts: 1) Publicly available URLs, 2) Presigned S3 URLs, 3) reducto:// URLs from /upload, 4) jobid:// URLs from previous invocations, 5) List of URLs for multi-document pipelines
- **pipeline_id** (str) - Required - The ID of the pipeline to execute for document processing
- **settings** (PipelineSettingsParam) - Optional - Settings for pipeline execution that override pipeline defaults
- **extra_headers** (Headers) - Optional - Additional headers
- **extra_query** (Query) - Optional - Additional query parameters
- **extra_body** (Body) - Optional - Additional JSON body fields
- **timeout** (float | httpx.Timeout) - Optional - Request timeout override

### Request Example
```json
{
  "input": "https://example.com/document.pdf",
  "pipeline_id": "pipeline_abc123"
}
```

### Response
#### Success Response (200)
- **result** (PipelineResponse) - Results from pipeline execution
```

--------------------------------

### AsyncPipelineResource.run

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/pipeline.md

Asynchronously executes a custom pipeline on a document. This is the async version of `PipelineResource.run`.

```APIDOC
## AsyncPipelineResource.run

### Description
Asynchronous version of `run()`.

### Method
POST

### Endpoint
/pipeline/run

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **input** (str | list[str]) - Required - Document URL or list of URLs. Accepts: 1) Publicly available URLs, 2) Presigned S3 URLs, 3) reducto:// URLs from /upload, 4) jobid:// URLs from previous invocations, 5) List of URLs for multi-document pipelines
- **pipeline_id** (str) - Required - The ID of the pipeline to execute for document processing
- **settings** (PipelineSettingsParam) - Optional - Settings for pipeline execution that override pipeline defaults
- **extra_headers** (Headers) - Optional - Additional headers
- **extra_query** (Query) - Optional - Additional query parameters
- **extra_body** (Body) - Optional - Additional JSON body fields
- **timeout** (float | httpx.Timeout) - Optional - Request timeout override

### Request Example
```json
{
  "input": "https://example.com/document.pdf",
  "pipeline_id": "pipeline_abc123"
}
```

### Response
#### Success Response (200)
- **result** (PipelineResponse) - Results from pipeline execution
```

--------------------------------

### Configure Reducto Client Default Query Parameters

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/configuration.md

Include custom query parameters in all API requests. This allows for setting default parameters like version or debug flags.

```python
client = Reducto(
    api_key="key",
    default_query={
        "version": "v3",
        "debug": True
    }
)
```

--------------------------------

### AsyncReducto Constructor

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/client.md

Construct a new asynchronous Reducto client instance. It shares most parameters with the synchronous client but accepts an asynchronous HTTP client.

```APIDOC
## AsyncReducto Constructor

### Description
Construct a new asynchronous Reducto client instance. It shares most parameters with the synchronous client but accepts an asynchronous HTTP client.

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters

Same as Reducto, except:

| Parameter | Type | Change |
|-----------|------|--------|
| http_client | httpx.AsyncClient \| None | Accepts async HTTP client instead of sync |

### Request Example
```python
import asyncio
from reducto import AsyncReducto

async def main():
    # Basic async client
    async with AsyncReducto(api_key="your_api_key") as client:
        response = await client.parse.run(
            input="https://example.com/document.pdf"
        )
        print(response.job_id)

asyncio.run(main())
```

### Response
#### Success Response (200)
None

#### Response Example
None

### Raises

| Error | Condition |
|-------|-----------|
| ReductoError | api_key is not provided and REDUCTO_API_KEY environment variable is not set |
| ValueError | Unknown environment string provided, or both REDUCTO_BASE_URL and environment arguments are given |
```

--------------------------------

### Response Types and Methods

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/README.md

Explains how to work with response objects, including serialization to JSON, conversion to dictionaries, and checking field presence.

```APIDOC
## Response Types and Methods

### Description
Explains how to work with response objects, including serialization to JSON, conversion to dictionaries, and checking field presence.

All response types are Pydantic models with helper methods:

```python
response = client.parse.run(input="...")

# Serialize to JSON
json_str = response.model_dump_json()

# Convert to dict
dict_data = response.model_dump()

# Check which fields were set
if 'pdf_url' in response.model_fields_set:
    print(f"PDF available at: {response.pdf_url}")
```
```

--------------------------------

### Parse with Enhanced Options

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/parse.md

Demonstrates parsing a document with enhanced options for content enrichment, formatting, and retrieval. This snippet shows how to configure markdown formatting and smart chunking for retrieval.

```python
client.parse.run(
    input="https://pdfobject.com/pdf/sample.pdf",
    enhance={
        "enabled": True,
        "config": "default"
    },
    formatting={
        "type": "markdown"
    },
    retrieval={
        "type": "chunking",
        "chunking": {
            "type": "smart",
            "max_chunk_tokens": 1024
        }
    }
)
```

--------------------------------

### AsyncWebhookResource.run

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/api-reference/webhook.md

Access the webhook configuration portal URL asynchronously. This method retrieves a URL for configuring webhook settings, suitable for use in asynchronous applications.

```APIDOC
## AsyncWebhookResource.run (async)

### Description
Access the webhook configuration portal URL asynchronously. This method retrieves a URL for configuring webhook settings, suitable for use in asynchronous applications.

### Method
`run` (async)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
from reducto import AsyncReducto

async def main():
    async with AsyncReducto(api_key="your_api_key") as client:
        portal_url = await client.webhook.run()
        print(f"Configure webhooks at: {portal_url}")

asyncio.run(main())
```

### Response
#### Success Response (200)
- **URL** (str) - URL to the webhook configuration portal
```

--------------------------------

### Set Reducto API Key via Environment Variable

Source: https://github.com/reductoai/reducto-python-sdk/blob/main/_autodocs/configuration.md

Set the API key for authentication using the REDUCTO_API_KEY environment variable. This is automatically read if the api_key parameter is not provided to the constructor.

```bash
export REDUCTO_API_KEY="your_api_key_here"
```