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 prelude;
84pub mod product_contracts;
85pub mod profile;
86pub mod provider_platform;
87pub mod providers;
88pub mod remote;
89pub mod runtime;
90pub mod sdk;
91pub mod secret;
92pub mod support;
93#[cfg(feature = "tts")]
94pub mod tts;
95pub mod window;
96
97pub use audio::{
98    load_audio, normalize_remote_audio, try_load_wav_file, AudioInput, BoundedAudioBody,
99    ChannelPolicy, EncodedAudioFormat, NormalizedAudio, RemoteAudioLimits, ALLOWED_SAMPLE_RATES_HZ,
100    DEFAULT_MAX_DURATION, DEFAULT_MAX_ENCODED_BYTES, DEFAULT_MAX_PCM_SAMPLES, WHISPER_SAMPLE_RATE,
101};
102pub use batch::{
103    acquire_batch_lock, build_items, discover_inputs, discovery_preflight_id, lock_path,
104    manifest_path, merge_for_resume, operation_fingerprint, prepare_resume, sha256_file_full,
105    truncate_error, validate_batch_stt_provider, verify_item_for_resume, work_indices, BatchItem,
106    BatchItemStatus, BatchLock, BatchLockGuard, BatchManifest, BatchSummary,
107    OperationFingerprintInput, ResumeDecision, AUDIO_EXTENSIONS, BATCH_LOCK_NAME,
108    BATCH_MANIFEST_NAME, BATCH_MANIFEST_VERSION, BATCH_MANIFEST_VERSION_V1, MAX_BATCH_ERROR_CHARS,
109};
110pub use cancel::CancelFlag;
111pub use capabilities::{
112    apply_stt_request_gates, lookup_openrouter_stt, preflight_cleanup, preflight_cleanup_for,
113    preflight_stt, preflight_stt_for, preflight_tts, preflight_tts_for, CapabilityOperation,
114    DescriptorFreshness, OpenRouterSttPath, OpenRouterSttRecord, ProviderCapabilities,
115    SttBackendClass, VoiceModel, CAPABILITY_SCHEMA_VERSION, OPENROUTER_STT_REGISTRY,
116};
117pub use cleanup::{
118    apply_cleanup, apply_cleanup_with_segments, apply_cleanup_with_segments_op, cleanup_text,
119    CleanupProviderKind, CleanupReport, CleanupResult, CleanupStyle, OpenRouterCleanup,
120    RulesCleanup, SegmentCleanupPolicy, TextCleanup,
121};
122pub use config::{Config, ConfigFile, EffectiveConfigDiagnostic, ValidatedConfig};
123pub use doctor::{run_doctor, DoctorCheck, DoctorReport, DoctorSeverity, DOCTOR_SCHEMA_VERSION};
124pub use domain::{FiniteDurationSecs, ModelId, SampleRateHz};
125pub use dto::{ErrorDto, SttResultDto, ERROR_SCHEMA_VERSION, STT_RESULT_SCHEMA_VERSION};
126pub use engine::AurumEngine;
127pub use error::{AurumError, ErrorCategory, Result, TranscriptionError};
128pub use eval::{
129    aggregate_listening, allowed_mean_wer, budget_exit_code, build_report, char_error_rate,
130    compare_perf_budget, compare_stt_budget, evaluate_support_tier, join_discontinuity_score,
131    observatory_core_budget_tiny, observatory_core_corpus, percentile_sorted,
132    perf_budget_exit_code, perf_scenario_catalogue, repetition_ratio, score_observatory_fixture,
133    score_stt, score_tts_pcm, silence_false_positive, smoke_corpus, tier_a_profile_templates,
134    tts_local_matrix, tts_production_pack, word_error_rate, AssetResolution, BudgetComparison,
135    BudgetFinding, BudgetSeverity, CorpusCoverage, EvalCorpus, EvalReport, HardwareTier,
136    ListeningAggregate, ListeningRating, ListeningReport, NamedHardwareProfile, ObservatoryCorpus,
137    ObservatoryFixture, ObservatoryFixtureScore, ObservatoryReport, ObservatoryScoreExtras,
138    PerfBudget, PerfComparison, PerfFinding, PerfReport, PerfScenario, PerfScenarioBudget,
139    PerfScenarioResult, PerfSeverity, RunIdentity, SttBudget, SttFixture, SttScore,
140    SupportTierDecision, TtsEvalFixture, TtsEvalPack, TtsEvalParticipation, TtsObjectiveReport,
141    TtsObjectiveScore, TtsObjectiveThresholds, TtsRunIdentity, NORMALIZATION_POLICY_VERSION,
142    OBSERVATORY_SCHEMA_VERSION, PERF_EVIDENCE_VERSION, PERF_SCHEMA_VERSION,
143    STT_OBSERVATORY_EVIDENCE_VERSION, TTS_EVAL_SCHEMA_VERSION, TTS_EVIDENCE_VERSION,
144};
145pub use model::{list_models, DownloadProgress, EnsureModelOptions, ModelInfo, ModelStatus};
146pub use observability::{
147    privacy_scan, process_metrics, BoundedEventSink, DiagnosticBundle, EventSink, Metrics,
148    MetricsScope, MetricsSnapshot, NoopEventSink, OpEvent, OpKind, OpStage, SpanTimer,
149    TerminalCategory, TerminalGuard, DEFAULT_EVENT_QUEUE_CAP, METRICS_SCHEMA_VERSION,
150    OP_EVENT_SCHEMA_VERSION, PRIVACY_CANARY_MARKERS,
151};
152pub use output::{
153    commit_text, format_result, write_result, write_result_to_path, CommitMode, OutputFormat,
154    OutputTransaction, SymlinkPolicy, DEFAULT_MAX_OUTPUT_BYTES,
155};
156pub use partial::{PartialSession, PartialSessionConfig, PartialUpdate};
157pub use pcm::PcmBuffer;
158pub use postprocess::{normalize_result_with_report, NormalizationReport};
159pub use product_contracts::{
160    registered_stt_provider_ids, registered_tts_provider_ids, ProductContractsSnapshot,
161    ProductProviderRecord, PRODUCT_CONTRACTS_SCHEMA_VERSION,
162};
163pub use profile::{
164    format_recommendation, resolve_profile, ProfileResolution, QualityProfile,
165    PROFILE_EVIDENCE_VERSION,
166};
167pub use provider_platform::{
168    capabilities_for, check_builtin_conformance, detect_catalogue_drift,
169    evaluate_supported_evidence_gate, list_provider_summaries, load_evidence_dir,
170    preflight_stt_with_registry, preflight_tts_with_registry, provider_list, CatalogueDriftReport,
171    EvidenceGateReport, EvidenceOperation, ProviderBuildContext, ProviderEvidenceIndex,
172    ProviderEvidenceRecord, ProviderId, ProviderList, ProviderRegistry, ProviderResolveOptions,
173    ProviderSummary, SupportTier, SupportedRouteClaim, PROVIDER_EVIDENCE_SCHEMA_VERSION,
174    PROVIDER_LIST_SCHEMA_VERSION, SUPPORTED_EVIDENCE_MAX_AGE_SECS,
175};
176pub use providers::local::{clear_context_cache, process_global_stt_pool, SttContextPool};
177#[cfg(feature = "tts")]
178pub use providers::{
179    default_tts_model_for_provider, default_tts_voice_for_provider, lookup_openrouter_tts,
180    resolve_tts_model, resolve_tts_voice, tts_model_known_for_provider, OpenRouterTtsProvider,
181    DEFAULT_OPENROUTER_TTS_MODEL, DEFAULT_OPENROUTER_TTS_VOICE, OPENROUTER_TTS_REGISTRY,
182};
183#[cfg(feature = "tts")]
184pub use providers::{
185    lookup_elevenlabs_tts, ElevenLabsTtsProvider, DEFAULT_ELEVENLABS_TTS_MODEL,
186    ELEVENLABS_TTS_REGISTRY, EXAMPLE_ELEVENLABS_VOICE_ID,
187};
188pub use providers::{
189    lookup_openai_stt, OpenAiSttProvider, DEFAULT_OPENAI_STT_MODEL, OPENAI_STT_REGISTRY,
190};
191#[cfg(feature = "tts")]
192pub use providers::{
193    lookup_openai_tts, OpenAiTtsProvider, DEFAULT_OPENAI_TTS_MODEL, DEFAULT_OPENAI_TTS_VOICE,
194    OPENAI_TTS_REGISTRY,
195};
196pub use providers::{lookup_xai_stt, XaiSttProvider, DEFAULT_XAI_STT_MODEL, XAI_STT_REGISTRY};
197#[cfg(feature = "tts")]
198pub use providers::{
199    lookup_xai_tts, XaiTtsProvider, DEFAULT_XAI_TTS_MODEL, DEFAULT_XAI_TTS_VOICE, XAI_TTS_REGISTRY,
200};
201pub use providers::{
202    LocalWhisperProvider, OpenRouterProvider, OpenRouterSttMode, Segment, TranscriptionOptions,
203    TranscriptionProvider, TranscriptionResult,
204};
205pub use remote::{
206    HardenedHttpClient, LongFormPolicy, OpenAiSpeechRequest, OpenRouterHttpPolicy,
207    ProviderHttpPolicy, RemotePolicy, SpeechResponseFormat, TimestampSource,
208    DEFAULT_REMOTE_STT_CHUNK_SECS,
209};
210pub use runtime::{
211    GovernorConfig, Lifecycle, LifecycleState, OpContext, PermitKind, ResourceGovernor,
212};
213pub use sdk::{
214    AurumConfig, CleanupConfig, OperationOptions, ProviderProfiles, RuntimeConfig, SttConfig,
215    TranscriptionRequest,
216};
217#[cfg(feature = "tts")]
218pub use sdk::{SynthesisRequest, TtsConfig};
219pub use secret::SecretString;
220pub use support::{
221    build_support_bundle, default_bundle_path, SupportBundle, SUPPORT_BUNDLE_VERSION,
222};
223pub use window::{PartialClock, PartialWindowPolicy};
224
225#[cfg(feature = "tts")]
226pub use tts::{
227    format_adapters as format_tts_adapters, format_custom_list as format_tts_custom_list,
228    format_inspect as format_tts_inspect, format_model_list as format_tts_model_list,
229    format_voice_list as format_tts_voice_list, inspect_pack as inspect_tts_pack,
230    list_adapters as list_tts_adapters, list_models as list_tts_models,
231    list_voices as list_tts_voices, process_global_tts_pool,
232    propose_add_local as propose_tts_add_local, resolve_voice_for_model,
233    run_kitten_catalogue_conformance, run_pack_conformance, verify_pack as verify_tts_pack,
234    write_add_manifest as write_tts_add_manifest, write_wav_i16_mono_atomic,
235    write_wav_i16_mono_transaction, BackendKind as TtsBackendKind, LocalTtsProvider,
236    SynthesisOptions, SynthesisProvider, SynthesisResult, TrustMode, TtsSessionPool,
237    DEFAULT_TTS_MODEL, DEFAULT_TTS_VOICE, KOKORO_DEFAULT_VOICE, KOKORO_TTS_MODEL,
238};
aurum_core/lib.rs

aurum_core/
lib.rs
