Predictor — AI Navigator Extraction

Source: Phoenix predictor.py (Python). Extracted 2026-04-08. Philosophy: “Navigation, not judgment” — show users where they’ll arrive.

Algorithm Summary

PhoenixPredictor is a behavioral trajectory forecasting engine that transforms historical event streams into probabilistic future scenarios. It extracts time-series metrics from typed event taxonomies, computes velocity and acceleration via linear regression on cumulative data, classifies directional trends, and maps aggregate trend signals onto seven discrete FutureScenario outcomes with Bayesian-adjusted probabilities. The module produces actionable navigation advice and projected milestones rather than compliance verdicts — a proactive “Navigator” counterpart to the reactive “Sentinel” pattern.

TrendAnalysis Algorithm

Input: a time-ordered list of (timestamp_seconds, weighted_value) tuples for a single behavioral metric.

def compute_trend(data_points, metric_name):
    # Requires >= 3 points; returns zero-confidence TrendAnalysis if fewer

    times     = [p[0] for p in data_points]
    values    = [p[1] for p in data_points]

    # 1. Build cumulative series (metrics like reputation are additive)
    cumulative = []
    total = 0.0
    for v in values:
        total += v
        cumulative.append(total)

    current_value = cumulative[-1]
    time_window_days = (times[-1] - times[0]) / 86400.0

    # 2. Velocity — average rate of change over the RECENT half of the window
    recent_start  = len(cumulative) // 2
    recent_values = cumulative[recent_start:]
    recent_times  = times[recent_start:]

    if len(recent_values) >= 2:
        value_change = recent_values[-1] - recent_values[0]
        time_change  = (recent_times[-1] - recent_times[0]) / 86400.0
        velocity = value_change / time_change if time_change > 0 else 0.0
    else:
        velocity = 0.0

    # 3. Acceleration — delta between first-half velocity and recent velocity
    if len(cumulative) >= 4:
        mid = len(cumulative) // 2
        v1  = (cumulative[mid-1] - cumulative[0]) / \
              ((times[mid-1] - times[0]) / 86400.0)  if times[mid-1] != times[0] else 0
        acceleration = velocity - v1
    else:
        acceleration = 0.0

    # 4. Direction classification
    if abs(velocity) < 0.01:
        direction = STABLE
    elif velocity > 0.1:
        direction = RISING
    elif velocity < -0.1:
        direction = DECLINING
    else:
        variance = sum((v - mean(values))**2 for v in values) / len(values)
        direction = VOLATILE if variance > 0.5 else STABLE

    # 5. Confidence: data density × trend consistency
    base_confidence  = min(1.0, len(data_points) / 50.0)
    consistency      = 1.0 - min(1.0, abs(acceleration) * 10)
    confidence       = (base_confidence + consistency) / 2

    return TrendAnalysis(metric_name, current_value, velocity,
                         acceleration, direction, confidence,
                         len(data_points), time_window_days)

Key design choices:

  • Cumulative series: event weights accumulate (reputation grows); velocity is measured on the cumulative, not raw, series.
  • Recent-half window for velocity: favors recent behavior over full history, giving more weight to current trajectory.
  • Dual-half split for acceleration: compares first-half velocity to second-half velocity, not point-to-point derivatives.
  • Confidence degrades with acceleration: a rapidly changing trend is less predictable and scores lower confidence.

FutureScenario Classification

Scenarios are determined from aggregate trend signals, not individual metrics. Seven outcome classes:

Scenario Condition Default Base Probability
EXCELLENCE Top-10% trajectory, strong positive avg_velocity 5%
GROWTH Positive trajectory, consistent engagement 20%
STABILITY Established position, low velocity 40%
STAGNATION Declining activity, narrow focus 15%
DECLINE Negative avg_velocity, reduced engagement 10%
RECOVERY Recent improvement after prior decline 5%
RISK High volatility, mixed signals 5%

Probability adjustment rules (applied before normalization):

if avg_velocity > 0.2:       # Strong positive momentum
    EXCELLENCE  += 0.15
    GROWTH      += 0.20
    STABILITY   -= 0.15
    STAGNATION  -= 0.10
    DECLINE     -= 0.10

elif avg_velocity < -0.1:    # Negative momentum
    DECLINE     += 0.20
    STAGNATION  += 0.10
    GROWTH      -= 0.15
    EXCELLENCE  -= 0.05
    RECOVERY    += 0.10

if percentile_rank > 80:     # Already a top performer
    EXCELLENCE  += 0.10

elif percentile_rank < 30:   # Low-ranked peer showing improvement
    RECOVERY    += 0.10

After adjustment, all probabilities are normalized to sum to 1.0. Scenarios with probability < 5% are dropped from the output. The remaining scenarios are sorted descending by probability; the top entry is most_likely_scenario.

ProbabilityPath Generation

Each ProbabilityPath bundles the scenario’s numeric probability with human-readable content:

ProbabilityPath(
    scenario          = FutureScenario,     # Enum value
    probability       = float,              # 0-1, normalized
    description       = str,               # One-sentence summary
    key_factors       = List[str],          # Why this scenario applies
    recommended_actions = List[str],        # Navigation steps to improve/maintain
    risk_factors      = List[str],          # What could go wrong
    time_horizon_days = int                 # Prediction window (30-60 days)
)

Horizon by scenario: EXCELLENCE → 60 days, RECOVERY → 45 days, all others → 30 days.

The generate_navigation_advice() method produces a single natural-language paragraph from the most_likely_scenario, optionally appending domain-specific guidance if a soul_summary (with primary_domains field) is provided.

