RAG++ Specification

QueryBundle {
    embedding: Vector<f32>[D]      # Query embedding, dimension D
    k: u32                          # Number of candidates to retrieve
    metadata_filter: FilterExpr?    # Optional metadata constraints
    index_names: Vec<String>?       # Optional: specific indexes to search
}

MemoryRecord {
    id: String                      # Unique identifier
    embedding: Vector<f32>[D]       # Trajectory embedding
    context: String                 # Human-readable context description
    outcome: f64                    # Primary outcome metric (e.g., success rate)
    metadata: Map<String, Value>    # Arbitrary key-value metadata
    created_at: u64                 # Unix timestamp (ms)
    stats: OutcomeStats             # Running statistics for this record
}

MetadataValue =
    | String(String)
    | Int(i64)
    | Float(f64)
    | Bool(bool)
    | StringList(Vec<String>)

PriorBundle {
    mean: f64                       # Mean outcome of retrieved trajectories
    variance: f64                   # Variance of outcomes
    confidence: f64                 # Confidence in estimate (0-1)
    count: u64                      # Number of samples contributing
    min: f64                        # Minimum observed outcome
    max: f64                        # Maximum observed outcome

    # Optional extended statistics
    percentiles: Map<u8, f64>?      # e.g., {50: 0.75, 95: 0.92}
    outcome_distribution: Histogram? # Bucketed distribution
}

QueryResponse {
    prior: PriorBundle              # Computed priors from retrieved records
    candidates: Vec<RankedCandidate> # Top-k candidates with scores
    latency: Duration               # Query execution time
    indexes_searched: Vec<String>   # Which indexes were queried
}

RankedCandidate {
    record_id: String               # Reference to MemoryRecord
    score: f64                      # Retrieval score (higher = more relevant)
    distance: f64                   # Raw distance from query
    rank: u32                       # Position in result list (1-indexed)
}

on update(x):
    count += 1
    delta = x - mean
    mean += delta / count
    delta2 = x - mean
    M2 += delta * delta2

variance = M2 / count  (population)
variance = M2 / (count - 1)  (sample)

RRF_score(d) = Σ 1 / (k + rank_i(d))

IndexConfig {
    dimension: u32                  # Embedding dimension (required)
    distance_type: DistanceType     # L2 | Cosine | InnerProduct
    index_type: IndexType           # Flat | HNSW

    # HNSW-specific
    hnsw_m: u32 = 16                # Max connections per node
    hnsw_ef_construction: u32 = 200 # Construction search width
    hnsw_ef_search: u32 = 50        # Query search width
}

QueryEngineConfig {
    default_k: u32 = 10             # Default retrieval count
    fusion_strategy: FusionStrategy = RRF
    reranker: RerankerConfig?       # Optional reranking
    cache_config: CacheConfig?      # Optional query caching
    timeout_ms: u64 = 1000          # Query timeout
}

CacheConfig {
    max_entries: usize = 10000      # Maximum cached queries
    ttl_seconds: u64 = 300          # Time-to-live
    enabled: bool = true
}

Error =
    | DimensionMismatch { expected: u32, got: u32 }
    | RecordNotFound { id: String }
    | DuplicateRecord { id: String }
    | IndexNotFound { name: String }
    | InvalidFilter { reason: String }
    | QueryTimeout { elapsed_ms: u64 }
    | WalCorrupted { sequence: u64 }
    | ChecksumMismatch

# Example: Sentence Transformers
from sentence_transformers import SentenceTransformer
model = SentenceTransformer('all-MiniLM-L6-v2')
embedding = model.encode("trajectory context description")

# Example: Using priors for action conditioning
response = rag.query(query_bundle)
prior = response.prior

# Condition policy on retrieved priors
if prior.confidence > 0.8:
    action_distribution = policy.forward(
        state,
        prior_mean=prior.mean,
        prior_variance=prior.variance
    )

// Create index
let mut index = FlatIndex::new(512, DistanceType::Cosine);

// Add records
index.add("rec-1", &embedding)?;

// Search
let results = index.search(&query_embedding, 10)?;

// Query engine (full pipeline)
let engine = QueryEngine::new(config);
let response = engine.query(QueryRequest {
    embedding: query_vec,
    k: 10,
    filter: None,
    index_names: None,
})?;

// Access priors
println!("Prior mean: {}", response.prior.mean);

from rag_plusplus import FlatIndex, IndexRegistry, DistanceType

# Create index
index = FlatIndex(dimension=512, distance_type=DistanceType.Cosine)

# Add vectors
index.add("rec-1", embedding)

# Search
results = index.search(query_embedding, k=10)

# Multi-index
registry = IndexRegistry()
registry.register("semantic", semantic_index)
registry.register("temporal", temporal_index)
results = registry.search_all(query, k=10)