oruk-compat Python batch candidate

Use a dedicated Python 3.12 environment. Install the included qualification lock with python -m pip install --require-hashes --only-binary=:all: -r requirements-qualified-py312.lock, then install a reviewed local wheel with python -m pip install --no-deps /absolute/path/oruk_compat-0.1.0a5-py3-none-any.whl. The lock records the exact qualified runtime dependencies; other Python/platform combinations need separate qualification. These commands do not imply ownership or availability of a PyPI project.

Alpha synchronous Python client for Oruk's supported Hume-shaped durable batch profile. It imports public response/request types from hume==0.13.13 with pydantic==2.13.5; it does not patch or copy Hume's client implementation. Oruk is not affiliated with Hume. The Oruk-hosted compatibility runtime is not yet enabled; use only an independently qualified endpoint. The default is https://speech-api.oruk.ai/compat/hume. Installing this package does not activate hosted inference.

from pathlib import Path
from oruk_compat import FileIdentityStore, OrukCompatClient, OrukBatchError
from hume.expression_measurement.batch.types.inference_base_request import InferenceBaseRequest
from hume.expression_measurement.batch.types.models import Models
from hume.expression_measurement.batch.types.prosody import Prosody

# Provision this private directory deliberately; keep one stable path per application task.
# Do not replace a lost volume with an empty directory during recovery.
store = FileIdentityStore(Path('/private/application/jobs/customer-task-123.json'))
client = OrukCompatClient(api_key=oruk_key, base_url='https://speech-api.oruk.ai/compat/hume',
                          persist_job=store.persist)
batch = client.expression_measurement.batch
saved = store.load()
if saved is not None:
    # Recovery is a read. A 404 does not authorize a new job ID or establish a refund.
    status = batch.get_job_details(saved.job_id)
else:
    job_id = batch.start_inference_job_from_local_file(
        file=[('input.flac', encoded_audio, 'audio/flac')],
        json=InferenceBaseRequest(models=Models(prosody=Prosody(granularity='utterance'))),
    )
    status = batch.get_job_details(job_id)
# Poll explicitly with a finite application deadline; only when COMPLETED:
# predictions = batch.get_job_predictions(status.job_id)

The application must associate the identity path with the account and task and retain it across restarts. FileIdentityStore requires an existing, owner-only POSIX directory with no symlinked parent. It creates one private record exclusively, writes and fsyncs it, then fsyncs the directory before permitting upload. Existing records must exactly match. Symlinks, hard links, broad permissions, duplicate JSON keys, partial or conflicting records are refused; no repair, overwrite, deletion or replacement ID is automatic. A partially written record after a crash needs reconciliation. Local fsync is not a guarantee about arbitrary mounted filesystems, backups, physical custody or account/task association. Windows file-store support is not claimed.

Alternatively provide persist_job(record, cancellation): atomically save or verify every immutable BatchIdentity field and return exactly True. Its to_dict() uses the same key-free record schema as the Node candidate: version, jobId, baseUrl, inputSha256, inputBytes, contentType and configSha256. It must reject existing identity/content conflicts and associate each record with the correct task/account. The client cannot prove an application's database durability. The callback runs in the original synchronous owner; exceptions/deadlines prevent sending.

Creation preserves the common Python Hume call shape and returns a job ID string. Status and predictions are parsed into pinned Hume types; use .model_dump()['oruk'] to access native extensions. Dict request settings or Hume InferenceBaseRequest are accepted. Only a single local binary file/tuple is supported, with word, utterance or conversational-turn prosody and optional identify_speakers. Bare prosody selects utterance in this durable profile. No URL input, multiple files, other models, callback URL or notification is supported. Six detected encodings are WAV, FLAC, MP3, Ogg, WebM and MP4. Media headers do not prove valid audio; the server decodes and enforces the one-hour limit. Audio is buffered under 30 MiB, JSON responses under 16 MiB. Standard binary file handles passed to creation are consumed and closed.

Each operation opens and closes its own HTTP connection with no connection pool, environment proxy, redirect, retry or hidden polling. HTTPS uses certificate verification; allow_insecure_localhost=True permits only http://127.0.0.1 in tests. At most four operations per client run concurrently, one per job ID. request_options allows only request_id, timeout_in_seconds (0.001–120; default 60) and a threading.Event cancel_event. The deadline is cooperative across the owned file read, persistence callback and HTTP operation. Socket operations use the remaining deadline; blocking DNS, arbitrary custom I/O or a callback that ignores cancellation can finish later. Cancellation cannot be taken as proof the server canceled accepted work. No thread or task is detached.

OrukBatchError exposes fixed code, retained job_id, optional status_code, conservative may_have_been_billed and automatic_retry=False. It hides raw provider bodies/errors and credentials. A GET error's billing flag describes only the GET. A lost response, timeout, crash or 404 never proves the original POST was unaccepted or unbilled. Load and reconcile the original identity; never mint a replacement ID to recover uncertainty. An explicit same-ID/same-content attempt uses request_options={'request_id': saved.job_id} and must pass the same persistence check.

