euhadra 0.3.0

A programmable voice input framework — ASR, LLM refinement, and OS integration as composable adapters
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

//! Router factory wrapping `CanaryAdapter`.
//!
//! Registered under runtime id `"canary"`. Menura supplies the model
//! bundle directory via `AdapterRequest.model_source.LocalPath`, the
//! BCP 47 language tag via `AdapterRequest.language` (one of
//! `en`/`de`/`fr`/`es`), and an optional `int8` toggle via
//! `AdapterRequest.options` to load the quantised weights instead of
//! the FP32 ones.

use async_trait::async_trait;
use serde::Deserialize;
use std::sync::Arc;

use crate::router::{AdapterRequest, AsrRuntimeFactory, ModelSource, RouterError};
use crate::traits::AsrAdapter;

use super::adapter::{CanaryAdapter, CanaryConfig};

/// Options accepted by `CanaryFactory` via `AdapterRequest.options`.
#[derive(Debug, Default, Deserialize)]
struct CanaryOptions {
    /// Load the INT8-quantised encoder/decoder pair instead of FP32.
    /// `None` keeps the `CanaryConfig::default()` filenames (FP32).
    #[serde(default)]
    int8: Option<bool>,
}

/// Router factory that builds `CanaryAdapter` via `AsrRouter`.
pub struct CanaryFactory;

impl CanaryFactory {
    pub const ID: &'static str = "canary";
}

#[async_trait]
impl AsrRuntimeFactory for CanaryFactory {
    fn id(&self) -> &'static str {
        Self::ID
    }

    async fn instantiate(&self, req: &AdapterRequest) -> Result<Arc<dyn AsrAdapter>, RouterError> {
        let ModelSource::LocalPath(model_dir) = &req.model_source;

        let opts: CanaryOptions = if req.options.is_null() {
            CanaryOptions::default()
        } else {
            serde_json::from_value(req.options.clone()).map_err(|e| {
                RouterError::InvalidRequest(format!("canary options parse error: {e}"))
            })?
        };

        let mut cfg = CanaryConfig::default();
        if opts.int8 == Some(true) {
            cfg = cfg.with_int8_weights();
        }

        let mut adapter = CanaryAdapter::load_with_config(model_dir, cfg).map_err(|e| {
            RouterError::InstantiationFailed {
                runtime: Self::ID.to_string(),
                message: e.to_string(),
            }
        })?;
        if !req.language.is_empty() {
            adapter = adapter.with_language(req.language.clone());
        }
        Ok(Arc::new(adapter))
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::router::{AdapterRequest, AsrRouter, ModelSource, RouterError};
    use serde_json::json;
    use std::path::PathBuf;

    fn req(language: &str, options: serde_json::Value) -> AdapterRequest {
        AdapterRequest {
            language: language.into(),
            runtime: CanaryFactory::ID.into(),
            model_source: ModelSource::LocalPath(PathBuf::from("/nonexistent/canary/bundle")),
            options,
        }
    }

    #[tokio::test]
    async fn factory_id_matches_constant() {
        assert_eq!(CanaryFactory.id(), "canary");
    }

    #[tokio::test]
    async fn dispatch_with_missing_bundle_returns_instantiation_failed() {
        let router = AsrRouter::new().register(CanaryFactory);
        match router.dispatch(req("en", serde_json::Value::Null)).await {
            Err(RouterError::InstantiationFailed { runtime, .. }) => {
                assert_eq!(runtime, "canary");
            }
            Err(other) => panic!("expected InstantiationFailed, got {other:?}"),
            Ok(_) => panic!("expected error when bundle dir does not exist"),
        }
    }

    #[tokio::test]
    async fn int8_option_is_accepted() {
        let router = AsrRouter::new().register(CanaryFactory);
        match router.dispatch(req("es", json!({ "int8": true }))).await {
            Err(RouterError::InstantiationFailed { .. }) => {}
            Err(other) => panic!("expected InstantiationFailed, got {other:?}"),
            Ok(_) => panic!("expected loader error"),
        }
    }

    #[tokio::test]
    async fn malformed_options_return_invalid_request() {
        let router = AsrRouter::new().register(CanaryFactory);
        match router.dispatch(req("en", json!({ "int8": "yes" }))).await {
            Err(RouterError::InvalidRequest(msg)) => {
                assert!(msg.contains("canary"));
            }
            Err(other) => panic!("expected InvalidRequest, got {other:?}"),
            Ok(_) => panic!("expected error for malformed options"),
        }
    }
}