ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! THE BY-EXAMPLE SET DOOR — `retrieve_similar_by_<field>_with`, the fourth door a
//! `list(embedding)` election gets, and the one the β4 spec's §6 measurement found missing.
//!
//! Beside [`similar`](super::similar) rather than inside it, on that file's own precedent: one file
//! per thing being proved. The single-vector by-example door stays there.
//!
//! # It is asserted as a POSITION as much as a shape
//!
//! The door is the crossing of two families that already existed — the by-example recipe and the
//! set fold — and the way a crossing goes wrong is by quietly becoming a third pipeline. So the
//! claims below are about which existing citizens the body reaches (`get_vectors`, `knn`,
//! `owner_best_excluding`, `set_scored`) and about which it must NOT: the plain `owner_best`, whose
//! use would let the example contribute to its own neighbours' sightings and answer a different
//! ranking under this name.

use super::{
  IndexModel,
  tests::{embedding_index, two_elections},
};
use crate::index::ElectionLabel;

/// The emission's tokens as text — the gate-blind reading, the doors living inside the observation
/// gate pair.
fn emitted(model: &IndexModel) -> String {
  model.emit().to_string()
}

/// The same model with its election relabelled a SET — the one word this whole door hangs off.
fn as_set(mut model: IndexModel) -> IndexModel {
  for elected in &mut model.embeddings {
    elected.label = ElectionLabel::List;
    elected.ty = syn::parse_quote!(::std::vec::Vec<::ingraph::Embedding<f32, 4, Clip>>);
  }
  model
}

/// One door's own tokens, cut at the next item.
fn door<'a>(emission: &'a str, name: &str) -> &'a str {
  let at = emission
    .split(&format!("async fn {name} <"))
    .nth(1)
    .unwrap_or_else(|| panic!("`{name}` is emitted: {emission}"));
  let end = [at.find("# [doc"), at.find("async fn")]
    .into_iter()
    .flatten()
    .min()
    .unwrap_or(at.len());
  &at[..end]
}

/// **THE DOOR RIDES THE LABEL**, exactly as its `retrieve_keys_*` sibling does — so a single
/// election has no by-example set door at all, which is a TRUE ABSENCE rather than a door standing
/// behind a bound nobody can satisfy.
#[test]
fn only_a_set_election_gets_the_by_example_set_door() {
  let single = emitted(&embedding_index());
  assert!(
    !single.contains("retrieve_similar_by_image_embedding_with"),
    "a single election grew the set door: {single}",
  );
  assert!(
    single.contains("retrieve_similar_by_image_embedding"),
    "the single-vector by-example door is gone: {single}",
  );

  let set = emitted(&as_set(embedding_index()));
  assert!(
    set.contains("retrieve_similar_by_image_embedding_with"),
    "a set election has no by-example set door: {set}",
  );
}

/// **ONE DOOR PER ELECTION**, counted at two per name because the retrieve face is written once per
/// half of the observation gate.
#[test]
fn every_set_election_gets_its_own_by_example_set_door() {
  let emission = emitted(&as_set(two_elections()));
  for field in ["caption_embedding", "image_embedding"] {
    assert_eq!(
      emission
        .matches(&format!("async fn retrieve_similar_by_{field}_with <"))
        .count(),
      2,
      "`retrieve_similar_by_{field}_with` is not written once per gate half: {emission}",
    );
  }
}

/// **THE BODY IS THE BY-EXAMPLE RECIPE ASKED WITH `m` VECTORS** — fetch own set, query with each,
/// exclude self per stream, fold.
///
/// The FETCH is the group read, `get_<field>`, which on a set election answers the whole set. It
/// used to be the seam call written out a second time here, and that second copy is what the group
/// read removed: the emptiness and the width now have ONE authority.
#[test]
fn the_body_is_the_recipe_at_the_set_grain() {
  let emission = emitted(&as_set(embedding_index()));
  let body = door(&emission, "retrieve_similar_by_image_embedding_with");
  for call in [
    // fetch own set, THROUGH the group read
    "get_image_embedding",
    // query with each of them, through the SAME knn every other door calls
    "knn",
    // the same address read
    "vector_keyed",
    // exclude self, per stream
    "owner_best_excluding",
    // and fold what came back
    "set_scored",
  ] {
    assert!(
      body.contains(call),
      "the recipe is missing `{call}`: {body}"
    );
  }
  assert!(
    !body.contains("get_vectors"),
    "the seam call is written a second time beside the door that owns it: {body}",
  );
}

/// **THE EXCLUSION IS PER STREAM, AND THE PLAIN COLLAPSE IS WHAT THE DOOR MUST NOT REACH.**
///
/// The mutation this exists for is the tempting one: collapse with `owner_best` and drop the
/// example out of the fused answer afterwards. That answers the same entities with different
/// scores — the example's own sightings would have entered every neighbour's fold — and no other
/// assertion in this crate would notice.
#[test]
fn the_door_never_reaches_the_plain_collapse() {
  let emission = emitted(&as_set(embedding_index()));
  let body = door(&emission, "retrieve_similar_by_image_embedding_with");
  assert!(
    !body.contains("owner_best ::"),
    "the door collapses without the seed: {body}",
  );
  assert!(
    !body.contains("retain"),
    "the door filters instead of seeding the membership: {body}",
  );
}