Native scores remain native: the client refuses nonempty Hume emotion arrays, invented Hume confidence or a claimed validated crosswalk. All 48 Hume dimensions remain unmapped. This package supplies batch only; Python streaming and async wrappers remain separate work. It is not a complete HumeClient replacement or a key-and-base-URL-only migration. No registry ownership/publication or real model/deployment/customer acceptance is implied.

Version a2 corrects a1’s website-origin default. Preserve any existing a1 identity records for reconciliation; never edit their endpoint or mint a replacement ID automatically. Follow the pilot handoff for account/task association, uncertainty and cutover.

Account/task SQLite store (a3)

SQLiteTaskStore supplies a concrete local transaction for (account_id, task_id) and the complete immutable batch identity. Both IDs are case-sensitive application references: 1–128 ASCII letters, digits, underscore, dot, colon or hyphen, beginning with a letter or digit. They are not credentials or proof that a caller owns an account. Resolve them from the application's authorized task record; retain the approved API-key reference separately.

Provision once in an existing canonical owner-only POSIX directory, before enabling admissions:

from oruk_compat import SQLiteTaskStore

provisioned = SQLiteTaskStore.create('/private/application/jobs/tasks.sqlite')
# Save this value in independent application configuration, outside this volume.
expected_store_id = provisioned.store_id

Every normal start, including recovery, opens that existing store:

from oruk_compat import SQLiteTaskStore, OrukCompatClient

store = SQLiteTaskStore.open('/private/application/jobs/tasks.sqlite', store_id=expected_store_id)
task = store.bind(account_reference, application_task_id)
saved = task.load()
client = OrukCompatClient(api_key=oruk_key, persist_job=task.persist)
batch = client.expression_measurement.batch
if saved is not None:
    status = batch.get_job_details(saved.job_id)  # GET-only recovery
else:
    # Only a genuinely new approved application task may take this branch.
    job_id = batch.start_inference_job_from_local_file(file=[encoded_audio], json=config)

Competing workers generating different UUIDs for the same pair cannot both persist. The loser receives an error before upload; load the winning record and reconcile it with GET. Reusing a job UUID under another account/task also fails. Explicit same-ID/same-content attempts still depend on the server's idempotency contract; the store is not a distributed execution lock or a guarantee that an HTTP request is sent only once.

The store uses a rollback journal, synchronous=EXTRA, fullfsync=ON, immutable rows and exact schema/record checks. It closes its connection on every operation. SQLite's sync settings and Mac full-sync setting still depend on the filesystem and device honoring them. Local process-kill tests do not prove survival of physical power loss. No network filesystem, Windows, hostile same-UID mutation, encryption, deletion or automatic repair is supplied.

Opening uses SQLite mode=rw, never create-if-missing. Missing, replaced, symlinked, hard-linked, broadly accessible or malformed stores fail. Unsafe journal companions and WAL/SHM files are refused. Failed initialization leaves evidence for reconciliation; never call create as a fallback. The database is capped at 64 MiB, each encoded identity at 8 KiB. No API keys, audio or transcripts are saved. Database capacity or lock contention does not authorize a new job ID. Lock waiting is at most 100 ms per SQLite operation; cancellation is cooperative between operations and through SQLite's progress callback. Filesystem calls can outlast a deadline; no worker is detached.

A commit can succeed before acknowledgement fails or cancellation is observed. On any persistence error, the client retains its proposed ID and makes no upload; inspect the same account/task. TaskStoreError.code has fixed messages; absent remote jobs do not establish refunds or authorize another upload.

Restore matters: a correct store UUID does not prove a backup contains the latest tasks. Stop admissions while reconciling a restored snapshot with independently retained account/task identities and server records. Where an independent BatchIdentity exists, use task.load(expected=that_identity); a missing or changed record then fails. Without that external history, an older valid snapshot can make a previously submitted task appear new. The tests demonstrate this limitation explicitly. Do not copy a live SQLite file without a consistent SQLite backup procedure; qualify coordinated backup, custody, restore and volume-loss behavior for the actual application before enabling it.

Existing FileIdentityStore records are not imported or moved automatically. Keep their task association and original job IDs intact during any separately reviewed migration. a3 adds this store without changing the wire protocol or the supported analysis subset.

Sentence requests (granularity: sentence) require complete native word alignment and the server's sentence-capable release. The English transcript is grouped by Unicode sentence boundaries across adjacent model chunks; native speaker/turn boundaries end a group and trailing fragments are retained. Sentence timestamps use full aligned words, never interpolation; a boundary inside an aligned token is refused. Native scores stay at their measured segment intervals under oruk.native; sentence rows have empty Hume emotion arrays and no invented confidence. This does not promise Hume-equivalent segmentation or measurements.