API Reference

function createLoop(definition: LoopDefinition): SemanticLoop

Factory function that resolves declarative config into wired instances. Config slots accept three forms:

• String shorthand — e.g., "supabase", "openai", "heuristic". Reads env vars.
• Config object — e.g., { provider: "supabase", url: "...", serviceRoleKey: "..." }. Explicit values.
• Raw instance — any object implementing the interface (MemoryStore, EmbeddingProvider, Critic). Escape hatch for custom backends.

Resolution is checked via duck-typing: isMemoryStore() checks for "upsertItem" in value, isEmbeddingProvider() checks for "embed" in value && "dimensions" in value.

interface SemanticLoop {
  seed(items: readonly ItemInput[]): Promise<readonly SemanticItem[]>;
  select(query?: string, opts?: SelectOptions): Promise<SelectedCandidate>;
  ingest(itemId: string, platform: string, metrics: EngagementMetrics, opts?: IngestOptions): Promise<ProcessedOutcome>;
  readonly engine: SemanticLoopEngine;
  readonly embedder: EmbeddingProvider;
  readonly store: MemoryStore;
}

seed() uses embedder.embedBatch() when available (reducing API calls), then falls back to individual embed() calls. Items that already have an embedding field skip embedding generation.

select() embeds the query only when the embedder has dimensions > 0. Otherwise queryVector is undefined and the store defaults to a fixed similarity value.

ingest() calls deriveEngagementScore(metrics) unless an explicit engagementScore is provided via IngestOptions.

Each config slot uses a union type allowing string shorthand, typed config object, or raw interface instance. Resolution order in the factory:

1. Check if value implements the interface (duck typing)
2. Check for string shorthand
3. Check for config object with provider field
4. Throw ValidationError on unrecognized config

String shorthands read env vars via Deno.env.get(). Missing env vars throw ValidationError with a descriptive message.

class SemanticLoopEngine {
  constructor(options: EngineOptions)
  seed(items: readonly SemanticItem[]): Promise<void>
  selectNext(request: SelectRequest): Promise<SelectedCandidate>
  ingestOutcome(outcome: OutcomeSignal): Promise<ProcessedOutcome>
}

The engine is stateless — all state lives in the MemoryStore. Every method is a request-response cycle against the store.

EngineOptions:

interface EngineOptions {
  readonly store: MemoryStore;
  readonly critic: Critic;
  readonly telemetry?: Telemetry;
  readonly config?: Partial<LoopConfig>;
  readonly random?: () => number;  // injectable for deterministic tests
  readonly now?: () => Date;       // injectable for deterministic tests
}

The random and now injectors make the engine fully deterministic for testing. The engine catches nothing — errors propagate to the caller. Private fields use true ES # private members.

The ingestOutcome pipeline: validate → getItem → getAggregate → critic.score → combineScores → appendOutcome → updateAggregate. Final score = criticScore × criticWeight + engagementScore × engagementWeight.

All fields are readonly. The embedding is readonly number[] (aliased as EmbeddingVector). Dates are ISO 8601 strings, not Date objects, for serialization safety across edge runtimes.

When embedding is provided, the item skips the embedding provider entirely. This is useful for pre-computed embeddings or migrating data. The seed() method batch-embeds all items missing embeddings in a single embedBatch() call when available.

Similarity is cosine similarity mapped to [0, 1] via (dot / (|a| * |b|) + 1) / 2. When no query vector is provided, the store assigns a default similarity of 0.5.

The weightedScore is the four-dimensional weighted sum: similarity × w1 + scoreAvg × w2 + exploration × w3 + freshness × w4. When strategy is "explore", the selected candidate may not have the highest weightedScore — it was randomly sampled from the top-k pool.

Aggregation uses decay-weighted sums: scoreSum = oldScoreSum × decayFactor + finalScore, then scoreAvg = scoreSum / attempts. All averages are clamped to [0, 1]. The last* fields are from the most recent outcome only — useful for debugging and analytics.

The high-level ingest() constructs this from its arguments, auto-generating id and occurredAt. When using the engine directly, you must provide all fields. The engagementScore must be pre-derived (use deriveEngagementScore() from utils).

