Python models and configuration

Package: aic-sdk==3.2.0. Core SDK: 0.24.0. Source: Python wrapper 3.2.0. The fragments below use these imports. Supply license_key from your approved secret source and use the loaded model and initialized objects described in each section. For a complete file-processing example, follow the Python guide.

import os
import pathlib
import tempfile
from pathlib import Path
import typing
import aic_sdk as aic
from aic_sdk import Model, Processor, ProcessorConfig, OtelConfig

audio denotes a one-dimensional NumPy float32 array. Async fragments run inside an async function.

Model

class

Loaded model weights and model metadata. Create a model with Model.from_file(); there is no public Model() constructor. A loaded model can be shared by multiple processors. Native handles release their resources when Python releases the objects. Example

model = Model.from_file("/path/to/model.aicmodel")
processor = Processor(model, license_key)
config = ProcessorConfig.optimal(model)
processor.initialize(config)

Model.from_file()

static

@staticmethod
def from_file(path: str | os.PathLike | pathlib.Path) -> Model

Creates a new model instance backed by memory-mapped file data. Do not modify or delete that file while the model or any dependent processor, detector or analyzer remains alive. Native references retain model data after the Python model handle is released; automatic handle management does not make changing the backing file safe. Multiple models can be loaded for enhancement, voice activity detection or analysis. Parameters

str | os.PathLike | pathlib.Path

required

Path to the model file (.aicmodel). You can download models manually from artifacts.ai-coustics.io or use Model.download() to fetch them programmatically. Accepts both string paths and pathlib.Path objects.

Returns

Model: A new Model instance.

Raises

FileSystemError: The file cannot be opened.
ModelInvalidError or ModelVersionUnsupportedError: Invalid or incompatible model data.

Pass a valid filesystem path without embedded NUL characters. aic-sdk 3.2.0 does not consistently map a NUL-containing path to an SDK exception. Example

model = Model.from_file("/path/to/model.aicmodel")
model = Model.from_file(Path.cwd() / "model.aicmodel")

See also

artifacts.ai-coustics.io for available model IDs and downloads.

Model.download()

static

@staticmethod
def download(model_id: str, download_dir: str | os.PathLike | pathlib.Path) -> str

Downloads a model file from the ai-coustics artifact CDN. Resolves a compatible model through its manifest and downloads it to the specified directory. An existing file is reused if its checksum matches; otherwise it is replaced. Fresh manifests are reused from memory or the download directory according to the server’s cache lifetime. Stale manifests are revalidated. Resolution is retried when the model is absent or a failed download may reflect a changed mapping. Available models can be browsed at artifacts.ai-coustics.io. Parameters

str

required

The model identifier (e.g., "quail-ms-l-16khz").

str | os.PathLike | pathlib.Path

required

Directory where the model file will be stored.

Returns

str: The model file path. It remains relative when download_dir is relative.

Raises

ModelDownloadError: Manifest access, model selection, checksum, download or filesystem failure. Inspect details for the underlying cause.

This is a blocking operation that may perform network I/O.

Example

# Find model IDs at <https://artifacts.ai-coustics.io>
path = Model.download("rook-ms-l-16khz", "/tmp/models")

# Or using pathlib.Path
path = Model.download("rook-ms-l-16khz", Path(tempfile.gettempdir()) / "models")

model = Model.from_file(path)

Model.download_async()

static

@staticmethod
def download_async(model_id: str, download_dir: str | os.PathLike | pathlib.Path) -> typing.Awaitable[str]

Downloads a model file asynchronously from the ai-coustics artifact CDN. The network I/O runs on a background blocking task and does not block the caller’s event loop. Resolves a compatible model through its manifest and downloads it to the specified directory. An existing file is reused if its checksum matches; otherwise it is replaced. Fresh manifests are reused from memory or the download directory according to the server’s cache lifetime. Stale manifests are revalidated. Resolution is retried when the model is absent or a failed download may reflect a changed mapping. Available models can be browsed at artifacts.ai-coustics.io. Parameters

str

required

The model identifier (e.g., "quail-ms-l-16khz").

str | os.PathLike | pathlib.Path

required

Directory where the model file will be stored.

Returns

typing.Awaitable[str]: Await it to obtain the model file path, relative when download_dir is relative. The released .pyi says typing.Any; the wrapper returns an awaitable resolving to str. Background task failure can also raise RuntimeError.

Raises

ModelDownloadError: Manifest access, model selection, checksum, download or filesystem failure. Inspect details for the underlying cause.

