aurum_core/
lib.rs

1//! # aurum-core
2//!
3//! Reusable **on-device speech I/O** library (experimental API).
4//!
5//! - **STT** — local whisper.cpp by default; optional OpenRouter
6//! - **TTS** — local ONNX KittenTTS (cargo feature `tts`, default on)
7//! - **Cleanup** — rules or optional LLM post-edit
8//!
9//! Tagline: *Speech both ways. On-device by default.*
10//!
11//! The API may change without notice until a deliberate major version.
12//!
13//! ## STT example (provider path)
14//!
15//! ```rust,no_run
16//! use aurum_core::audio::{AudioInput, WHISPER_SAMPLE_RATE};
17//! use aurum_core::pcm::PcmBuffer;
18//! use aurum_core::providers::{LocalWhisperProvider, TranscriptionOptions};
19//! use std::path::PathBuf;
20//!
21//! # async fn demo() -> aurum_core::error::Result<()> {
22//! let provider = LocalWhisperProvider::new(PathBuf::from("/tmp/aurum-cache"))
23//!     .with_progress(false)
24//!     .with_local_only(false);
25//! provider.preload("tiny-q5_1").await?;
26//!
27//! let mut buf = PcmBuffer::dictation();
28//! buf.push(&[0.0f32; 1600])?;
29//! let result = provider
30//!     .transcribe_pcm(
31//!         buf.samples().as_slice(),
32//!         &TranscriptionOptions {
33//!             model: "tiny-q5_1".into(),
34//!             language: "en".into(),
35//!             timestamps: false,
36//!             cancel: None,
37//!         },
38//!     )
39//!     .await?;
40//! let _ = AudioInput::from_pcm_slice(buf.samples().as_slice(), WHISPER_SAMPLE_RATE)?;
41//! println!("{}", result.text());
42//! aurum_core::providers::local::clear_context_cache();
43//! # Ok(())
44//! # }
45//! ```
46//!
47//! ## Engine path (preferred for library hosts)
48//!
49//! ```rust,no_run
50//! use aurum_core::AurumEngine;
51//!
52//! # fn demo() -> aurum_core::error::Result<()> {
53//! let engine = AurumEngine::load()?;
54//! let _ = engine.doctor();
55//! let _ = engine.support_bundle(None);
56//! // engine.transcribe_pcm(&samples, &opts).await?; // STT on engine pools
57//! engine.shutdown(); // closes + clears idle models in *this* engine only
58//! # Ok(())
59//! # }
60//! ```
61
62pub mod audio;
63pub mod batch;
64pub mod bench;
65pub mod cache;
66pub mod cancel;
67pub mod capabilities;
68pub mod cleanup;
69pub mod config;
70pub mod doctor;
71pub mod domain;
72pub mod download;
73pub mod dto;
74pub mod engine;
75pub mod error;
76pub mod eval;
77pub mod model;
78pub mod observability;
79pub mod output;
80pub mod partial;
81pub mod pcm;
82pub mod postprocess;
83pub mod profile;
84pub mod provider_platform;
85pub mod providers;
86pub mod remote;
87pub mod runtime;
88pub mod secret;
89pub mod support;
90#[cfg(feature = "tts")]
91pub mod tts;
92pub mod window;
93
94pub use audio::{
95    load_audio, normalize_remote_audio, try_load_wav_file, AudioInput, BoundedAudioBody,
96    ChannelPolicy, EncodedAudioFormat, NormalizedAudio, RemoteAudioLimits, ALLOWED_SAMPLE_RATES_HZ,
97    DEFAULT_MAX_DURATION, DEFAULT_MAX_ENCODED_BYTES, DEFAULT_MAX_PCM_SAMPLES, WHISPER_SAMPLE_RATE,
98};
99pub use batch::{
100    build_items, discover_inputs, fingerprint_file, manifest_path, merge_for_resume, work_indices,
101    BatchItem, BatchItemStatus, BatchManifest, BatchSummary, AUDIO_EXTENSIONS, BATCH_MANIFEST_NAME,
102    BATCH_MANIFEST_VERSION,
103};
104pub use cancel::CancelFlag;
105pub use capabilities::{
106    apply_stt_request_gates, lookup_openrouter_stt, preflight_cleanup, preflight_cleanup_for,
107    preflight_stt, preflight_stt_for, preflight_tts, preflight_tts_for, CapabilityOperation,
108    DescriptorFreshness, OpenRouterSttPath, OpenRouterSttRecord, ProviderCapabilities,
109    SttBackendClass, VoiceModel, CAPABILITY_SCHEMA_VERSION, OPENROUTER_STT_REGISTRY,
110};
111pub use cleanup::{
112    apply_cleanup, apply_cleanup_with_segments, apply_cleanup_with_segments_op, cleanup_text,
113    CleanupProviderKind, CleanupReport, CleanupResult, CleanupStyle, OpenRouterCleanup,
114    RulesCleanup, SegmentCleanupPolicy, TextCleanup,
115};
116pub use config::{Config, EffectiveConfigDiagnostic, RawConfig, ValidatedConfig};
117pub use doctor::{run_doctor, DoctorCheck, DoctorReport, DoctorSeverity, DOCTOR_SCHEMA_VERSION};
118pub use domain::{FiniteDurationSecs, ModelId, SampleRateHz};
119pub use dto::{ErrorDto, SttResultDto, ERROR_SCHEMA_VERSION, STT_RESULT_SCHEMA_VERSION};
120pub use engine::AurumEngine;
121pub use error::{AurumError, ErrorCategory, Result, TranscriptionError};
122pub use eval::{
123    build_report, char_error_rate, repetition_ratio, score_stt, silence_false_positive,
124    smoke_corpus, word_error_rate, EvalCorpus, EvalReport, SttFixture, SttScore,
125};
126pub use model::{list_models, DownloadProgress, EnsureModelOptions, ModelInfo, ModelStatus};
127pub use observability::{
128    process_metrics, DiagnosticBundle, Metrics, MetricsSnapshot, SpanTimer, METRICS_SCHEMA_VERSION,
129};
130pub use output::{
131    commit_text, format_result, write_result, write_result_to_path, CommitMode, OutputFormat,
132    OutputTransaction, SymlinkPolicy, DEFAULT_MAX_OUTPUT_BYTES,
133};
134pub use partial::{PartialSession, PartialSessionConfig, PartialUpdate};
135pub use pcm::PcmBuffer;
136pub use postprocess::{normalize_result_with_report, NormalizationReport};
137pub use profile::{
138    format_recommendation, resolve_profile, ProfileResolution, QualityProfile,
139    PROFILE_EVIDENCE_VERSION,
140};
141pub use provider_platform::{
142    capabilities_for, check_builtin_conformance, list_provider_summaries,
143    preflight_stt_with_registry, preflight_tts_with_registry, provider_list, ProviderBuildContext,
144    ProviderId, ProviderList, ProviderRegistry, ProviderResolveOptions, ProviderSummary,
145    PROVIDER_LIST_SCHEMA_VERSION,
146};
147pub use providers::local::{clear_context_cache, process_global_stt_pool, SttContextPool};
148#[cfg(feature = "tts")]
149pub use providers::{
150    default_tts_model_for_provider, default_tts_voice_for_provider, lookup_openrouter_tts,
151    resolve_tts_model, resolve_tts_voice, tts_model_known_for_provider, OpenRouterTtsProvider,
152    DEFAULT_OPENROUTER_TTS_MODEL, DEFAULT_OPENROUTER_TTS_VOICE, OPENROUTER_TTS_REGISTRY,
153};
154#[cfg(feature = "tts")]
155pub use providers::{
156    lookup_elevenlabs_tts, ElevenLabsTtsProvider, DEFAULT_ELEVENLABS_TTS_MODEL,
157    ELEVENLABS_TTS_REGISTRY, EXAMPLE_ELEVENLABS_VOICE_ID,
158};
159pub use providers::{
160    lookup_openai_stt, OpenAiSttProvider, DEFAULT_OPENAI_STT_MODEL, OPENAI_STT_REGISTRY,
161};
162#[cfg(feature = "tts")]
163pub use providers::{
164    lookup_openai_tts, OpenAiTtsProvider, DEFAULT_OPENAI_TTS_MODEL, DEFAULT_OPENAI_TTS_VOICE,
165    OPENAI_TTS_REGISTRY,
166};
167pub use providers::{lookup_xai_stt, XaiSttProvider, DEFAULT_XAI_STT_MODEL, XAI_STT_REGISTRY};
168#[cfg(feature = "tts")]
169pub use providers::{
170    lookup_xai_tts, XaiTtsProvider, DEFAULT_XAI_TTS_MODEL, DEFAULT_XAI_TTS_VOICE, XAI_TTS_REGISTRY,
171};
172pub use providers::{
173    LocalWhisperProvider, OpenRouterProvider, OpenRouterSttMode, Segment, TranscriptionOptions,
174    TranscriptionProvider, TranscriptionResult,
175};
176pub use remote::{
177    HardenedHttpClient, OpenAiSpeechRequest, OpenRouterHttpPolicy, ProviderHttpPolicy,
178    RemotePolicy, SpeechResponseFormat,
179};
180pub use runtime::{
181    GovernorConfig, Lifecycle, LifecycleState, OpContext, PermitKind, ResourceGovernor,
182};
183pub use secret::SecretString;
184pub use support::{
185    build_support_bundle, default_bundle_path, SupportBundle, SUPPORT_BUNDLE_VERSION,
186};
187pub use window::{PartialClock, PartialWindowPolicy};
188
189#[cfg(feature = "tts")]
190pub use tts::{
191    format_adapters as format_tts_adapters, format_custom_list as format_tts_custom_list,
192    format_inspect as format_tts_inspect, format_model_list as format_tts_model_list,
193    format_voice_list as format_tts_voice_list, inspect_pack as inspect_tts_pack,
194    list_adapters as list_tts_adapters, list_models as list_tts_models,
195    list_voices as list_tts_voices, process_global_tts_pool,
196    propose_add_local as propose_tts_add_local, resolve_voice_for_model,
197    run_kitten_catalogue_conformance, run_pack_conformance, verify_pack as verify_tts_pack,
198    write_add_manifest as write_tts_add_manifest, write_wav_i16_mono_atomic,
199    write_wav_i16_mono_transaction, BackendKind as TtsBackendKind, LocalTtsProvider,
200    SynthesisOptions, SynthesisProvider, SynthesisResult, TrustMode, TtsSessionPool,
201    DEFAULT_TTS_MODEL, DEFAULT_TTS_VOICE, KOKORO_DEFAULT_VOICE, KOKORO_TTS_MODEL,
202};
aurum_core/lib.rs

aurum_core/
lib.rs
