Module context_field 

Context Field Theory (CFT) – unified potential function for context items.

Combines information-theoretic, graph-based, and history signals into a single scalar potential Phi(i,t) per context item, enabling principled budget allocation and view selection.

Scientific basis: Phi(i,t) = w_RR + w_SS + w_GG + w_HH - w_CC - w_DD where R = task relevance (heat diffusion + PageRank), S = surprise (cross-entropy with Zipfian prior), G = graph proximity (weighted BFS distance), H = history signal (bandit feedback), C = token cost for the active view, D = redundancy with already-selected items (Jaccard).

Structs

ContextField

The Context Field: computes Phi for a set of items given a task context.

ContextItemId

Stable, content-addressed identifier for a context item. Derived from kind + source_path so the same file always maps to the same ID within a session, regardless of content changes.

FieldPotential

Combined potential for a context item.

FieldSignals

Raw signal components for a single context item before combination.

FieldWeights

Weights for the potential function components. Adapted via Thompson Sampling (bandit.rs) over time.

Provenance

TokenBudget

Token budget parameters for compilation.

ViewCosts

Token-cost estimates for each available view of a context item.

Enums

ContextKind

ContextState

ViewKind

Functions

compute_signals_for_path

Compute real signals for a file path using existing scoring modules. Bridges CFT with the information-theoretic, graph-based, and history subsystems already in lean-ctx.

efficiency

Compute efficiency ratio: Phi per token. Used by the greedy knapsack in the compiler.

normalize_graph_proximity

Normalize graph proximity (inverse of distance) to [0, 1]. Distance 0 = same file = 1.0, distance N = 1/(1+N).

normalize_relevance

Normalize a relevance score from task_relevance.rs to [0, 1].

normalize_surprise

Normalize a surprise score from surprise.rs to [0, 1]. Surprise range is typically 5.0 (common) to 17.0+ (rare).

normalize_token_cost

Normalize token cost relative to budget.