Skip to main content

Core Functions

The main LSH functions available in all three languages.

sign_text / signText (Recommended)​

High-level convenience function for generating signatures from text prompts.

This is the recommended API for most use cases. It handles the entire pipeline: embedding generation → normalization → LSH hashing → signature formatting.

Rust:

pub async fn sign_text(
    text: &str,
    provider: &dyn EmbeddingProvider,
    version: SignatureVersion,  // Use SignatureVersion::Latest for the latest model
    config: Option<LshConfig>,
) -> Result<SignatureResult>

Python:

async def sign_text(
    text: str,
    provider: EmbeddingProvider,
    version: SignatureVersion = SignatureVersion.LATEST,
    config: Optional[LshConfig] = None,
) -> SignatureResult

TypeScript:

async function signText(
  text: string,
  provider: EmbeddingProvider,
  version: SignatureVersion = SignatureVersion.LATEST,
  config?: LshConfig
): Promise<SignatureResult>

Parameters:

  • text: The input text prompt to sign
  • provider: An embedding provider (OpenAIProvider, OnnxProvider, or custom)
  • version: Signature version (defaults to LATEST, which resolves to V1). Options: V0, V1, or LATEST
  • config: Optional LSH configuration (defaults to 3 families, 256 bits, 16 bands)

Returns:

  • SignatureResult: Complete result including:
    • Formatted signature string (e.g., "0din-v1:8d000000...")
    • Provider and model metadata
    • Embedding SHA256 hash
    • LSH families and bands
    • Timing information

Example:

// Use latest model (recommended)
let result = sign_text("How do I reset my password?", &provider, SignatureVersion::Latest, None).await?;
println!("{}", result.to_signature_string());

// Or omit version in Python/TypeScript (defaults to LATEST)
// Python: result = await sign_text("How do I reset my password?", provider)
// TypeScript: const result = await signText("How do I reset my password?", provider);

simhash_lsh_multi (Low-Level)​

Generate LSH signatures from a normalized embedding vector.

Rust:

pub fn simhash_lsh_multi(normalized_vector: &[f32], config: &LshConfig) -> Vec<LshFamily>

Python:

def simhash_lsh_multi(
    normalized_vector: list[float],
    families: int = 3,
    bits: int = 256,
    bands: int = 16
) -> list[LSHFamily]

TypeScript:

function simhashLshMulti(
  normalizedVector: number[],
  config?: LshConfig
): LSHFamily[]

normalize_vector​

Normalize a vector to unit length (L2 norm = 1).

Required preprocessing step before LSH hashing. Ensures cosine similarity can be estimated from Hamming distance.

pub fn normalize_vector(vector: &[f32]) -> Vec<f32>

Parameters:

  • vector: Input vector (any dimensionality)

Returns:

  • Normalized vector where ||v|| = 1

Example:

use odin_prompt_toolkit::normalize_vector;

let vector = vec![3.0, 4.0];  // magnitude = 5
let normalized = normalize_vector(&vector);
// Result: [0.6, 0.8]

hamming_distance_hex​

Compute Hamming distance (number of differing bits) between two hex-encoded signatures.

Used to measure similarity between LSH signatures. Lower distance = higher similarity.

pub fn hamming_distance_hex(hex_a: &str, hex_b: &str) -> u32

Parameters:

  • hex_a: First signature (hex string, e.g., "8d000000...")
  • hex_b: Second signature (hex string, same length as hex_a)

Returns:

  • Number of differing bits (0 to 4 × hex_length)

Example:

use odin_prompt_toolkit::hamming_distance_hex;

let sig_a = "8d000000ac854dae";
let sig_b = "8d000000ac854daf";
let distance = hamming_distance_hex(sig_a, sig_b);
// Result: 1 (last bit differs)

cosine_from_hamming​

Estimate cosine similarity from Hamming distance using the formula: cos(π × d/n) where d is Hamming distance and n is the number of bits.

This is based on the Random Hyperplane LSH theoretical relationship between Hamming distance and cosine similarity.

pub fn cosine_from_hamming(hamming_distance: u32, bits: u32) -> f64

Parameters:

  • hamming_distance: Hamming distance between signatures
  • bits: Total number of bits in each signature (e.g., 256)

Returns:

  • Estimated cosine similarity in range [-1.0, 1.0]

Example:

use odin_prompt_toolkit::{hamming_distance_hex, cosine_from_hamming};

let distance = hamming_distance_hex("8d00...", "8d01...");
let similarity = cosine_from_hamming(distance, 256);
// e.g., similarity ≈ 0.95 for small distance
info

The cosine estimation is most accurate for similarities > 0.5. For very dissimilar vectors (cosine < 0), LSH provides weaker guarantees.

compute_embedding_sha256​

Compute the SHA256 hash of a normalized embedding vector in canonical JSON format.

Used to uniquely identify embeddings and verify cross-language compatibility. All three implementations produce identical SHA256 hashes for identical vectors.

pub fn compute_embedding_sha256(normalized_embedding: &[f32]) -> String

Parameters:

  • normalized_embedding: Normalized vector (L2 norm = 1)

Returns:

  • Hex-encoded SHA256 hash (64 characters)

Example:

use odin_prompt_toolkit::{normalize_vector, compute_embedding_sha256};

let vector = vec![0.5, 0.5, 0.5, 0.5];
let normalized = normalize_vector(&vector);
let hash = compute_embedding_sha256(&normalized);
// Result: "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a"
Cross-Language Verification

All three implementations use the same canonical JSON format: {"embedding":[0.5,0.5,0.5,0.5]} with no spaces and consistent float precision. This ensures bit-identical SHA256 hashes across languages.

See the Quick Start for usage examples.