Example

# Find model IDs at <https://artifacts.ai-coustics.io>
path = await Model.download_async("rook-ms-l-16khz", "/tmp/models")

# Or using pathlib.Path
path = await Model.download_async("rook-ms-l-16khz", Path(tempfile.gettempdir()) / "models")

model = Model.from_file(path)

Model.get_id()

def get_id(self) -> str

Returns the model identifier string. Returns

str: The model ID string.

Model.get_optimal_sample_rate()

def get_optimal_sample_rate(self) -> int

Retrieves the native sample rate of the model. This is the model’s native rate in Hz. It does not validate or configure your input. Use ProcessorConfig to describe the actual input rate and query get_optimal_block_size(sample_rate) for that rate. See audio format for supported rates and resampling. Returns

int: The model’s native sample rate in Hz.

Example

optimal_rate = model.get_optimal_sample_rate()
print(f"Optimal sample rate: {optimal_rate} Hz")

See also Latency and Non-native sample rates.

Model.get_optimal_block_size()

def get_optimal_block_size(self, sample_rate: int) -> int

Retrieves the optimal block size for the model at a given sample rate. Using the optimal block size minimizes latency by avoiding internal buffering. A non-optimal block size adds buffering latency on top of the model’s base delay. The optimal block size varies with sample rate because each model operates on a fixed time window. For example, a 10 ms window is 480 samples at 48 kHz and 160 samples at 16 kHz. Parameters

int

required

Sample rate in Hz for which to calculate the optimal block size.

Returns

int: The optimal block size for the given sample rate.

Example

sample_rate = model.get_optimal_sample_rate()
block_size = model.get_optimal_block_size(sample_rate)
print(f"Optimal block size: {block_size}")

ProcessorConfig

class

Audio configuration passed to Processor.initialize(), Vad.initialize() and Collector.initialize(). Use ProcessorConfig.optimal() as a starting point, then adjust fields to match your audio stream.

ProcessorConfig() constructor

ProcessorConfig(
    sample_rate: int,
    block_size: int,
    variable_block_size: bool = False,
) -> ProcessorConfig

Create a configuration value. Construction stores the fields; native initialization validates whether the combination is supported. Editing this object after initialization does not reconfigure a running processor, detector or collector. Reinitialize the owning object to apply changes. Parameters

int

required

Input sample rate in Hz. Native initialization supports 8,000–192,000 Hz, subject to the model and configuration. This field is converted to an unsigned 32-bit integer.

int

required

Number of mono samples per call, greater than zero. This field is converted to a platform-sized unsigned integer.

bool

default:"False"

Allow calls of up to block_size samples. With False, every call must contain exactly block_size samples.

ProcessorConfig.optimal()

static

@staticmethod
def optimal(
    model: Model,
    sample_rate: int | None = None,
    block_size: int | None = None,
    variable_block_size: bool = False,
) -> ProcessorConfig

Returns a ProcessorConfig with the model’s optimal settings and any supplied overrides. Parameters

Model

required

The Model instance to get optimal config for. See Model.

int | None

default:"None"

Custom sample rate in Hz. If None, uses the model’s optimal sample rate (default: None).

int | None

default:"None"

Custom number of samples per processing call. If None, uses the optimal block size for the sample rate (default: None). A non-optimal block size increases latency.

bool

default:"False"

Allow calls of up to block_size samples. With False, every call must contain exactly block_size samples.

Returns

ProcessorConfig: ProcessorConfig with optimal settings for the given model.

Example

# Use all optimal defaults
config = ProcessorConfig.optimal(model)
# Use a custom sample rate (optimal block size calculated automatically)
config = ProcessorConfig.optimal(model, sample_rate=44100)
# Use a custom sample rate and block size (increases latency)
config = ProcessorConfig.optimal(model, sample_rate=48000, block_size=512)

ProcessorConfig properties

ProcessorConfig.sample_rate

int

read/write

Input sample rate in Hz. Native initialization supports 8,000–192,000 Hz, subject to the model and configuration. This field is converted to an unsigned 32-bit integer.

ProcessorConfig.block_size

int

read/write

Number of mono samples per call, greater than zero. This field is converted to a platform-sized unsigned integer. A non-optimal block size increases latency.

ProcessorConfig.variable_block_size

bool

read/write

Allows calls of up to block_size samples, with added buffering latency. It does not change the sample rate or allow oversized blocks.

OtelConfig

class

