strathmark 2.0.0__py3-none-any.whl

strathmark/__init__.py

@@ -0,0 +1,335 @@
+"""
+strathmark — Woodchopping Handicap Engine
+==========================================
+
+A Python package that exposes the STRATHMARK handicap calculation
+engine for use in external applications (tournament software, scoring apps, etc.).
+
+Quick start
+-----------
+    from strathmark import HandicapCalculator, CompetitorRecord, WoodProfile, ResultStore
+    from strathmark.predictor import HistoricalResult
+
+    store = ResultStore()          # opens ~/.strathmark/results.db
+    calc  = HandicapCalculator()
+
+    competitor = CompetitorRecord(
+        name="Alice Smith",
+        history=store.get_competitor_history("Alice Smith", "SB"),
+    )
+    wood  = WoodProfile(species="Pine", diameter_mm=300, quality=5)
+    marks = calc.calculate([competitor], wood, "SB")
+
+Python import API (for STRATHEX and other Python projects):
+    from strathmark import HandicapCalculator
+    from strathmark.fairness import simulate_and_assess_handicaps
+    from strathmark.variance import run_monte_carlo_simulation
+
+HTTP REST API (for web/mobile/non-Python projects):
+    uvicorn strathmark.api:app --port 8000
+    POST http://localhost:8000/calculate
+
+Design Rules (invariants enforced in all submodules)
+-----------------------------------------------------
+    - Mark floor:    3 seconds (never lower, under any circumstances)
+    - Mark ceiling:  system-wide 183 seconds (180s time limit + 3s minimum mark)
+                     event configs may enforce a lower ceiling
+    - Variance:      absolute +-3 seconds ONLY — proportional variance is forbidden
+    - Prediction engine: manual override, otherwise the validated V2 posterior
+      with an explicit deterministic rollback fallback
+    - Time-decay:    exponential decay, 2-year half-life (730 days)
+    - Output:        plain text only — no emojis, no ANSI color codes
+    - Style:         lean and simple, no unnecessary complexity
+
+Downstream integration:
+    Pin an immutable reviewed release or commit. STRATHEX uses direct Python for its
+    offline default and may select the REST /calculate transport explicitly.
+"""
+
+from strathmark.auth import (
+    ACTOR_ATTESTATION_SCHEMA_VERSION,
+    SHADOW_ATTESTATION_AUDIENCE,
+    VerifiedActorAttestation,
+    shadow_auth_configuration_status,
+    sign_actor_attestation,
+)
+from strathmark.calculator import HandicapCalculator, process_competition_day
+from strathmark.consumer_contract import (
+    EXPECTED_SHADOW_CONSUMER_PATHS,
+    SHADOW_CONSUMER_CONTRACT_VERSION,
+    ShadowConsumerContractIntegrityError,
+    load_shadow_consumer_contract,
+    shadow_consumer_contract_bytes,
+    shadow_consumer_contract_digest,
+)
+from strathmark.db import (
+    format_proam_results,
+    get_active_model_version,
+    get_competitor_bias,
+    mirror_prediction_ledger,
+    pull_competitors,
+    pull_results,
+    push_competitors,
+    push_results,
+    push_results_dicts,
+    record_calibration,
+    record_prediction,
+    record_prediction_residuals,
+    register_competitor,
+    register_model_version,
+    set_active_model,
+    settle_prediction,
+    store_features,
+)
+from strathmark.drift import DriftReport, evaluate_drift, is_drifting
+from strathmark.fairness import (
+    get_ai_assessment_of_handicaps,
+    get_championship_race_analysis,
+    simulate_and_assess_handicaps,
+)
+from strathmark.features import (
+    ExclusionDiagnostics,
+    PriorEvidence,
+    build_prior_evidence,
+    normalize_prediction_as_of,
+    resolve_species_properties,
+)
+from strathmark.ledger import (
+    LEGACY_SETTLEMENT_REASON_CODES,
+    MAX_NUMERIC_RAW_TIME_SECONDS,
+    NUMERIC_OUTCOME_REASON_CODES,
+    LedgerConflictError,
+    LedgerMonitoringStatus,
+    LedgerPrediction,
+    LedgerWriteResult,
+    NumericOutcomeRevisionResult,
+    NumericSettlementRevision,
+    NumericSettlementRevisionResult,
+    PredictionLedger,
+    SettlementConflictError,
+    SettlementResult,
+)
+from strathmark.llm import call_ollama, check_ollama_connection
+from strathmark.loader import load_results_for_competitor, load_woodchopping_xlsx
+from strathmark.mark_optimizer import (
+    MarkOptimizationResult,
+    legacy_rounded_gap_marks,
+    optimize_joint_marks,
+)
+from strathmark.mnemex import (
+    is_mnemex_configured,
+    pull_canonical_competitors,
+    pull_canonical_results,
+    register_competitor_in_mnemex,
+)
+from strathmark.prediction_v2 import (
+    ChronologicalCalibrator,
+    ForecastInterval,
+    PredictionV2Model,
+    PredictionV2Request,
+    PredictiveDistribution,
+)
+from strathmark.predictor import (
+    CompetitorRecord,
+    FilePredictionProvider,
+    HistoricalResult,
+    PredictionBundle,
+    PredictionContext,
+    PredictionEngineProvider,
+    PredictionInterval,
+    PredictionResult,
+    StaticPredictionProvider,
+    WoodProfile,
+    get_all_predictions,
+    get_best_prediction,
+    get_prediction_provider,
+    predict_baseline,
+    select_best_prediction,
+)
+from strathmark.shadow import (
+    ACTIVE_INPUT_SCHEMA_VERSION,
+    IDENTITY_SCHEMA_VERSION,
+    OBSERVATION_SCHEMA_VERSION,
+    RECEIPT_CORE_SCHEMA_VERSION,
+    REQUEST_PROJECTION_SCHEMA_VERSION,
+    SHADOW_TARGET_SINGLE_ELAPSED,
+    ShadowCalculationResult,
+    ShadowFieldRequest,
+    ShadowLiveStatus,
+    ShadowPredictionService,
+    ShadowReceipt,
+)
+from strathmark.store import (
+    DEFAULT_MAX_SNAPSHOT_AGE_DAYS,
+    EVIDENCE_ACTIVATION_SCHEMA_VERSION,
+    EVIDENCE_HISTORY_ROW_SCHEMA_VERSION,
+    EVIDENCE_SNAPSHOT_SCHEMA_VERSION,
+    EVIDENCE_SNAPSHOT_SOURCE_SCHEMA_VERSION,
+    MAX_CAPTURE_CLOCK_SKEW_SECONDS,
+    EvidenceSnapshotConflictError,
+    EvidenceSnapshotIntegrityError,
+    EvidenceSnapshotPayload,
+    EvidenceSnapshotSelection,
+    EvidenceSnapshotSource,
+    EvidenceSnapshotStatus,
+    ResultStore,
+    canonical_evidence_source_digest,
+)
+from strathmark.sync import (
+    SyncResult,
+    manual_force_sync,
+    nightly_batch,
+    strathex_finalization,
+)
+from strathmark.utils import score_prediction_accuracy
+from strathmark.variance import (
+    audit_mark_sheet,
+    estimate_competitor_std_dev,
+    quick_fairness_check,
+    run_monte_carlo_simulation,
+)
+from strathmark.visualization import (
+    generate_simulation_summary,
+    visualize_simulation_results,
+)
+
+__all__ = [
+    # Core calculation
+    "HandicapCalculator",
+    "process_competition_day",
+    # Data types
+    "CompetitorRecord",
+    "WoodProfile",
+    "HistoricalResult",
+    "PredictionResult",
+    "PredictionContext",
+    "PredictionInterval",
+    "PredictionBundle",
+    "PredictionEngineProvider",
+    "StaticPredictionProvider",
+    "FilePredictionProvider",
+    "PriorEvidence",
+    "ExclusionDiagnostics",
+    # Prediction API
+    "get_best_prediction",
+    "get_prediction_provider",
+    "get_all_predictions",
+    "select_best_prediction",
+    "predict_baseline",
+    "build_prior_evidence",
+    "normalize_prediction_as_of",
+    "resolve_species_properties",
+    "PredictionV2Model",
+    "PredictionV2Request",
+    "PredictiveDistribution",
+    "ForecastInterval",
+    "ChronologicalCalibrator",
+    "SHADOW_CONSUMER_CONTRACT_VERSION",
+    "EXPECTED_SHADOW_CONSUMER_PATHS",
+    "ShadowConsumerContractIntegrityError",
+    "load_shadow_consumer_contract",
+    "shadow_consumer_contract_bytes",
+    "shadow_consumer_contract_digest",
+    "MarkOptimizationResult",
+    "legacy_rounded_gap_marks",
+    "optimize_joint_marks",
+    # Persistence
+    "ResultStore",
+    "EvidenceSnapshotPayload",
+    "EvidenceSnapshotSelection",
+    "EvidenceSnapshotSource",
+    "EvidenceSnapshotStatus",
+    "EvidenceSnapshotConflictError",
+    "EvidenceSnapshotIntegrityError",
+    "canonical_evidence_source_digest",
+    "EVIDENCE_SNAPSHOT_SOURCE_SCHEMA_VERSION",
+    "EVIDENCE_SNAPSHOT_SCHEMA_VERSION",
+    "EVIDENCE_HISTORY_ROW_SCHEMA_VERSION",
+    "EVIDENCE_ACTIVATION_SCHEMA_VERSION",
+    "DEFAULT_MAX_SNAPSHOT_AGE_DAYS",
+    "MAX_CAPTURE_CLOCK_SKEW_SECONDS",
+    "PredictionLedger",
+    "LedgerPrediction",
+    "LedgerWriteResult",
+    "LedgerConflictError",
+    "LEGACY_SETTLEMENT_REASON_CODES",
+    "MAX_NUMERIC_RAW_TIME_SECONDS",
+    "NUMERIC_OUTCOME_REASON_CODES",
+    "LedgerMonitoringStatus",
+    "NumericSettlementRevision",
+    "NumericSettlementRevisionResult",
+    "NumericOutcomeRevisionResult",
+    "SettlementResult",
+    "SettlementConflictError",
+    "ShadowFieldRequest",
+    "ShadowLiveStatus",
+    "ShadowReceipt",
+    "ShadowCalculationResult",
+    "ShadowPredictionService",
+    "RECEIPT_CORE_SCHEMA_VERSION",
+    "REQUEST_PROJECTION_SCHEMA_VERSION",
+    "ACTIVE_INPUT_SCHEMA_VERSION",
+    "IDENTITY_SCHEMA_VERSION",
+    "OBSERVATION_SCHEMA_VERSION",
+    "SHADOW_TARGET_SINGLE_ELAPSED",
+    "ACTOR_ATTESTATION_SCHEMA_VERSION",
+    "SHADOW_ATTESTATION_AUDIENCE",
+    "VerifiedActorAttestation",
+    "shadow_auth_configuration_status",
+    "sign_actor_attestation",
+    # Simulation
+    "run_monte_carlo_simulation",
+    "estimate_competitor_std_dev",
+    "audit_mark_sheet",
+    "quick_fairness_check",
+    # Visualization
+    "generate_simulation_summary",
+    "visualize_simulation_results",
+    # Fairness
+    "get_ai_assessment_of_handicaps",
+    "get_championship_race_analysis",
+    "simulate_and_assess_handicaps",
+    # LLM
+    "call_ollama",
+    "check_ollama_connection",
+    # Data loading
+    "load_woodchopping_xlsx",
+    "load_results_for_competitor",
+    # Database (Supabase)
+    "push_results",
+    "push_results_dicts",
+    "pull_results",
+    "push_competitors",
+    "pull_competitors",
+    "register_competitor",
+    "format_proam_results",
+    "record_prediction_residuals",
+    "get_competitor_bias",
+    "mirror_prediction_ledger",
+    # ML state (carve-out from controlled-write rule; STRATHMARK-internal)
+    "register_model_version",
+    "set_active_model",
+    "get_active_model_version",
+    "record_calibration",
+    "store_features",
+    "record_prediction",
+    "settle_prediction",
+    # MNEMEX (canonical archive client)
+    "is_mnemex_configured",
+    "pull_canonical_results",
+    "pull_canonical_competitors",
+    "register_competitor_in_mnemex",
+    # Sync (MNEMEX -> STRATHMARK Supabase)
+    "SyncResult",
+    "nightly_batch",
+    "strathex_finalization",
+    "manual_force_sync",
+    # Drift detection
+    "DriftReport",
+    "evaluate_drift",
+    "is_drifting",
+    # Scoring / accuracy
+    "score_prediction_accuracy",
+]
+
+__version__ = "2.0.0"

