ocular-ai 0.0.4

Official Python SDK for the Ocular AI Foundry Platform

Ocular AI Python SDK

Official Python SDK for interacting with the Ocular AI Platform.

Installation

pip install ocular

Quick Start

from ocular import Ocular

# Initialize the SDK with your API key
ocular = Ocular(api_key="your_api_key_here")

# Access a workspace
workspace = ocular.workspace("your_workspace_id")

# Get a project from the workspace
project = workspace.project("your_project_id")

# Get a version from the project
version = project.version("your_version_id")

# Get an export from the version
export = version.export("your_export_id")

# Download the export dataset
dataset_path = export.download()
print(f"Downloaded export to: {dataset_path}")

Configuration

The SDK can be configured using the following parameters:

ocular = Ocular(
    api_key="your_api_key",  # Required unless OCULAR_API_KEY env var is set
    api_url="https://api.ocular.ai/v1",  # Optional custom API URL
    timeout=30,  # Request timeout in seconds
    max_retries=3,  # Maximum number of retries for failed requests
    backoff_factor=0.5,  # Backoff factor for retries
    debug=False,  # Enable debug logging
)

You can also configure the SDK using environment variables:

• OCULAR_API_KEY: Your Ocular API key
• OCULAR_API_URL: The base URL for the Ocular API
• OCULAR_TIMEOUT: Default request timeout in seconds
• OCULAR_MAX_RETRIES: Maximum number of retries for failed requests
• OCULAR_BACKOFF_FACTOR: Backoff factor for retries
• OCULAR_DEBUG: Enable debug mode (set to "true", "1", or "yes")
• OCULAR_LOG_LEVEL: Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Error Handling

The SDK uses a structured error hierarchy for different types of errors:

from ocular.utils.errors import (
    OcularError,  # Base exception for all errors
    AuthenticationError,  # Authentication issues
    ValidationError,  # Invalid parameters
    ResourceNotFoundError,  # Resource not found
    RateLimitError,  # API rate limits exceeded
    ServerError,  # Server-side errors
    NetworkError,  # Network connectivity issues
    TimeoutError,  # Request timed out
)

try:
    workspace = ocular.workspace("invalid_id")
except ResourceNotFoundError as e:
    print(f"Workspace not found: {e}")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except OcularError as e:
    print(f"An error occurred: {e}")

Logging

The SDK uses Python's standard logging library. You can configure logging using:

from ocular.utils.logging import setup_logging

# Setup logging with custom settings
logger = setup_logging(
    level="DEBUG",
    log_file="ocular.log",  # Optional file to log to
)