ferrin_spec/
provider.rs

1//! Provider trait: the entry point that hands out models and services.
2
3use std::sync::Arc;
4
5use crate::dynamic::BatchRef;
6use crate::dynamic::EmbeddingModelRef;
7use crate::dynamic::FilesRef;
8use crate::dynamic::ImageModelRef;
9use crate::dynamic::LanguageModelRef;
10use crate::dynamic::RealtimeFactoryRef;
11use crate::dynamic::RerankingModelRef;
12use crate::dynamic::SkillsRef;
13use crate::dynamic::SpeechModelRef;
14use crate::dynamic::SpeechTranslationModelRef;
15use crate::dynamic::TranscriptionModelRef;
16use crate::dynamic::VideoModelRef;
17use crate::error::ModelKind;
18use crate::error::NoSuchModelError;
19use crate::shared::ProviderId;
20
21/// A provider: creates model instances by id and exposes provider services.
22///
23/// Implement `language_model`, `embedding_model` and `image_model`; return
24/// [`NoSuchModelError::unsupported_kind`] for kinds the provider does not
25/// offer. The remaining lookups default to that error, and the service
26/// accessors default to `None`.
27pub trait Provider: Send + Sync + 'static {
28    /// Provider identifier, for example `openai`.
29    fn provider_id(&self) -> &ProviderId;
30
31    /// Returns the language model with `model_id`.
32    ///
33    /// # Errors
34    ///
35    /// Returns [`NoSuchModelError`] when the model is unknown.
36    fn language_model(&self, model_id: &str) -> Result<LanguageModelRef, NoSuchModelError>;
37
38    /// Returns the embedding model with `model_id`.
39    ///
40    /// # Errors
41    ///
42    /// Returns [`NoSuchModelError`] when the model is unknown.
43    fn embedding_model(&self, model_id: &str) -> Result<EmbeddingModelRef, NoSuchModelError>;
44
45    /// Returns the image model with `model_id`.
46    ///
47    /// # Errors
48    ///
49    /// Returns [`NoSuchModelError`] when the model is unknown.
50    fn image_model(&self, model_id: &str) -> Result<ImageModelRef, NoSuchModelError>;
51
52    /// Returns the transcription model with `model_id`.
53    ///
54    /// # Errors
55    ///
56    /// Returns [`NoSuchModelError`] when the model is unknown or the provider
57    /// has no transcription models.
58    fn transcription_model(
59        &self,
60        model_id: &str,
61    ) -> Result<TranscriptionModelRef, NoSuchModelError> {
62        Err(NoSuchModelError::unsupported_kind(
63            self.provider_id(),
64            model_id,
65            ModelKind::Transcription,
66        ))
67    }
68
69    /// Returns the speech model with `model_id`.
70    ///
71    /// # Errors
72    ///
73    /// Returns [`NoSuchModelError`] when the model is unknown or the provider
74    /// has no speech models.
75    fn speech_model(&self, model_id: &str) -> Result<SpeechModelRef, NoSuchModelError> {
76        Err(NoSuchModelError::unsupported_kind(
77            self.provider_id(),
78            model_id,
79            ModelKind::Speech,
80        ))
81    }
82
83    /// Returns the reranking model with `model_id`.
84    ///
85    /// # Errors
86    ///
87    /// Returns [`NoSuchModelError`] when the model is unknown or the provider
88    /// has no reranking models.
89    fn reranking_model(&self, model_id: &str) -> Result<RerankingModelRef, NoSuchModelError> {
90        Err(NoSuchModelError::unsupported_kind(
91            self.provider_id(),
92            model_id,
93            ModelKind::Reranking,
94        ))
95    }
96
97    /// Returns the video model with `model_id`.
98    ///
99    /// # Errors
100    ///
101    /// Returns [`NoSuchModelError`] when the model is unknown or the provider
102    /// has no video models.
103    fn video_model(&self, model_id: &str) -> Result<VideoModelRef, NoSuchModelError> {
104        Err(NoSuchModelError::unsupported_kind(
105            self.provider_id(),
106            model_id,
107            ModelKind::Video,
108        ))
109    }
110
111    /// Returns the speech translation model with `model_id`.
112    ///
113    /// # Errors
114    ///
115    /// Returns [`NoSuchModelError`] when the model is unknown or the provider
116    /// has no speech translation models.
117    fn speech_translation_model(
118        &self,
119        model_id: &str,
120    ) -> Result<SpeechTranslationModelRef, NoSuchModelError> {
121        Err(NoSuchModelError::unsupported_kind(
122            self.provider_id(),
123            model_id,
124            ModelKind::SpeechTranslation,
125        ))
126    }
127
128    /// Returns the realtime factory, if the provider supports realtime sessions.
129    fn realtime(&self) -> Option<RealtimeFactoryRef> {
130        None
131    }
132
133    /// Returns the files service, if the provider supports file storage.
134    fn files(&self) -> Option<FilesRef> {
135        None
136    }
137
138    /// Returns the skills service, if the provider supports skills.
139    fn skills(&self) -> Option<SkillsRef> {
140        None
141    }
142
143    /// Returns the batch service, if the provider supports batch jobs.
144    fn batch(&self) -> Option<BatchRef> {
145        None
146    }
147}
148
149/// Shared reference to a provider.
150pub type ProviderRef = Arc<dyn Provider>;
ferrin_spec/provider.rs

ferrin_spec/
provider.rs