OpenTelemetry (OTel) configuration for a Processor or Vad. Pass to Processor, ProcessorAsync, Vad or VadAsync to control telemetry per instance. When no OtelConfig is provided, telemetry is configured according to the runtime environment (e.g. the AIC_SDK_OTEL_ENABLE environment variable). Example

processor = Processor(model, license_key, otel_config=OtelConfig(enable=True, session_id="my-session"))

OtelConfig() constructor

OtelConfig(
    enable: bool,
    session_id: str | None = None,
    export_interval_ms: int = 0,
) -> OtelConfig

Creates an OpenTelemetry configuration value. enable is required; export_interval_ms is an unsigned 32-bit integer. Settings are copied into the native object at construction. Later edits to this value do not change an existing session. A session_id containing a NUL character raises InternalError when passed to a processor or detector constructor. OpenTelemetry controls optional observability, independently of SDK authorization and usage reporting. See telemetry. Parameters

bool

required

Whether to enable OpenTelemetry export.

str | None

default:"None"

Optional session ID. If None, a random ID is generated.

int

default:"0"

Metric export interval in ms. 0 uses the SDK default of 60,000 ms.

OtelConfig properties

OtelConfig.enable

bool

read/write

Whether to enable OpenTelemetry export. Overrides the AIC_SDK_OTEL_ENABLE environment variable.

OtelConfig.session_id

str | None

read/write

Optional session ID for telemetry. If None, a random session ID is generated.

OtelConfig.export_interval_ms

int

read/write

OpenTelemetry metric export interval in milliseconds. Set to 0 to use the SDK default of 60,000 ms.

get_sdk_version()

function

def get_sdk_version() -> str

Returns the version of the ai-coustics core SDK library used by this package. Returns

str: The library version as a string.

This is not necessarily the same as this package’s version.

Example

version = aic.get_sdk_version()
print(f"ai-coustics SDK version: {version}")

get_compatible_model_version()

function

def get_compatible_model_version() -> int

Returns the model file format version compatible with this core SDK build. This is a format number, not a model ID or model release version. Returns

int: The compatible model version number.

See the Python API index, Python guide and troubleshooting.

OtelConfig.repr()

def __repr__(self) -> str

Returns a diagnostic string containing the object’s current fields. It is not a serialization format.

ProcessorConfig.repr()

def __repr__(self) -> str

Returns a diagnostic string containing the object’s current fields. It is not a serialization format.

SDK

API reference

Upgrades

LiveKit

AI tools

Historical migrations

Python models and configuration

Model

Model.from_file()

Model.download()

Model.download_async()

Model.get_id()

Model.get_optimal_sample_rate()

Model.get_optimal_block_size()

ProcessorConfig

ProcessorConfig() constructor

ProcessorConfig.optimal()

ProcessorConfig properties

ProcessorConfig.sample_rate

ProcessorConfig.block_size

ProcessorConfig.variable_block_size

OtelConfig

OtelConfig() constructor

OtelConfig properties

OtelConfig.enable

OtelConfig.session_id

OtelConfig.export_interval_ms

get_sdk_version()

get_compatible_model_version()

OtelConfig.repr()

ProcessorConfig.repr()

​Model

​Model.from_file()

​Model.download()

​Model.download_async()

​Model.get_id()

​Model.get_optimal_sample_rate()

​Model.get_optimal_block_size()

​ProcessorConfig

​ProcessorConfig() constructor

​ProcessorConfig.optimal()

​ProcessorConfig properties

​ProcessorConfig.sample_rate

​ProcessorConfig.block_size

​ProcessorConfig.variable_block_size

​OtelConfig

​OtelConfig() constructor

​OtelConfig properties

​OtelConfig.enable

​OtelConfig.session_id

​OtelConfig.export_interval_ms

​get_sdk_version()

​get_compatible_model_version()

​OtelConfig.repr()

​ProcessorConfig.repr()

Model

Model.from_file()

Model.download()

Model.download_async()

Model.get_id()

Model.get_optimal_sample_rate()

Model.get_optimal_block_size()

ProcessorConfig

ProcessorConfig() constructor

ProcessorConfig.optimal()

ProcessorConfig properties

ProcessorConfig.sample_rate

ProcessorConfig.block_size

ProcessorConfig.variable_block_size

OtelConfig

OtelConfig() constructor

OtelConfig properties

OtelConfig.enable

OtelConfig.session_id

OtelConfig.export_interval_ms

get_sdk_version()

get_compatible_model_version()

OtelConfig.repr()

ProcessorConfig.repr()