# RedenLab Extract SDK

Python SDK for RedenLab's ML inference service. Run machine learning models on audio files using AWS SageMaker async inference endpoints.

## Features

- Simple, Pythonic API for ML inference
- Automatic file upload to S3
- Async job management with polling
- Built-in retry logic and error handling
- Support for multiple ML models (intelligibility, speaker diarization, etc.)

## Installation

```bash
pip install redenlab-extract
```

## Quick Start

```python
from redenlab_ml import InferenceClient

# Initialize client with API key
client = InferenceClient(api_key="sk_live_your_api_key_here")

# Run inference on an audio file
result = client.predict(file_path="audio.wav")

print(result)
# {
#   'job_id': 'uuid',
#   'status': 'completed',
#   'result': {'intelligibility_score': 0.85},
#   'created_at': '2025-01-15T10:30:00Z',
#   'completed_at': '2025-01-15T10:35:00Z'
# }
```

## Authentication

The SDK looks for your API key in the following order:

1. **Constructor parameter**: `InferenceClient(api_key="sk_live_...")`
2. **Environment variable**: `REDENLAB_ML_API_KEY`
3. **Config file**: `~/.redenlab-ml/config.yaml`

### Using Environment Variables

```bash
export REDENLAB_ML_API_KEY=sk_live_your_api_key_here
```

```python
from redenlab_ml import InferenceClient

# API key is loaded from environment
client = InferenceClient()
result = client.predict(file_path="audio.wav")
```

### Using Config File

Create `~/.redenlab-ml/config.yaml`:

```yaml
api_key: sk_live_your_api_key_here
base_url: https://your-api-gateway-url.amazonaws.com/prod  # optional
model_name: intelligibility  # optional
```

```python
from redenlab_ml import InferenceClient

# API key is loaded from config file
client = InferenceClient()
result = client.predict(file_path="audio.wav")
```

## Advanced Usage

### Specify Model

```python
client = InferenceClient(
    api_key="sk_live_...",
    model_name="speaker_diarisation_workflow"
)
```

Available models:
- `intelligibility` (default)
- `speaker_diarisation_workflow`
- `ataxia-naturalness`
- `ataxia-intelligibility`

### Custom Timeout

```python
client = InferenceClient(
    api_key="sk_live_...",
    timeout=7200  # 2 hours
)
```

### Check Job Status

```python
# Get status of a running job
status = client.get_status(job_id="existing-job-uuid")
print(status['status'])  # 'processing', 'completed', 'failed'
```

### Error Handling

```python
from redenlab_ml import InferenceClient, InferenceError, TimeoutError, AuthenticationError

try:
    client = InferenceClient(api_key="sk_live_...")
    result = client.predict(file_path="audio.wav")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except TimeoutError as e:
    print(f"Inference timed out: {e}")
except InferenceError as e:
    print(f"Inference failed: {e}")
```

## Configuration Options

| Parameter | Environment Variable | Config File | Default |
|-----------|---------------------|-------------|---------|
| `api_key` | `REDENLAB_ML_API_KEY` | `api_key` | Required |
| `base_url` | `REDENLAB_ML_BASE_URL` | `base_url` | Production endpoint |
| `model_name` | `REDENLAB_ML_MODEL` | `model_name` | `intelligibility` |
| `timeout` | `REDENLAB_ML_TIMEOUT` | `timeout` | `3600` (1 hour) |

## Supported File Types

- WAV (`.wav`)
- MP3 (`.mp3`)
- M4A (`.m4a`)
- FLAC (`.flac`)

## Requirements

- Python 3.8+
- `requests`
- `tenacity`
- `pyyaml`

## Development

### Install Development Dependencies

```bash
# Clone from CodeCommit (requires AWS credentials)
git clone ssh://git-codecommit.us-west-2.amazonaws.com/v1/repos/redenlab-extract
cd redenlab-extract
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest tests/
```

### Code Formatting

```bash
black src/ tests/
ruff check src/ tests/
```

### Type Checking

```bash
mypy src/
```

## Examples

See the [examples/](examples/) directory for more usage examples:

- [quickstart.py](examples/quickstart.py) - Basic usage
- [batch_inference.py](examples/batch_inference.py) - Process multiple files
- [error_handling.py](examples/error_handling.py) - Robust error handling

## Documentation

- [API Reference](docs/api_reference.md)
- [Configuration Guide](docs/configuration.md)
- [Troubleshooting](docs/troubleshooting.md)

## Support

- Email: support@redenlab.com
- Website: https://redenlab.com

## License

MIT License - see [LICENSE](LICENSE) file for details

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
