Metadata-Version: 2.3
Name: ocular-ai
Version: 0.0.3
Summary: Official Python SDK for the Ocular AI Foundry Platform
License: Apache-2.0
Keywords: ocular,ai,machine learning,sdk,api
Author: Vivek Lahole
Author-email: vivek@useocular.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: python-dotenv (>=0.15.0,<0.16.0)
Requires-Dist: requests (>=2.25.0,<3.0.0)
Requires-Dist: typing-extensions (>=4.1.0,<5.0.0)
Requires-Dist: urllib3 (>=1.26.0,<2.0.0)
Project-URL: Bug Tracker, https://github.com/OcularEngineering/ocular-python-sdk/issues
Project-URL: Documentation, https://docs.useocular.com
Project-URL: Homepage, https://github.com/OcularEngineering/ocular-python-sdk
Project-URL: Repository, https://github.com/OcularEngineering/ocular-python-sdk
Description-Content-Type: text/markdown

# Ocular AI Python SDK

Official Python SDK for interacting with the Ocular AI Platform.

## Installation

```bash
pip install ocular
```

## Quick Start

```python
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:

```python
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:

```python
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:

```python
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
)
```