Engagement derivation: interactionRate = (likes + comments×2 + shares×3 + saves×2 + clicks×2 + conversions×4) / views. Watch signal: clamp(avgWatchSeconds / 30). Final: interactionRate × 0.7 + watchSignal × 0.3. Uses views first, falls back to impressions, then 0.

The aggregate is the post-update state. The finalScore is criticScore × criticWeight + engagementScore × engagementWeight (default 0.6/0.4 split).

Weights don't need to sum to 1 — the final weighted score is clamped to [0, 1]. Freshness uses exponential decay: e^(-ln(2) × hoursElapsed / halfLife). Exploration score: 1 / max(1, attempts + 1).

The decay is applied to scoreSum before adding the new final score: scoreSum = oldScoreSum × decayFactor + finalScore. This means with a decay of 0.95, after 14 outcomes the oldest score's contribution is 0.95^14 ≈ 0.49 — halved.

The selection field allows per-call overrides of epsilon, weights, etc. This is useful for A/B testing different selection strategies without creating multiple loop instances.

Setting engagementScore bypasses deriveEngagementScore(). Useful when you have a custom engagement formula or pre-computed scores from an external system. The payload is stored alongside the outcome for audit trails.

interface MemoryStore {
  upsertItem(item: SemanticItem): Promise<void>;
  retrieve(request: RetrieveRequest): Promise<readonly Candidate[]>;
  getItem(itemId: string): Promise<SemanticItem | null>;
  getAggregate(itemId: string): Promise<AggregateState | null>;
  appendOutcome(outcome: OutcomeSignal, critic: CriticResult, finalScore: number): Promise<void>;
  updateAggregate(update: AggregateUpdate, config: AggregationConfig): Promise<AggregateState>;
}

Key contract requirements for custom implementations:

• upsertItem must be idempotent (use on conflict in SQL)
• retrieve must return candidates sorted by similarity desc, then scoreAvg desc
• updateAggregate must apply decay and clamp all averages to [0, 1]
• updateAggregate should use row-level locking to prevent race conditions
• All methods are async for adapter interface consistency

The aggregateBefore field provides historical context — the critic can factor in how many attempts the item has had and its running averages. The meta field in CriticResult is stored alongside the outcome for audit trails.

When dimensions is 0 (as with NoopEmbedding), select() skips query embedding entirely. Implement this interface for custom embedding backends (Cohere, local ONNX models, etc.).

Span names: "semantic_loop.seed", "semantic_loop.select_next", "semantic_loop.ingest_outcome". Attributes include item count, tribe, kind, strategy, scores. The interface is intentionally minimal to avoid vendor lock-in.

Accepts an optional now?: () => Date constructor argument for deterministic testing. Similarity without a query vector defaults to 0.5. Sorting: similarity desc, then scoreAvg desc. Retrieval limit defaults to 8.

Options:

interface SupabaseRpcStoreOptions {
  readonly url: string;
  readonly serviceRoleKey: string;
  readonly itemsTable?: string;       // "semantic_items"
  readonly aggregatesTable?: string;  // "semantic_item_scores"
  readonly rpc?: Partial<SupabaseRpcNames>;
  readonly fetcher?: typeof fetch;    // injectable for testing
}

All writes go through RPC functions for atomicity. sl_apply_outcome uses SELECT ... FOR UPDATE for row-level locking. The fetcher option lets you inject a mock fetch for testing without hitting Supabase.

Score formula: 0.2 + engagementBoost + noveltyBoost + historicalStability - penalty, where:

• engagementBoost = engagementScore × 0.6
• noveltyBoost = min(0.25, noveltyHits × 0.06)
• penalty = min(0.2, penaltyHits × 0.05)
• historicalStability = min(0.15, scoreAvg × 0.15) (only when attempts > 0)

Tags emitted: "novelty" (has novelty hits), "hype-risk" (has penalty hits), "validated" (engagement ≥ 0.5), "needs-more-data" (engagement < 0.5).

The baseUrl option supports Azure OpenAI, proxy endpoints, and compatible APIs. The embedBatch() method sends all texts in a single API call and sorts results by index to maintain order. Throws on non-OK responses with the HTTP status code.