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

//! Router factory wrapping `ParaformerAdapter`.
//!
//! Registered under runtime id `"paraformer"`. Menura supplies the
//! model bundle directory via `AdapterRequest.model_source.LocalPath`.
//! Paraformer-large is a Chinese-only checkpoint, so the request's
//! language is ignored at the adapter layer; Menura should still route
//! per-language correctly via `asr_models.toml`.

use async_trait::async_trait;
use std::sync::Arc;

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

use super::adapter::ParaformerAdapter;

/// Router factory that builds `ParaformerAdapter` via `AsrRouter`.
pub struct ParaformerFactory;

impl ParaformerFactory {
    pub const ID: &'static str = "paraformer";
}

#[async_trait]
impl AsrRuntimeFactory for ParaformerFactory {
    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;

        // Reject non-empty options for now — there are no toggles
        // exposed today. A future `model_filename` override (e.g. for
        // the 8358 hot-word variant) can add fields here without
        // breaking existing callers.
        if !req.options.is_null()
            && !matches!(&req.options, serde_json::Value::Object(o) if o.is_empty())
        {
            return Err(RouterError::InvalidRequest(format!(
                "paraformer accepts no options today; got: {}",
                req.options
            )));
        }

        let adapter =
            ParaformerAdapter::load(model_dir).map_err(|e| RouterError::InstantiationFailed {
                runtime: Self::ID.to_string(),
                message: e.to_string(),
            })?;
        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(options: serde_json::Value) -> AdapterRequest {
        AdapterRequest {
            language: "zh".into(),
            runtime: ParaformerFactory::ID.into(),
            model_source: ModelSource::LocalPath(PathBuf::from("/nonexistent/paraformer/bundle")),
            options,
        }
    }

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

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

    #[tokio::test]
    async fn empty_object_options_are_accepted() {
        let router = AsrRouter::new().register(ParaformerFactory);
        // {} should pass the options check and reach the loader.
        match router.dispatch(req(json!({}))).await {
            Err(RouterError::InstantiationFailed { .. }) => {}
            Err(other) => panic!("expected InstantiationFailed, got {other:?}"),
            Ok(_) => panic!("expected loader error"),
        }
    }

    #[tokio::test]
    async fn unknown_options_return_invalid_request() {
        let router = AsrRouter::new().register(ParaformerFactory);
        match router.dispatch(req(json!({ "vocab_size": 8358 }))).await {
            Err(RouterError::InvalidRequest(msg)) => {
                assert!(msg.contains("paraformer"));
            }
            Err(other) => panic!("expected InvalidRequest, got {other:?}"),
            Ok(_) => panic!("expected error for unknown options"),
        }
    }
}