ferrin_spec/
lib.rs

1//! Ferrin provider specification.
2//!
3//! This crate defines the contract between the Ferrin core and provider
4//! adapters: model traits, prompt and content types, stream parts, shared
5//! option and metadata types, and the provider-level error type. It contains no
6//! networking and no generation logic.
7//!
8//! # Layout
9//!
10//! - [`shared`]: identifiers, provider options and metadata, warnings, headers,
11//!   media types, file data.
12//! - [`language_model`]: the [`LanguageModel`] trait and everything it exchanges
13//!   with the core (call options, prompt, tools, content, stream parts, results).
14//! - One module per additional model kind ([`embedding_model`], [`image_model`],
15//!   [`speech_model`], [`transcription_model`], [`reranking_model`],
16//!   [`video_model`], [`speech_translation_model`], [`realtime_model`]) and per
17//!   provider service ([`files`], [`skills`], [`batch`]).
18//! - [`provider`]: the [`Provider`] trait that hands out models by id.
19//! - [`dynamic`]: object-safe `Dyn*` traits, boxed future/stream aliases and
20//!   the cloneable `*Ref` handle types.
21//! - [`error`]: [`ProviderError`] and its concrete error structs.
22//!
23//! # Serialization
24//!
25//! Every wire type derives `serde` with internally tagged enums (`type` or
26//! `role`, kebab-case), snake_case fields, base64 for bytes and RFC 3339 for
27//! timestamps. Optional fields are omitted when absent. `serde_json` is used
28//! with `preserve_order`, so object key order is stable.
29//!
30//! Design: `docs/01-architecture/03-core-data-model.md` and
31//! `docs/01-architecture/04-provider-spec.md`.
32//!
33//! # Attribution
34//!
35//! Portions of this crate are derived from the Vercel AI SDK (Apache-2.0,
36//! Copyright 2023 Vercel, Inc.), translated from TypeScript to Rust and
37//! modified. See the `NOTICE` file in the crate root.
38
39pub mod batch;
40pub mod dynamic;
41pub mod embedding_model;
42pub mod error;
43pub mod files;
44pub mod image_model;
45pub mod json;
46pub mod language_model;
47pub mod provider;
48pub mod realtime_model;
49pub mod reranking_model;
50pub mod shared;
51pub mod skills;
52pub mod speech_model;
53pub mod speech_translation_model;
54pub mod transcription_model;
55pub mod video_model;
56
57pub use batch::Batch;
58pub use dynamic::BatchRef;
59pub use dynamic::BoxFuture;
60pub use dynamic::BoxStream;
61pub use dynamic::DynBatch;
62pub use dynamic::DynEmbeddingModel;
63pub use dynamic::DynFiles;
64pub use dynamic::DynImageModel;
65pub use dynamic::DynLanguageModel;
66pub use dynamic::DynRealtimeFactory;
67pub use dynamic::DynRealtimeModel;
68pub use dynamic::DynRerankingModel;
69pub use dynamic::DynSkills;
70pub use dynamic::DynSpeechModel;
71pub use dynamic::DynSpeechTranslationModel;
72pub use dynamic::DynTranscriptionModel;
73pub use dynamic::DynVideoModel;
74pub use dynamic::EmbeddingModelRef;
75pub use dynamic::FilesRef;
76pub use dynamic::ImageModelRef;
77pub use dynamic::LanguageModelRef;
78pub use dynamic::ModelRef;
79pub use dynamic::RealtimeFactoryRef;
80pub use dynamic::RealtimeModelRef;
81pub use dynamic::RerankingModelRef;
82pub use dynamic::ServiceRef;
83pub use dynamic::SkillsRef;
84pub use dynamic::SpeechModelRef;
85pub use dynamic::SpeechTranslationModelRef;
86pub use dynamic::TranscriptionModelRef;
87pub use dynamic::VideoModelRef;
88pub use embedding_model::EmbeddingModel;
89pub use error::ApiCallError;
90pub use error::ModelKind;
91pub use error::NoSuchModelError;
92pub use error::ProviderError;
93pub use error::UnsupportedFunctionalityError;
94pub use files::Files;
95pub use image_model::AspectRatio;
96pub use image_model::ImageModel;
97pub use image_model::ImageSize;
98pub use json::JsonObject;
99pub use json::JsonValue;
100pub use language_model::CallOptions;
101pub use language_model::Content;
102pub use language_model::CustomKind;
103pub use language_model::FinishReason;
104pub use language_model::FinishReasonKind;
105pub use language_model::GenerateResult;
106pub use language_model::LanguageModel;
107pub use language_model::Prompt;
108pub use language_model::PromptMessage;
109pub use language_model::ReasoningEffort;
110pub use language_model::RequestMetadata;
111pub use language_model::ResponseFormat;
112pub use language_model::ResponseMetadata;
113pub use language_model::StreamError;
114pub use language_model::StreamPart;
115pub use language_model::StreamResult;
116pub use language_model::SupportedUrls;
117pub use language_model::ToolCall;
118pub use language_model::ToolChoice;
119pub use language_model::ToolDefinition;
120pub use language_model::Usage;
121pub use provider::Provider;
122pub use provider::ProviderRef;
123pub use realtime_model::RealtimeFactory;
124pub use realtime_model::RealtimeModel;
125pub use reranking_model::RerankingModel;
126pub use shared::ApprovalId;
127pub use shared::AudioFormat;
128pub use shared::BatchId;
129pub use shared::FileData;
130pub use shared::Headers;
131pub use shared::InvalidHeader;
132pub use shared::MediaType;
133pub use shared::ModelId;
134pub use shared::PartId;
135pub use shared::ProviderId;
136pub use shared::ProviderMetadata;
137pub use shared::ProviderOptions;
138pub use shared::ProviderReference;
139pub use shared::ToolCallId;
140pub use shared::ToolName;
141pub use shared::Warning;
142pub use skills::Skills;
143pub use speech_model::SpeechModel;
144pub use speech_translation_model::SpeechTranslationModel;
145pub use transcription_model::TranscriptionModel;
146pub use video_model::VideoModel;
147
148/// Version of the provider specification implemented by this crate.
149///
150/// The specification version equals the crate version (ADR 0011). Adapters
151/// compiled against a different `ferrin-spec` version fail to link rather than
152/// negotiating at runtime.
153pub const SPEC_VERSION: &str = env!("CARGO_PKG_VERSION");
ferrin_spec/lib.rs

ferrin_spec/
lib.rs