strathmark/analytics.py

@@ -0,0 +1,267 @@
+"""
+Analytics
+==========
+
+Backtesting, competitor profiling, and performance history analysis.
+
+Public functions:
+    backtest_predictions()       -- compare predicted vs actual times
+    profile_competitor()         -- summarise a single competitor's history
+    summarise_performance_history() -- tournament history summary for a field
+
+Source references (STRATHEX):
+    woodchopping/analytics/prediction_accuracy.py
+    woodchopping/analytics/competitor_profiling.py
+    woodchopping/analytics/performance_history.py
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+import pandas as pd
+
+from strathmark.predictor import (
+    CompetitorRecord,
+    WoodProfile,
+    get_best_prediction,
+)
+
+# ---------------------------------------------------------------------------
+# Backtesting
+# ---------------------------------------------------------------------------
+
+
+def backtest_predictions(
+    competitors: List[CompetitorRecord],
+    wood: WoodProfile,
+    event_code: str,
+    actuals: Dict[str, float],
+    ml_model=None,
+    results_df=None,
+    wood_df=None,
+) -> Dict[str, Any]:
+    """
+    Compare predicted times against actual race times.
+
+    Uses the full prediction cascade (get_best_prediction) when ml_model or
+    results_df are provided, otherwise falls back to baseline only.
+
+    Args:
+        competitors: List of CompetitorRecord objects.
+        wood: Wood profile used in the event.
+        event_code: 'SB' or 'UH'.
+        actuals: Dict mapping competitor name to actual cutting time (seconds).
+        ml_model: Optional trained MLModel for ML cascade level.
+        results_df: Optional historical results DataFrame.
+        wood_df: Optional wood properties DataFrame.
+
+    Returns:
+        Dict with keys:
+            'results'        -- List of per-competitor dicts
+            'mae'            -- Mean Absolute Error (seconds)
+            'rmse'           -- Root Mean Squared Error (seconds)
+            'bias'           -- Mean signed error (positive = predictions too high)
+            'within_3s_pct'  -- % of predictions within 3 seconds of actual
+    """
+    results = []
+    errors = []
+
+    for record in competitors:
+        if record.name not in actuals:
+            continue
+        actual = actuals[record.name]
+        pred_result = get_best_prediction(
+            record,
+            wood,
+            event_code,
+            wood_data_df=wood_df,
+            results_df=results_df,
+            ml_model=ml_model,
+        )
+        if pred_result is None:
+            continue
+        predicted = pred_result.value
+        error = predicted - actual
+        abs_error = abs(error)
+        errors.append(error)
+        results.append(
+            {
+                "name": record.name,
+                "predicted": predicted,
+                "actual": actual,
+                "error": error,
+                "abs_error": abs_error,
+                "confidence": pred_result.confidence,
+            }
+        )
+
+    if not errors:
+        return {
+            "results": results,
+            "mae": None,
+            "rmse": None,
+            "bias": None,
+            "within_3s_pct": None,
+        }
+
+    errors_arr = np.array(errors)
+    within_3s = sum(1 for e in errors if abs(e) <= 3.0)
+    return {
+        "results": results,
+        "mae": float(np.mean(np.abs(errors_arr))),
+        "rmse": float(np.sqrt(np.mean(errors_arr**2))),
+        "bias": float(np.mean(errors_arr)),
+        "within_3s_pct": within_3s / len(errors) * 100,
+    }
+
+
+def rolling_origin_analysis(
+    evidence: pd.DataFrame,
+    *,
+    target_start: date | None = None,
+    target_end_exclusive: date | None = None,
+    min_training_rows: int = 30,
+    minimum_global_rows: int = 100,
+    minimum_cohort_rows: int = 30,
+) -> Dict[str, Any]:
+    """Return an honest prior-only V2 rolling-origin accuracy summary.
+
+    ``claim_eligible`` is explicit so a small sample cannot accidentally be
+    presented as a validated accuracy or subgroup claim.
+    """
+
+    from strathmark.validation import chronological_backtest
+
+    report = chronological_backtest(
+        evidence,
+        target_start=target_start,
+        target_end_exclusive=target_end_exclusive,
+        min_training_rows=min_training_rows,
+    )
+    predictions = report.predictions
+    metrics: Dict[str, Any] = dict(report.metrics)
+    count = int(metrics.get("count", 0))
+    metrics["claim_eligible"] = count >= minimum_global_rows
+    metrics["sample_label"] = (
+        "global_claim_eligible" if metrics["claim_eligible"] else "insufficient_global_sample"
+    )
+    if not predictions.empty and {"core_lower", "core_upper"}.issubset(predictions.columns):
+        actual = predictions["actual_time"].to_numpy(dtype=float)
+        lower = predictions["core_lower"].to_numpy(dtype=float)
+        upper = predictions["core_upper"].to_numpy(dtype=float)
+        metrics["coverage_90"] = float(np.mean((lower <= actual) & (actual <= upper)))
+        metrics["mean_interval_width"] = float(np.mean(upper - lower))
+
+    cohorts: Dict[str, Dict[str, Any]] = {}
+    for name, values in report.cohort_metrics.items():
+        cohort = dict(values)
+        cohort_count = int(cohort.get("count", 0))
+        cohort["claim_eligible"] = cohort_count >= minimum_cohort_rows
+        cohort["sample_label"] = (
+            "cohort_claim_eligible" if cohort["claim_eligible"] else "insufficient_cohort_sample"
+        )
+        cohorts[name] = cohort
+    return {
+        "metrics": metrics,
+        "cohorts": cohorts,
+        "predictions": predictions,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Competitor profiling
+# ---------------------------------------------------------------------------
+
+
+def profile_competitor(
+    record: CompetitorRecord,
+    event_code: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Summarise a competitor's historical performance.
+
+    Args:
+        record: Competitor record with history populated.
+        event_code: Optional filter ('SB' or 'UH'). None analyses all events.
+
+    Returns:
+        Dict with:
+            'name', 'division', 'total_results', 'events_contested',
+            'mean_time', 'std_dev', 'best_time', 'worst_time',
+            'most_recent_date', 'activity_level'
+    """
+    history = record.history
+    if event_code is not None:
+        history = [r for r in history if r.event_code.upper() == event_code.upper()]
+
+    if not history:
+        return {
+            "name": record.name,
+            "division": record.division,
+            "total_results": 0,
+            "events_contested": [],
+            "mean_time": None,
+            "std_dev": None,
+            "best_time": None,
+            "worst_time": None,
+            "most_recent_date": None,
+            "activity_level": "inactive",
+        }
+
+    times = [r.time_seconds for r in history]
+    events = sorted({r.event_code for r in history})
+    dates = [r.result_date for r in history if r.result_date is not None]
+    most_recent = max(dates) if dates else None
+
+    today = date.today()
+    recent_count = sum(1 for d in dates if d is not None and (today - d).days <= 730)
+    if recent_count >= 5:
+        activity = "active"
+    elif recent_count >= 2:
+        activity = "moderate"
+    else:
+        activity = "inactive"
+
+    return {
+        "name": record.name,
+        "division": record.division,
+        "total_results": len(times),
+        "events_contested": events,
+        "mean_time": float(np.mean(times)),
+        "std_dev": float(np.std(times, ddof=1)) if len(times) >= 2 else None,
+        "best_time": float(min(times)),
+        "worst_time": float(max(times)),
+        "most_recent_date": most_recent,
+        "activity_level": activity,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Performance history summary
+# ---------------------------------------------------------------------------
+
+
+def summarise_performance_history(
+    competitors: List[CompetitorRecord],
+    event_code: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """
+    Return a ranked performance summary for a field of competitors.
+
+    Sorted by mean_time ascending (fastest first).
+
+    Args:
+        competitors: List of CompetitorRecord objects.
+        event_code: Optional filter.
+
+    Returns:
+        List of profile dicts (see profile_competitor()), sorted fastest first.
+    """
+    profiles = [profile_competitor(c, event_code) for c in competitors]
+    with_data = [p for p in profiles if p["mean_time"] is not None]
+    without_data = [p for p in profiles if p["mean_time"] is None]
+    with_data.sort(key=lambda p: p["mean_time"])
+    return with_data + without_data