Milestone projection (rising metrics only):

# For each RISING metric with velocity > 0:
next_milestone = ceil(current_value / 10) * 10 + 10   # Round up to next decade
days_to_milestone = min(365, (next_milestone - current_value) / velocity)

Up to 5 milestones returned, including a total_standing tier advancement.

Key Enums / States 

class TrendDirection(Enum):
    RISING    = "rising"     # velocity > 0.1
    STABLE    = "stable"     # abs(velocity) < 0.01, or low-variance near-zero
    DECLINING = "declining"  # velocity < -0.1
    VOLATILE  = "volatile"   # near-zero velocity but variance > 0.5

class FutureScenario(Enum):
    EXCELLENCE = "excellence"   # Top 10% of peers
    GROWTH     = "growth"       # Positive trajectory
    STABILITY  = "stability"    # Maintaining current position
    STAGNATION = "stagnation"   # No growth, risk of decline
    DECLINE    = "decline"      # Negative trajectory
    RECOVERY   = "recovery"     # Bouncing back from decline
    RISK       = "risk"         # High volatility, uncertain outcome

Event taxonomy weights (mapping event codes to behavioral metric vectors):

Event Code Metrics Weighted Description
EVT-A03 builder+0.8, reliable+0.7 Commitment completed
EVT-A04 builder+0.9, quality+0.8 Commitment verified
EVT-A05 builder−0.5, reliable−0.6 Commitment failed (penalty)
EVT-B04 judge+0.7, fair+0.6 Dispute resolved
EVT-F02 steward+0.4, engaged+0.5 Vote cast
EVT-H01 builder+0.8, reliable+0.7 Promise fulfilled
EVT-H02 builder+0.7, creative+0.6 Value created
EVT-H03 mentor+0.6, generous+0.7 Peer supported
EVT-H04 mentor+0.8, knowledgeable+0.7 Knowledge shared
EVT-H05 guardian+0.7, courageous+0.8 Risk taken
EVT-H07 judge+0.8, diplomatic+0.7 Conflict mediated
EVT-H08 steward+0.9, patient+0.8 Long-term commitment
EVT-H09 innovator+0.9, creative+0.8 Innovation introduced
EVT-H12 investor+0.7, strategic+0.6 Resources allocated

Effective value per event = base_weight × payload.intensity (intensity defaults to 1.0). Negative weight events (e.g., EVT-A05) use abs(weight) as intensity floor.

Invariants

  1. Navigation, not judgment. The predictor shows users where their current trajectory leads; it does not enforce compliance. Output must be framed as directional guidance, never as verdicts or scores used for access control.

  2. Minimum data threshold. Trends require at least min_data_points events (default 10) before a metric is included in scenario generation. Metrics below this threshold are silently excluded; no partial predictions are emitted.

  3. Probability normalization. After all adjustments, scenario probabilities must sum to 1.0. The normalization step is mandatory even if only one scenario survives the ≥5% cutoff.

  4. Percentile defaults to median. If no all_peer_standings comparison set is provided, percentile_rank defaults to 50.0. Predictions remain valid but cannot leverage peer-relative adjustments.

  5. Cumulative metric model. All metrics are treated as cumulative (reputation-like) quantities. The predictor is not designed for ratio or percentage metrics; callers must pre-normalize if needed.

  6. Soul summary is optional. Domain-specific navigation advice is best-effort. A missing soul_summary produces general advice only; it never causes a prediction failure.

  7. Singleton instance. The module exports a pre-constructed predictor = PhoenixPredictor() singleton using default config. Callers may instantiate PhoenixPredictor(config={...}) to override min_data_points, time_window_days, scenario_horizon_days, or confidence_threshold.

Colibri Integration Points

δ Model Router (primary target): The PhoenixPredictor is the reference implementation for δ (delta)’s proactive intelligence layer. Where δ currently routes tool calls based on declared capability, adding PhoenixPredictor.predict() would enable Colibri to surface trajectory forecasts for agents, tasks, or workflow pipelines — “if the current task pattern continues, the project will arrive at STAGNATION in 30 days.” This transforms δ from a reactive router into a proactive navigator.

λ Reputation: The event taxonomy weights (EVT-A03 through EVT-H12) constitute a behavioral metric schema that maps directly to λ (lambda) Reputation’s event-driven standing model. The builder, reliable, judge, mentor, steward, guardian, innovator, and investor metric names can be adopted verbatim as Colibri soul-vector dimensions.

ξ Identity: The soul_summary parameter that generate_navigation_advice() accepts — carrying primary_domains — is the integration seam between the predictor and ξ Identity’s soul profile. Feeding a ξ soul vector into the predictor’s advice generator produces domain-personalized navigation text (“your strength is in ‘builder’ — leverage this for maximum impact”).

θ Consensus / π Governance: The FutureScenario classification (EXCELLENCE → RISK) can feed governance dashboards to flag members or projects trending toward DECLINE or RISK before they cross thresholds that trigger formal review. Proactive visibility is cheaper than reactive remediation.

Adoption path for Colibri:

  • Step 1: Port TrendAnalysis, FutureScenario, ProbabilityPath, and PredictionResult dataclasses to TypeScript/Node.js value objects.
  • Step 2: Implement analyze_event_history() against Colibri’s existing event store (audit log or task history).
  • Step 3: Wire compute_trend() and generate_scenarios() as a predict tool in the δ Model Router domain.
  • Step 4: Surface navigation_advice and key_milestones as readable output in task dashboard or agent status tools.
  • Step 5 (v2): Connect soul_summary input to ξ Identity soul vectors for personalized navigation.

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.