> ## 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.

# Migrate Python SDK 1.3 to 2.0

> Upgrade to ai-coustics Python SDK 2.0 with the new model architecture, renamed parameters, and updated processing behavior.

Version 2.0 separates model loading from audio processing, ships models via external downloads, and introduces breaking API changes. Use this guide to migrate safely and verify behavior before rolling to production.

<Warning>
  License keys generated for version 1.3 do not work with 2.0. Generate a new key from the [developer platform](https://developers.ai-coustics.com/).
</Warning>

## Quick migration checklist

<Steps>
  <Step title="Regenerate your license key">
    Create a new license key in the developer platform and store it in `AIC_SDK_LICENSE`.
  </Step>

  <Step title="Update model IDs">
    Replace 1.3 enums with 2.0 model IDs (for example `QUAIL_VF_STT_L16` → `quail-vf-l-16khz`). [Model Name Migration Guide](/models/older-models/model-naming-changes).
  </Step>

  <Step title="Adopt the new architecture">
    Download models with `aic.Model.download`, load with `aic.Model.from_file`, then create a `ProcessorConfig` and `Processor`.
    Parameters are now set through `ProcessorContext` instead of the processor to enable safer multi-threaded usage.
  </Step>

  <Step title="Rename parameters">
    Update `AICParameter`/`AICVadParameter` to `ProcessorParameter`/`VadParameter` (CamelCase).
  </Step>

  <Step title="Validate async usage">
    Switch to `ProcessorAsync` for asynchronous processing and `Model.download_async` for downloads.
  </Step>
</Steps>

## Breaking changes summary

1. **Import name changed from `aic` to `aic_sdk`** (use `import aic_sdk as aic` for convenience).
2. Model names changed (`Quail` → `Sparrow`, `Quail-STT` → `Quail`).
3. New license keys required; old keys fail in 2.0.
4. New architecture splits `Model`, `ProcessorConfig`, `Processor` and `ProcessorContext`.
5. Parameter enums renamed from `SNAKE_CASE` to `CamelCase`.
6. Models are downloaded separately; no longer bundled.

## Model naming changes

Models were renamed to clarify use cases, check the [Model Name Migration Guide](/models/older-models/model-naming-changes)

## Architecture changes

<Tabs>
  <Tab title="1.3">
    ```python theme={null}
    from aic import Model, AICModelType

    model = Model(
        AICModelType.QUAIL_VF_STT_L16,
        license_key=license_key,
        sample_rate=16000,
        channels=1,
        frames=160,
    )
    ```
  </Tab>

  <Tab title="2.0">
    ```python theme={null}
    import aic_sdk as aic

    # 1) Download and load the model
    model_path = aic.Model.download("quail-vf-l-16khz", "./models")
    model = aic.Model.from_file(model_path)

    # 2) Create configuration
    config = aic.ProcessorConfig.optimal(model)

    # 3) Create processor
    processor = aic.Processor(model, license_key, config)
    ```
  </Tab>
</Tabs>

**Benefits**

* Reuse one model across multiple processors.
* Smaller package footprint because models download separately.

## API changes (quick reference)

| Operation           | 1.3                                                 | 2.0                                                 |
| ------------------- | --------------------------------------------------- | --------------------------------------------------- |
| Import              | `from aic import Model, AICModelType, AICParameter` | `import aic_sdk as aic`                             |
| Model creation      | `Model(AICModelType.QUAIL_VF_STT_L16, ...)`         | `Model.download()` + `Model.from_file()`            |
| Configuration       | Inline constructor params                           | `ProcessorConfig`                                   |
| Processing          | `model.process(audio)`                              | `processor.process(audio)`                          |
| Set parameter       | `model.set_parameter(AICParameter.*, val)`          | `proc_ctx.set_parameter(ProcessorParameter.*, val)` |
| Get parameter       | `model.get_parameter(AICParameter.*)`               | `proc_ctx.get_parameter(ProcessorParameter.*)`      |
| Get latency         | `model.processing_latency()`                        | `proc_ctx.get_output_delay()`                       |
| Optimal frames      | `model.optimal_num_frames()`                        | `model.get_optimal_num_frames(sample_rate)`         |
| Optimal sample rate | `model.optimal_sample_rate()`                       | `model.get_optimal_sample_rate()`                   |
| Reset state         | `model.reset()`                                     | `proc_ctx.reset()`                                  |
| Create VAD          | `model.create_vad()`                                | `processor.get_vad_context()`                       |
| VAD parameters      | `vad.set_parameter(AICVadParameter.*, val)`         | `vad.set_parameter(VadParameter.*, val)`            |
| Cleanup             | `model.close()`                                     | Automatic                                           |

<Note>
  Parameters are now controlled through `ProcessorContext` (obtained via `processor.get_processor_context()`) instead of directly on the processor. This design enables safer multi-threaded usage where each thread can maintain its own processing context.
</Note>

## Parameter changes

### `ProcessorParameter` (was `AICParameter`)

| 1.3                              | 2.0                                         |
| -------------------------------- | ------------------------------------------- |
| `AICParameter.BYPASS`            | `ProcessorParameter.Bypass`                 |
| `AICParameter.ENHANCEMENT_LEVEL` | `ProcessorParameter.EnhancementLevel`       |
| `AICParameter.VOICE_GAIN`        | `ProcessorParameter.VoiceGain`              |
| `AICParameter.NOISE_GATE_ENABLE` | Removed (now used automatically by the VAD) |

### `VadParameter` (was `AICVadParameter`)

| 1.3                                       | 2.0                                  |
| ----------------------------------------- | ------------------------------------ |
| `AICVadParameter.SPEECH_HOLD_DURATION`    | `VadParameter.SpeechHoldDuration`    |
| `AICVadParameter.SENSITIVITY`             | `VadParameter.Sensitivity`           |
| `AICVadParameter.MINIMUM_SPEECH_DURATION` | `VadParameter.MinimumSpeechDuration` |

## Complete migration example

<Tabs>
  <Tab title="1.3">
    ```python theme={null}
    import os
    from aic import Model, AICModelType, AICParameter, AICVadParameter
    import numpy as np

    license_key = os.getenv("AIC_SDK_LICENSE")

    model = Model(
        AICModelType.QUAIL_VF_STT_L16,
        license_key=license_key,
        sample_rate=16000,
        channels=1,
        frames=160,
    )

    print(f"Latency: {model.processing_latency() / 16000 * 1000:.2f}ms")
    print(f"Optimal frames: {model.optimal_num_frames()}")

    model.set_parameter(AICParameter.ENHANCEMENT_LEVEL, 0.8)

    vad = model.create_vad()
    vad.set_parameter(AICVadParameter.SENSITIVITY, 6.0)

    audio = np.zeros((1, 160), dtype=np.float32)
    model.process(audio)

    if vad.is_speech_detected():
        print("Speech detected")

    model.close()
    ```
  </Tab>

  <Tab title="2.0">
    ```python theme={null}
    import os
    import aic_sdk as aic
    import numpy as np

    license_key = os.environ["AIC_SDK_LICENSE"]

    model_path = aic.Model.download("quail-vf-l-16khz", "./models")
    model = aic.Model.from_file(model_path)

    config = aic.ProcessorConfig.optimal(model)
    processor = aic.Processor(model, license_key, config)

    proc_ctx = processor.get_processor_context()
    vad_ctx = processor.get_vad_context()

    latency_samples = proc_ctx.get_output_delay()
    print(f"Latency: {latency_samples / config.sample_rate * 1000:.2f}ms")
    print(f"Optimal frames: {config.num_frames}")

    proc_ctx.set_parameter(aic.ProcessorParameter.EnhancementLevel, 0.8)
    vad_ctx.set_parameter(aic.VadParameter.Sensitivity, 6.0)

    audio = np.zeros((1, config.num_frames), dtype=np.float32)
    processed = processor.process(audio)

    if vad_ctx.is_speech_detected():
        print("Speech detected")
    ```
  </Tab>
</Tabs>

## Async processing

<Tabs>
  <Tab title="1.3">
    ```python theme={null}
    # 1.3 - async methods on Model
    result = await model.process_async(audio)
    future = model.process_submit(audio)
    result = await model.process_interleaved_async(audio, channels)
    ```
  </Tab>

  <Tab title="2.0">
    ```python theme={null}
    # 2.0 - use ProcessorAsync class
    import aic_sdk as aic

    processor = aic.ProcessorAsync(model, license_key, config)
    result = await processor.process_async(audio)

    # For async model download
    model_path = await aic.Model.download_async("quail-vf-l-16khz", "./models")
    ```
  </Tab>
</Tabs>

| 1.3                                 | 2.0                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------- |
| `model.process_async(audio)`        | `ProcessorAsync.process_async(audio)`                                     |
| `model.process_submit(audio)`       | Use `asyncio` primitives directly                                         |
| `model.process_interleaved_async()` | Not available (use `process_async` with numpy array `(channels, frames)`) |

## Removed features

* `AICModelType` enum (use model ID strings such as `"quail-vf-l-16khz"`).
* `process_interleaved()` and `process_sequential()` (use `process` with numpy array `(channels, frames)`).
* Context manager `with Model(...) as m:`.
* `NOISE_GATE_ENABLE` parameter (now used automatically by the VAD).
* `process_submit()` future API (use `asyncio` with `ProcessorAsync`).

## New features

### Model downloading

```python theme={null}
import aic_sdk as aic

# Synchronous
model_path = aic.Model.download("sparrow-xxs-48khz", "./models")

# Asynchronous
model_path = await aic.Model.download_async("sparrow-xxs-48khz", "./models")
```

### Model reuse

```python theme={null}
import aic_sdk as aic

model = aic.Model.from_file(model_path)

processor1 = aic.Processor(model, license_key, config)
processor2 = aic.Processor(model, license_key, config)
```

### Configure the Processor

```python theme={null}
# Get optimal configuration for the model
config = aic.ProcessorConfig.optimal(model, num_channels=1, allow_variable_frames=False)
print(config)  # ProcessorConfig(sample_rate=48000, num_channels=1, num_frames=480, allow_variable_frames=False)

# Or create from scratch
config = aic.ProcessorConfig(
    sample_rate=48000,
    num_channels=2,
    num_frames=480,
    allow_variable_frames=False # up to num_frames
)

# Option 1: Create and initialize in one step
processor = aic.Processor(model, license_key, config)

# Option 2: Create first, then initialize separately
processor = aic.Processor(model, license_key)
processor.initialize(config)
```

### Model information

```python theme={null}
# Get model ID
model_id = model.get_id()

# Get optimal sample rate for the model
optimal_rate = model.get_optimal_sample_rate()

# Get optimal frame count for a specific sample rate
optimal_frames = model.get_optimal_num_frames(48000)
```

### Specific exception types

```python theme={null}
import aic_sdk as aic

try:
    processor = aic.Processor(model, license_key, config)
except aic.LicenseFormatInvalidError as e:
    print(f"Invalid license format: {e.message}")
except aic.LicenseExpiredError as e:
    print(f"License expired: {e.message}")
except aic.ModelInvalidError as e:
    print(f"Invalid model: {e.message}")
```

Check [type stubs file](https://github.com/ai-coustics/aic-sdk-py/blob/main/aic_sdk.pyi) for all error types and complete API.

## Need help?

* See the [GitHub Repository](https://github.com/ai-coustics/aic-sdk-py) and the [type stubs file](https://github.com/ai-coustics/aic-sdk-py/blob/main/aic_sdk.pyi).
* Browse available models at [artifacts.ai-coustics.io](https://artifacts.ai-coustics.io).
* Generate new license keys at [developers.ai-coustics.com](https://developers.ai-coustics.com).