> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-coustics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rust models and configuration

> Model loading, borrowed data, configuration fields and SDK metadata in aic-sdk 0.24.0.

**Crate:** `aic-sdk = "=0.24.0"`. **Core SDK:** `0.24.0`. Signatures and behavior are based on the [released crate source](https://docs.rs/crate/aic-sdk/0.24.0/source/). For installation and a complete audio program, use the [Rust guide](/reference/sdk/language-bindings/rust).

Signatures below are declarations. Use the root exports, for example `use aic_sdk::{AicError, Model, OtelConfig, ProcessorConfig};`. `Path` and `PathBuf` refer to `std::path` types.

<a id="rust-aic_sdk-Model" />

## Model

```rust theme={null}
pub struct Model<'a> { /* private fields */ }
```

A native model handle. Choose a model matching the operation: enhancement for `Processor`, dedicated voice activity detection (VAD) for `Vad` and Tyto analysis for the analyzers. One model can supply several independent processing instances.

File loading creates a `Model<'static>`. Buffer loading creates a `Model<'a>` borrowing its input bytes. The backing bytes must remain valid and immutable for all dependent processors, VADs and analyzers, even if you drop the original model handle. Native reference counting keeps model storage alive; it does not extend the Rust lifetime of borrowed bytes. A file-backed model's file must not be modified or deleted while the model or dependent objects exist.

`Model` implements `Drop`, `Send` and `Sync`. Dropping the handle releases its native reference. It does not implement `Clone`; share a reference or use `Arc<Model<'static>>` when appropriate.

<a id="rust-aic_sdk-Model-from_file" />

### Model::from\_file

```rust theme={null}
pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Model<'static>, AicError>
```

Loads a model from `path`. This is blocking setup work. File and model failures return `FileSystemError`, `ModelInvalid` or `ModelVersionUnsupported`, as applicable. Pass a valid path without embedded NUL characters: this release uses `CString::new(...).unwrap()`, so a NUL-containing path can panic rather than return `AicError`.

<a id="rust-aic_sdk-Model-from_buffer" />

### Model::from\_buffer

```rust theme={null}
pub fn from_buffer(buffer: &'a [u8]) -> Result<Self, AicError>
```

Borrows model bytes without copying the backing buffer. The address must be aligned to 64 bytes; an ordinary `Vec<u8>` does not guarantee that alignment. Misalignment returns `ModelDataUnaligned`; invalid contents return model errors. The borrow is carried by the returned model and dependent native objects.

<a id="rust-aic_sdk-include_model" />

### include\_model!

```rust theme={null}
include_model!(path_expression)
```

Embeds a model file using `include_bytes!` inside a 64-byte-aligned static allocation and evaluates to a reference to its bytes. The path follows `include_bytes!` resolution relative to the Rust source file. The file must exist at compile time; this macro does not download it. Its static storage can be used by async processing types.

This declaration is a compile-time embedding pattern; replace the path with an existing compatible model file:

```rust theme={null}
use aic_sdk::{include_model, AicError, Model};

static MODEL_BYTES: &[u8] = include_model!("path/to/model.aicmodel");

fn load_embedded() -> Result<Model<'static>, AicError> {
    Model::from_buffer(MODEL_BYTES)
}
```

<a id="rust-aic_sdk-Model-id" />

### Model::id

```rust theme={null}
pub fn id(&self) -> &str
```

Returns the model ID borrowed from the native handle. Returns `"unknown"` if the native string is null or cannot be decoded as UTF-8. The borrowed string cannot outlive this model handle.

<a id="rust-aic_sdk-Model-optimal_sample_rate" />

### Model::optimal\_sample\_rate

```rust theme={null}
pub fn optimal_sample_rate(&self) -> u32
```

Returns the model's native sample rate in Hz. This query does not configure or validate an input stream.

<a id="rust-aic_sdk-Model-optimal_block_size" />

### Model::optimal\_block\_size

```rust theme={null}
pub fn optimal_block_size(&self, sample_rate: u32) -> usize
```

Returns the preferred sample count per processing call at `sample_rate`. Use the stream's actual rate. Initialization validates support for the rate and block combination. Metadata queries return values directly and assert native success; they do not return `Result` for internal native failures.

<a id="rust-aic_sdk-Model-download" />

### Model::download

**Requires feature:** `download-model`. Absent when that feature is disabled.

```rust theme={null}
pub fn download<P: AsRef<Path>>(
    model_id: &str,
    download_dir: P,
) -> Result<std::path::PathBuf, AicError>
```

Resolves the model ID against a manifest using the core SDK's compatible model file version, downloads compatible data and returns its path. The result remains relative when `download_dir` is relative. Creates missing destination directories.

The downloader can reuse a fresh manifest in memory or in the download directory according to server cache lifetime. It revalidates stale entries, retries manifest resolution when needed and reuses a model file only when its SHA-256 matches. Replacement data is checked before installation. Failures return `AicError::ModelDownload(String)` with the underlying detail. This method blocks and has no async Rust counterpart in this release; provision models before processing.

<a id="rust-aic_sdk-ProcessorConfig" />

## ProcessorConfig

```rust theme={null}
pub struct ProcessorConfig {
    pub sample_rate: u32,
    pub block_size: usize,
    pub variable_block_size: bool,
}
```

Construct with a struct literal or `optimal`. Configuration is copied into the processor, detector or collector at initialization; changing the value later does not reconfigure it. There is no `Default` implementation.

<a id="rust-aic_sdk-ProcessorConfig-sample_rate" />

<a id="rust-aic_sdk-ProcessorConfig-block_size" />

<a id="rust-aic_sdk-ProcessorConfig-variable_block_size" />

| Field                       | Contract                                                                                                   |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `sample_rate: u32`          | Actual input rate in Hz; native initialization accepts 8,000–192,000 Hz subject to the model/configuration |
| `block_size: usize`         | Positive mono sample count per fixed call, or maximum call length with variable blocks                     |
| `variable_block_size: bool` | `false`: exactly `block_size` samples. `true`: calls up to `block_size`, with additional buffering delay   |

<a id="rust-aic_sdk-ProcessorConfig-optimal" />

### ProcessorConfig::optimal

```rust theme={null}
pub fn optimal(model: &Model) -> Self
```

Uses the model native rate, its preferred block size at that rate and `variable_block_size: false`. Override fields before initialization when the input has a different rate.

<a id="rust-aic_sdk-ProcessorConfig-with_variable_block_size" />

### ProcessorConfig::with\_variable\_block\_size

```rust theme={null}
pub fn with_variable_block_size(self, variable_block_size: bool) -> Self
```

Consumes the configuration, sets the flag and returns the updated configuration. Does not initialize an object.

<a id="rust-aic_sdk-OtelConfig" />

## OtelConfig

```rust theme={null}
pub struct OtelConfig {
    pub enable: bool,
    pub session_id: Option<String>,
    pub export_interval_ms: u32,
}
```

Optional per-instance OpenTelemetry settings for processor and VAD constructors. Without an explicit configuration, native environment defaults apply. These settings control observability separately from mandatory authorization and usage reporting. See [telemetry](/reference/concepts/sdk-telemetry).

<a id="rust-aic_sdk-OtelConfig-enable" />

<a id="rust-aic_sdk-OtelConfig-session_id" />

<a id="rust-aic_sdk-OtelConfig-export_interval_ms" />

| Field                        | Contract                                                                                                                             |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `enable: bool`               | Overrides the runtime environment's enable setting                                                                                   |
| `session_id: Option<String>` | `None` requests an automatically generated ID; an embedded NUL causes `AicError::Internal` when constructing a processor or detector |
| `export_interval_ms: u32`    | Positive values override the interval in milliseconds; zero uses the SDK default of 60,000 ms                                        |

There is no `Default` implementation. Configuration is copied at construction; subsequent changes do not affect existing sessions.

<a id="rust-aic_sdk-OtelConfig-disabled" />

### OtelConfig::disabled

```rust theme={null}
pub fn disabled() -> Self
```

Returns `{ enable: false, session_id: None, export_interval_ms: 0 }`.

<a id="rust-aic_sdk-OtelConfig-enabled" />

### OtelConfig::enabled

```rust theme={null}
pub fn enabled() -> Self
```

Returns `{ enable: true, session_id: None, export_interval_ms: 0 }`.

<a id="rust-aic_sdk-OtelConfig-with_session_id" />

### OtelConfig::with\_session\_id

```rust theme={null}
pub fn with_session_id(session_id: impl Into<String>) -> Self
```

Returns enabled telemetry with the converted session ID and interval zero.

<a id="rust-aic_sdk-get_sdk_version" />

## get\_sdk\_version

```rust theme={null}
pub fn get_sdk_version() -> &'static str
```

Returns the loaded native SDK version, which is separate from the Cargo package version. Returns `"unknown"` for an undecodable native string. Under `runtime-linking`, this is an SDK call that can trigger automatic library loading.

<a id="rust-aic_sdk-get_compatible_model_version" />

## get\_compatible\_model\_version

```rust theme={null}
pub fn get_compatible_model_version() -> u32
```

Returns the compatible model file format version. This is not the model ID or model release version.

## Configuration example

This example needs no model or SDK key:

```rust theme={null}
use aic_sdk::{OtelConfig, ProcessorConfig};

fn main() {
    let config = ProcessorConfig {
        sample_rate: 16_000,
        block_size: 160,
        variable_block_size: false,
    }.with_variable_block_size(true);
    assert!(config.variable_block_size);
    let telemetry = OtelConfig::disabled();
    assert!(!telemetry.enable);
}
```

See the [symbol index](/reference/sdk/api/rust/index) and [features, errors and traits](/reference/sdk/api/rust/errors-and-features).