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

aurum_core/
lib.rs
