Scopix

Documentation

Best Practices

Recommended patterns for production usage of the Scopix SDK

Use Environment Variables

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

python
import os
from scopix import Scopix


# Good: Load from environment
async with Scopix(api_key=os.getenv("SCOPIX_API_KEY")) as client:
    result = await client.files.upload("image.jpg")


# Even better: SDK auto-loads from SCOPIX_API_KEY
async with Scopix.from_env() as client:
    result = await client.files.upload("image.jpg")

Use Context Managers

Use context managers to ensure proper resource cleanup:

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


    result = await client.files.upload("image.jpg")

Batch Operations

Prefer batch operations over individual requests for better performance:

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


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

Handle Errors Gracefully

Catch specific exceptions and handle them appropriately:

python
from scopix import Scopix, RateLimitError, AuthenticationError, ScopixError


try:
    result = await client.files.upload("image.jpg")
except RateLimitError:
    # Wait and retry (SDK handles this automatically)
    pass
except AuthenticationError:
    # Check API key configuration
    logger.error("Authentication failed")
except ScopixError 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:

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


result = await client.files.upload("photo.jpg", on_progress=on_progress)

Batch progress

For batch uploads use client.files.upload_batch(...) and then poll client.files.get_processing_status(file_id) or client.files.wait_for_session(session_id, on_progress=...) for per-file progress tracking. Video and document uploads have their own dedicated callback surfaces.

Reuse the Client

Create one client instance and reuse it throughout your application:

python
# Good: Single client instance, reused across operations
async with Scopix.from_env() as client:
    result = await client.files.upload("image.jpg")
    results = await client.files.upload_batch(["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 Scopix.from_env() as client:  # Wasteful
        return await client.files.upload(path)

Performance Tip

Reuse the client instance to benefit from HTTP connection reuse. Each client maintains a persistent session that keeps connections alive across requests.

Related

Error Handling

Exception handling patterns