Module causal_predict 

Causal collapse prediction via O(1) analytical perturbation + EML correction.

Predicts how adding a new edge will change the causal graph’s algebraic connectivity (lambda_2) without recomputing the full O(k*m) Lanczos eigenvalue iteration. The core insight comes from first-order eigenvalue perturbation theory:

delta_lambda_2 = w * (phi[u] - phi[v])^2

where phi is the Fiedler vector and w is the edge weight. Edges that bridge the spectral partition (phi[u] and phi[v] have opposite signs) produce the largest coherence gains.

Components

• predict_delta_lambda2 – O(1) analytical perturbation formula
• rank_evidence_by_impact – rank candidate edges by predicted impact
• detect_conversation_cycle – detect stuck/oscillating conversations
• CausalCollapseModel – EML-enhanced prediction with learned corrections
• CausalGraph::rank_candidates – convenience method on the causal graph

References

See .planning/development_notes/eml-causal-collapse-research.md for the full mathematical derivation and design rationale.

Structs

CausalCollapseModel

EML-enhanced delta prediction for when the analytical formula is insufficient.

CausalRankRequest

Request payload for the causal.rank RPC endpoint.

CausalRankResponse

Response payload for the causal.rank RPC endpoint.

CoherenceTracker

Tracks coherence history for conversation cycle detection.

CollapseFeatures

Feature vector for the causal collapse correction model.

EvidenceRanking

Result of ranking a candidate evidence addition.

Enums

ConversationState

State of a conversation’s coherence trajectory.

Functions

detect_conversation_cycle

Detect if coherence changes indicate a circular/stuck conversation.

is_redundant

Check if a candidate edge is redundant given recent additions.

predict_delta_lambda2

First-order perturbation prediction: delta_lambda_2 = w * (phi[u] - phi[v])^2

rank_evidence_by_impact

Rank candidate evidence by predicted coherence impact.