use crate::codec::CodecParams;
use crate::db::space::{Lang, Metric, Space};
pub(crate) const DEFAULT_CALIBRATE_SAMPLE: usize = 50_000;
#[derive(Clone, Debug, Default)]
pub struct Schema {
pub(crate) fields: Vec<(String, FieldSpec)>,
}
impl Schema {
#[must_use]
pub fn new() -> Schema {
Schema { fields: Vec::new() }
}
#[must_use]
pub fn text(self, name: &str) -> Schema {
self.text_with(name, Text::english())
}
#[must_use]
pub fn text_with(mut self, name: &str, spec: Text) -> Schema {
self.fields.push((name.to_owned(), FieldSpec::from(spec)));
self
}
#[must_use]
pub fn vector(mut self, name: &str, spec: Vector) -> Schema {
self.fields.push((name.to_owned(), FieldSpec::from(spec)));
self
}
}
#[derive(Clone, Debug)]
pub struct FieldSpec {
pub(crate) kind: FieldSpecKind,
}
#[derive(Clone, Debug)]
pub(crate) enum FieldSpecKind {
Text(Text),
Vector(Vector),
}
impl From<Text> for FieldSpec {
fn from(spec: Text) -> Self {
FieldSpec {
kind: FieldSpecKind::Text(spec),
}
}
}
impl From<Vector> for FieldSpec {
fn from(spec: Vector) -> Self {
FieldSpec {
kind: FieldSpecKind::Vector(spec),
}
}
}
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct Text {
pub(crate) binding: TextBinding,
}
#[derive(Clone, Debug)]
pub(crate) enum TextBinding {
Inline { lang: Lang },
Shared(Space),
}
impl Text {
#[must_use]
pub fn english() -> Text {
Text {
binding: TextBinding::Inline {
lang: Lang::English,
},
}
}
#[must_use]
pub fn raw() -> Text {
Text {
binding: TextBinding::Inline { lang: Lang::Raw },
}
}
#[must_use]
pub fn space(s: &Space) -> Text {
Text {
binding: TextBinding::Shared(s.clone()),
}
}
}
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct Vector {
pub(crate) binding: VectorBinding,
pub(crate) shared_misuse: Option<&'static str>,
}
#[derive(Clone, Debug)]
pub(crate) enum VectorBinding {
Inline(VectorInline),
Shared(Space),
}
#[derive(Clone, Debug)]
pub(crate) struct VectorInline {
pub dim: u32,
pub metric: Metric,
pub codec: Codec,
pub calibrate: Calibrate,
}
impl Vector {
#[must_use]
pub fn dim(dim: u32) -> Vector {
Vector {
binding: VectorBinding::Inline(VectorInline {
dim,
metric: Metric::Cosine,
codec: Codec::default(),
calibrate: Calibrate::default(),
}),
shared_misuse: None,
}
}
#[must_use]
pub fn space(s: &Space) -> Vector {
Vector {
binding: VectorBinding::Shared(s.clone()),
shared_misuse: None,
}
}
#[must_use]
pub fn metric(mut self, m: Metric) -> Vector {
match &mut self.binding {
VectorBinding::Inline(i) => i.metric = m,
VectorBinding::Shared(_) => {
self.shared_misuse.get_or_insert("metric");
}
}
self
}
#[must_use]
pub fn codec(mut self, c: Codec) -> Vector {
match &mut self.binding {
VectorBinding::Inline(i) => i.codec = c,
VectorBinding::Shared(_) => {
self.shared_misuse.get_or_insert("codec");
}
}
self
}
#[must_use]
pub fn calibrate(mut self, c: Calibrate) -> Vector {
match &mut self.binding {
VectorBinding::Inline(i) => i.calibrate = c,
VectorBinding::Shared(_) => {
self.shared_misuse.get_or_insert("calibrate");
}
}
self
}
}
#[derive(Clone, Debug, PartialEq)]
pub struct Codec {
pub(crate) spec: CodecSpec,
}
#[derive(Clone, Debug, PartialEq)]
pub(crate) enum CodecSpec {
Qam { amp_bits: u8, phase_bits: u8 },
Upq { cells: u32, design: UpqDesign },
Prebuilt(CodecParams),
}
impl Codec {
#[must_use]
pub fn qam() -> Codec {
Codec {
spec: CodecSpec::Qam {
amp_bits: crate::codec::qam_lloyd_max::DEFAULT_AMP_BITS,
phase_bits: crate::codec::qam_lloyd_max::DEFAULT_PHASE_BITS,
},
}
}
#[must_use]
pub fn qam_bits(amp_bits: u8, phase_bits: u8) -> Codec {
Codec {
spec: CodecSpec::Qam {
amp_bits,
phase_bits,
},
}
}
#[must_use]
pub fn upq() -> Codec {
Codec::upq_with(crate::codec::upq::DEFAULT_UPQ_CELLS, UpqDesign::Empirical)
}
#[must_use]
pub fn upq_cells(cells: u32) -> Codec {
Codec::upq_with(cells, UpqDesign::Empirical)
}
#[must_use]
pub fn upq_with(cells: u32, design: UpqDesign) -> Codec {
Codec {
spec: CodecSpec::Upq { cells, design },
}
}
#[must_use]
pub fn from_params(params: CodecParams) -> Codec {
Codec {
spec: CodecSpec::Prebuilt(params),
}
}
}
impl Default for Codec {
fn default() -> Self {
Codec::qam()
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum UpqDesign {
Empirical,
Rayleigh,
}
impl UpqDesign {
pub(crate) fn to_engine(&self) -> crate::format::upq_params::UpqDesignSource {
match self {
UpqDesign::Empirical => crate::format::upq_params::UpqDesignSource::Empirical,
UpqDesign::Rayleigh => crate::format::upq_params::UpqDesignSource::Rayleigh,
}
}
}
#[derive(Clone, Debug)]
pub struct Calibrate {
pub(crate) mode: CalibrateMode,
}
#[derive(Clone, Debug)]
pub(crate) enum CalibrateMode {
Auto { sample: usize },
Now(Vec<Vec<f32>>),
}
impl Calibrate {
#[must_use]
pub fn auto() -> Calibrate {
Calibrate::auto_sample(DEFAULT_CALIBRATE_SAMPLE)
}
#[must_use]
pub fn auto_sample(sample: usize) -> Calibrate {
Calibrate {
mode: CalibrateMode::Auto { sample },
}
}
#[must_use]
pub fn now(sample: Vec<Vec<f32>>) -> Calibrate {
Calibrate {
mode: CalibrateMode::Now(sample),
}
}
}
impl Default for Calibrate {
fn default() -> Self {
Calibrate::auto()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn codec_constructors_and_default() {
assert_eq!(Codec::default(), Codec::qam());
assert_eq!(
Codec::qam().spec,
CodecSpec::Qam {
amp_bits: 5,
phase_bits: 6
}
);
assert_eq!(
Codec::qam_bits(8, 8).spec,
CodecSpec::Qam {
amp_bits: 8,
phase_bits: 8
}
);
assert_eq!(Codec::upq(), Codec::upq_with(2048, UpqDesign::Empirical));
assert_eq!(
Codec::upq_cells(512).spec,
CodecSpec::Upq {
cells: 512,
design: UpqDesign::Empirical
}
);
assert_eq!(
Codec::upq_with(1024, UpqDesign::Rayleigh).spec,
CodecSpec::Upq {
cells: 1024,
design: UpqDesign::Rayleigh
}
);
}
#[test]
fn calibrate_default_is_auto_50k() {
let c = Calibrate::default();
assert!(matches!(c.mode, CalibrateMode::Auto { sample: 50_000 }));
let c = Calibrate::auto_sample(8);
assert!(matches!(c.mode, CalibrateMode::Auto { sample: 8 }));
let c = Calibrate::now(vec![vec![0.0; 4]]);
assert!(matches!(c.mode, CalibrateMode::Now(ref s) if s.len() == 1));
}
#[test]
fn vector_records_shared_binding_misuse() {
let s = Space::vector("emb", 64);
let v = Vector::space(&s)
.codec(Codec::upq())
.calibrate(Calibrate::auto());
assert_eq!(v.shared_misuse, Some("codec"));
let v = Vector::space(&s).metric(Metric::Dot);
assert_eq!(v.shared_misuse, Some("metric"));
let v = Vector::dim(64).metric(Metric::Dot).codec(Codec::upq());
assert!(v.shared_misuse.is_none());
}
#[test]
fn schema_builder_collects_fields_in_order() {
let s = Space::vector("emb", 64);
let schema = Schema::new()
.text("body")
.vector("dense", Vector::dim(64))
.vector("shared", Vector::space(&s));
let names: Vec<&str> = schema.fields.iter().map(|(n, _)| n.as_str()).collect();
assert_eq!(names, ["body", "dense", "shared"]);
assert!(matches!(
schema.fields[0].1.kind,
FieldSpecKind::Text(Text {
binding: TextBinding::Inline {
lang: Lang::English
},
..
})
));
}
}