/// **IT JUDGES WIDTH AND NOT ARITY**, and it judges NEITHER here: both now live in the group read
/// this door takes its example from, which is the deduplication the split bought.
///
/// The claim is therefore read in two places. HERE: no judgment of any kind, and in particular no
/// `Several` — a `list(embedding)` election holding several vectors is the ordinary case and the
/// whole point of the door. THERE: the group read still says `Unindexed` and `Width`, and still
/// says no `Several`, so nothing was dropped on the way through.
#[test]
fn the_set_read_judges_what_a_set_can_be_judged_on() {
  let emission = emitted(&as_set(embedding_index()));
  let body = door(&emission, "retrieve_similar_by_image_embedding_with");
  assert!(
    !body.contains("Several"),
    "a set of several is what this door is FOR: {body}",
  );

  let group = door(&emission, "get_image_embedding");
  assert!(group.contains("Unindexed"), "{group}");
  assert!(group.contains("Width"), "{group}");
  assert!(
    !group.contains("Several"),
    "the group read judged an arity its election declared: {group}",
  );
}

/// **THE GROUP READ ANSWERS THE GROUP**, and a unit election's answers one — the split decided by
/// the election's LABEL at emission, with nothing at run time asking which.
#[test]
fn the_by_key_read_answers_the_shape_the_label_declares() {
  let grouped = emitted(&as_set(embedding_index()));
  let signature = door(&grouped, "get_image_embedding")
    .split('{')
    .next()
    .expect("the door has a signature");
  assert!(
    signature.contains("Held"),
    "a set election's by-key read does not answer the group: {signature}",
  );

  let single = emitted(&embedding_index());
  let signature = door(&single, "get_image_embedding")
    .split('{')
    .next()
    .expect("the door has a signature");
  assert!(
    !signature.contains("Held"),
    "a unit election's by-key read grew a group: {signature}",
  );
  assert!(
    door(&single, "get_image_embedding").contains("Several"),
    "a unit election stopped refusing an arity its declaration states",
  );
}

/// **THE SINGLE-VECTOR BY-EXAMPLE DOOR KEEPS ITS OWN ARITY JUDGMENT ON A SET ELECTION.** It asks
/// with ONE vector by construction, so an entity holding several has no single example — and the
/// refusal moved to where the arity is actually needed rather than disappearing.
#[test]
fn the_single_vector_by_example_door_still_needs_exactly_one() {
  let emission = emitted(&as_set(embedding_index()));
  let body = door(&emission, "retrieve_similar_by_image_embedding");
  assert!(
    body.contains("Several"),
    "the single-vector door silently picked one of several: {body}",
  );
  assert!(
    body.contains("get_image_embedding"),
    "it stopped reaching the door that owns the read: {body}",
  );
}

/// **IT IS TIER A AND ONLY TIER A** — no store, no filter, no gather, exactly like the two doors it
/// crosses.
#[test]
fn the_by_example_set_door_takes_no_store() {
  let emission = emitted(&as_set(embedding_index()));
  let signature = door(&emission, "retrieve_similar_by_image_embedding_with")
    .split('{')
    .next()
    .expect("the door has a signature");
  assert!(
    !signature.contains("AsyncGather"),
    "a tier-A door gathers: {signature}"
  );
  assert!(
    !signature.contains("filter"),
    "a tier-A door filters: {signature}"
  );
}

/// **TWO READ SCOPES, AND THE KNN ONE IS CLONEABLE.** The door makes `1 + m` engine calls, so the
/// by-key read has its own scope and the knn scope is cloned per query vector — which is the set
/// door's own `Clone` bound, named about a lifetime this signature spells.
#[test]
fn the_door_takes_a_scope_per_crossing_and_clones_the_asking_one() {
  let emission = emitted(&as_set(embedding_index()));
  let signature = door(&emission, "retrieve_similar_by_image_embedding_with")
    .split('{')
    .next()
    .expect("the door has a signature");
  assert!(
    signature.contains("own :"),
    "no own-read scope: {signature}"
  );
  assert!(signature.contains("scope :"), "no knn scope: {signature}");
  assert!(
    signature.contains("clone :: Clone"),
    "the asking scope is not cloneable, so `m` calls cannot be made: {signature}",
  );
  // The example is a BORROW: the caller keeps its key, and each stream's membership takes whatever
  // copy it needs on its own terms.
  assert!(signature.contains("key : &"), "{signature}");
}

/// **IT ANSWERS IN `Folded`**, because the FOLD authors this answer's order — the same reason its
/// `retrieve_keys_*` sibling does, and the reason neither of them mints an ordinal across the `m`
/// streams.
#[test]
fn the_door_answers_in_folded() {
  let emission = emitted(&as_set(embedding_index()));
  let signature = door(&emission, "retrieve_similar_by_image_embedding_with")
    .split('{')
    .next()
    .expect("the door has a signature");
  assert!(signature.contains("Folded"), "{signature}");
  assert!(
    signature.contains("OwnReadError"),
    "the door hands back some other vocabulary: {signature}",
  );
}

/// **IT WEARS ITS OWN SPAN**, named by its own `entry` — the seventh door of the instrumented half.
#[test]
fn the_door_names_itself_in_its_span() {
  let emission = emitted(&as_set(embedding_index()));
  assert!(
    emission.contains("entry = \"retrieve_similar_by_image_embedding_with\""),
    "the door opens no span of its own: {emission}",
  );
}