Metadata-Version: 2.4
Name: oruk
Version: 0.2.5
Summary: Official Python client for the oruk Speech API: English transcription, calibrated multilabel emotion and speaking-style labels, and unified audio analysis.
Project-URL: Homepage, https://oruk.ai
Project-URL: Documentation, https://oruk.ai/docs
Project-URL: Changelog, https://oruk.ai/changelog
Project-URL: Pricing, https://oruk.ai/pricing
Author-email: oruk labs <access@oruk.ai>
License: MIT
Keywords: audio analysis,emotion detection,oruk,paralinguistics,speech,speech emotion recognition,speech understanding,speech-to-text,transcription
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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 :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Description-Content-Type: text/markdown

# oruk — Python client for the oruk Speech API

Official Python SDK for [oruk](https://oruk.ai), the speech lab building audio
models for English transcription, calibrated multilabel emotion detection,
speaking-style classification, and unified audio analysis.

This SDK calls the file API: send a prerecorded English audio file (WAV, FLAC, MP3,
M4A, OGG, or WebM; up to 30 MB / 60 minutes), get structured results back.
Resonance is oruk’s flagship speech recognition model. Plans include audio minutes, measured by the second with a one-second minimum. The separate Realtime preview supports 32 locales and phrase-level emotion scores over WebSocket; see the [realtime reference](https://oruk.ai/docs#realtime).

## Install

```bash
python -m pip install https://oruk.ai/sdk/oruk-0.2.5-py3-none-any.whl
```

## Quickstart

Create an account at [oruk.ai](https://oruk.ai/auth/signup) (plans from
$5/month, 7-day standard self-serve trial, card required, $0 today) and create an API key in the
developer portal.

```python
import os
from oruk import Oruk

with Oruk(api_key=os.environ["ORUK_API_KEY"]) as client:
    result = client.analyze("sample.wav", model="oruk-resonance")

print(result["text"])       # English transcript
print(result["emotions"])   # calibrated multilabel emotion scores
print(result["styles"])     # calibrated multilabel speaking-style scores
```

## Endpoints

| Method | API endpoint | Returns |
|---|---|---|
| `client.transcribe(file)` | `POST /v1/audio/transcriptions` | English transcript |
| `client.emotions(file)` | `POST /v1/audio/emotions` | 15 calibrated emotion labels, no transcription |
| `client.styles(file)` | `POST /v1/audio/styles` | 16 calibrated speaking-style labels |
| `client.affect(file)` | `POST /v1/audio/affect` | emotion + style, no transcript |
| `client.analyze(file)` | `POST /v1/audio/analysis` | transcript, labels, segments, tagged text |
| `client.proficiency(file, transcript=None)` | `POST /v1/audio/proficiency` | Preview: CEFR band, 0–5 score, fluency, transcript |

Every method accepts a path, `Path`, or binary file object, plus optional
`model=` (`oruk-resonance`, `oruk-fourier`) and `request_id=` arguments.
With `model="oruk-resonance"`, pass `diarize=True` (and optionally
`num_speakers=`) to label speakers: diarization locates the speaker turns,
then Resonance scores each speaker turn, so every segment carries a
`speaker` field with its own text, emotions, and styles. Diarization is included in plan minutes.

```python
result = client.analyze("support-call.wav", model="oruk-resonance", diarize=True)
for seg in result["segments"]:
    print(seg["speaker"], seg["text"], seg["emotions"][0]["label"])
```

Emotion only: `client.emotions(...)` on Resonance runs the encoder and affect
head and never invokes the transcription decoder, so nothing is transcribed,
the result has no transcript. One audio minute uses one plan minute for either emotion-only or unified analysis; calling both separately processes the audio twice.

```python
result = client.emotions("support-call.wav", model="oruk-resonance")
print(result["emotions"][0])            # {'label': 'happy', 'score': 0.97}
print(result.get("text"))               # None: no transcript is produced
```

The client sends a unique request ID per call and retries only 429 and
transient 5xx responses with jittered backoff. Errors raise `OrukAPIError`
with `status`, `code`, and `request_id` attributes.

## Links

- Documentation and API reference: <https://oruk.ai/docs>
- Capabilities and scope: <https://oruk.ai/capabilities>
- Pricing: <https://oruk.ai/pricing>
- Benchmarks: <https://oruk.ai/benchmarks/methodology>
- Service status: <https://oruk.ai/status>

## License

MIT
