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

Constants

MMR_LAMBDA

Default MMR trade-off: how much relevance (Phi) is weighted against non-redundancy during integration-aware selection (#5). 0.7 keeps relevance dominant while still penalizing near-duplicates.

Functions

active_weights

The current active (learned) FieldWeights, or the default when none have been installed yet. Cheap — a single RwLock read — so safe on the hot path.

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.

mmr_score

Maximal Marginal Relevance score (#5): reward relevance (phi) but penalize redundancy with the already-selected set (max_similarity). This makes selection integration-aware in the IIT sense — a context package gains more from a complementary item than from a near-duplicate of one it already holds. Deterministic: a pure function of its inputs, no sampling.

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.

set_active_weights

Install the bandit-selected FieldWeights as the process-wide active weights (#4). Deterministic given the bandit posterior; called when an arm is chosen.