Documentation

Best Practices

Recommended patterns for production usage of the AionVision SDK

Use Environment Variables

Never hardcode API keys. Use environment variables or a secrets manager:

import os
from aion import AionVision

# Good: Load from environment
async with AionVision(api_key=os.getenv("AIONVISION_API_KEY")) as client:
    result = await client.upload_one("image.jpg")

# Even better: SDK auto-loads from AIONVISION_API_KEY
async with AionVision.from_env() as client:
    result = await client.upload_one("image.jpg")

Use Context Managers

Use context managers to ensure proper resource cleanup:

# Async client (required for proper initialization)
async with AionVision.from_env() as client:
    # Chat sessions
    async with client.chat_session() as session:
        response = await session.send("Query")
    # Session automatically closed

    result = await client.upload_one("image.jpg")

Batch Operations

Prefer batch operations over individual requests for better performance:

# Good: Single batch upload
result = await client.upload([
    "image1.jpg",
    "image2.jpg",
    "image3.jpg",
])

# Bad: Multiple individual uploads
for img in images:
    await client.upload_one(img)  # Slower, more API calls

Handle Errors Gracefully

Catch specific exceptions and handle them appropriately:

from aion import AionVision

try:
    result = await client.upload_one("image.jpg")
except AionVision.RateLimitError:
    # Wait and retry (SDK handles this automatically)
    pass
except AionVision.AuthenticationError:
    # Check API key configuration
    logger.error("Authentication failed")
except AionVision.AionvisionError as e:
    # Handle other SDK errors
    logger.error(f"Upload failed: {e}")

Use Callbacks for Progress

For long-running operations, provide user feedback with callbacks:

def on_progress(event):
    print(f"Prepared: {event.filename} ({event.total_bytes} bytes)")

def on_complete(event):
    print(f"Uploaded: {event.result.image_id}")

result = await client.upload(
    files,
    on_progress=on_progress,
    on_file_complete=on_complete,
)

Reuse the Client

Create one client instance and reuse it throughout your application:

# Good: Single client instance, reused across operations
async with AionVision.from_env() as client:
    result = await client.upload_one("image.jpg")
    results = await client.upload(["img1.jpg", "img2.jpg"])
    search = await client.agent_search.images("query")

# Bad: Creating new clients for each operation
async def upload_image(path: str):
    async with AionVision.from_env() as client:  # Wasteful
        return await client.upload_one(path)

Performance Tip

Enable connection pooling and keep-alive by reusing the client instance. The SDK automatically manages connection pools for optimal performance.

Error Handling

Exception handling patterns

Batch Processing

Processing multiple files efficiently