Aurelio Platform SDK

Common errors

• ValueError: AURELIO_API_KEY environment variable not set.

  cause The `AurelioClient` constructor was called without a valid API key. The key must be passed directly or found in the `AURELIO_API_KEY` environment variable.
  fix Set the environment variable `export AURELIO_API_KEY="your_api_key_here"` or pass the key directly: `client = AurelioClient(api_key="your_api_key_here")`.

• ModuleNotFoundError: No module named 'aurelio_sdk'

  cause The `aurelio-sdk` package is not installed in the current Python environment or the environment is not activated.
  fix Install the package using pip: `pip install aurelio-sdk`. Ensure your virtual environment is activated if you are using one.

• ValidationError: 'quality' is not a valid enumeration member; permitted: 'aurelio-base', 'docling-base', 'gemini-2-flash-lite'

  cause An older, deprecated 'quality' parameter value (e.g., 'high' or 'low') was used when calling an extraction method, instead of the new explicit model names.
  fix Update your code to use the new model names, e.g., `model='aurelio-base'` or `model='docling-base'` instead of `quality='low'` or `quality='high'`.

Warnings

• deprecated The `quality` parameter (e.g., 'low', 'high') for document extraction models is deprecated. Use specific model names like `aurelio-base`, `docling-base`, or `gemini-2-flash-lite` instead.
  Fix: Replace `quality='high'` with `model='docling-base'` or `quality='low'` with `model='aurelio-base'`.
• gotcha For large files or potentially long-running extraction requests, it's crucial to enable polling and implement robust error handling. If `wait` is not sufficiently long or polling is not configured, the client might return before the process completes.
  Fix: Set the `wait` parameter to an appropriate timeout value for synchronous calls, or use the `AsyncAurelioClient` with explicit polling logic for more control over long-running tasks. Always check `response.status`.
• gotcha The SDK offers both synchronous (`AurelioClient`) and asynchronous (`AsyncAurelioClient`) APIs. Choosing the right client is important for performance, especially in I/O-bound applications or when processing multiple documents concurrently.
  Fix: Use `AsyncAurelioClient` and `await` calls within an `async def` function for better performance when dealing with many concurrent requests or large file processing.

Install

• pip install aurelio-sdk Install with pip

Imports

• AurelioClient
  wrong:

  from aurelio_sdk.client import AurelioClient

  correct:

  from aurelio_sdk import AurelioClient

  The primary client class is directly exposed at the top level of the package, not in a submodule.
• AsyncAurelioClient

  from aurelio_sdk import AsyncAurelioClient

  For asynchronous operations, the AsyncAurelioClient is available at the top level.

Quickstart

Initializes the AurelioClient with an API key from environment variables and demonstrates how to extract text from a URL. It also includes error handling and checks for the extraction status. Remember to replace the URL or use `extract_file` for local documents.

import os
from aurelio_sdk import AurelioClient
from dotenv import load_dotenv

# Load environment variables from a .env file (optional, but good practice for API keys)
load_dotenv()

# Ensure your API key is set as an environment variable or passed directly
api_key = os.environ.get("AURELIO_API_KEY")

if not api_key:
    raise ValueError("AURELIO_API_KEY environment variable not set.")

client = AurelioClient(api_key=api_key)

# Example: Extract text from a URL
# For a real file, replace with client.extract_file(file_path="your_document.pdf")
try:
    print("Attempting to extract text from a URL...")
    response = client.extract_url(
        url="https://www.aurelio.ai/blog/building-with-openai-agents-sdk",
        model="aurelio-base", # Use the new model names
        wait=60 # Wait up to 60 seconds for completion
    )

    if response.status == "completed":
        print(f"Extraction Status: {response.status}")
        print(f"Extracted Document ID: {response.document.id}")
        if response.chunks:
            print("First chunk of extracted text:")
            print(response.chunks[0].text[:500] + "...") # Print first 500 chars
        else:
            print("No chunks extracted.")
    else:
        print(f"Extraction did not complete. Status: {response.status}. Message: {response.message}")

except Exception as e:
    print(f"An error occurred during extraction: {e}")