atelier_quant 0.0.12

//! Model artifact schema for inter-arrival forecasting.
//!
//! The [`ModelArtifact`] struct is written by `inter_fit` (as JSON) and
//! consumed by `inter_serve` to initialise forecasting parameters.

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

// ── Top-level artifact ──────────────────────────────────────────────

/// Serialisable model artifact produced by `inter_fit`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelArtifact {
    /// Model family identifier, e.g. `"hawkes_exponential"`.
    pub model: String,

    /// Schema version (bump when fields change).
    pub version: u32,

    /// UTC timestamp when the fit completed.
    pub fitted_at: DateTime<Utc>,

    /// Fitted Hawkes parameters.
    pub parameters: HawkesParams,

    /// Goodness-of-fit diagnostics (optional).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub diagnostics: Option<Diagnostics>,

    /// Metadata about the input data.
    pub data: DataMeta,

    /// Poisson baseline comparison (optional).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub baseline: Option<PoissonBaseline>,
}

// ── Sub-structs ─────────────────────────────────────────────────────

/// Fitted Hawkes (μ, α, β) parameters.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HawkesParams {
    pub mu: f64,
    pub alpha: f64,
    pub beta: f64,
}

/// Goodness-of-fit diagnostics from the Hawkes MLE.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Diagnostics {
    pub branching_ratio: f64,
    pub log_likelihood: f64,
    pub aic: f64,
    pub bic: f64,
    pub converged: bool,
    pub iterations: usize,
    pub residuals_mean: f64,
    pub residuals_std: f64,
    pub compensator_ratio: f64,
}

/// Metadata about the data used for fitting.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DataMeta {
    /// File path (or glob) that was loaded.
    pub source: String,
    /// Number of events in the training set.
    pub n_events_train: usize,
    /// Number of events in the test set.
    pub n_events_test: usize,
    /// Total observation window in milliseconds.
    pub observation_window_ms: f64,
    /// Time resolution used for interarrivals.
    pub time_resolution: String,
}

/// Poisson baseline comparison for model selection.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PoissonBaseline {
    pub model: String,
    pub lambda: f64,
    pub aic: f64,
    /// Likelihood-ratio test statistic: 2·(ℓ_Hawkes − ℓ_Poisson).
    pub lr_statistic: f64,
    /// Whether H₀ (Poisson) is rejected at α = 0.05 (χ²(2)).
    pub lr_reject_h0: bool,
}