crfrs 0.1.0

Generic structured-perceptron sequence labeler with Viterbi decoding
Documentation
//! Trained perceptron model — weights storage and Viterbi decoding.

use std::collections::HashMap;
use serde::{Deserialize, Serialize};
use crate::Result;

pub(crate) const START_LABEL: &str = "\x02START\x02";

#[inline]
pub(crate) fn emit_key(feature: &str, label: &str) -> String {
    format!("E\x00{}\x00{}", feature, label)
}

#[inline]
pub(crate) fn trans_key(prev: &str, curr: &str) -> String {
    format!("T\x00{}\x00{}", prev, curr)
}

/// A trained structured-perceptron model for sequence labeling.
///
/// Load from disk with [`PerceptronModel::load`] or obtain from
/// [`crate::trainer::PerceptronTrainer::finish`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PerceptronModel {
    /// All possible output labels.
    pub labels: Vec<String>,
    weights: HashMap<String, f64>,
}

impl PerceptronModel {
    // -----------------------------------------------------------------------
    // Scoring
    // -----------------------------------------------------------------------

    /// Computes the emission score for `features` predicting `label`.
    pub fn emit_score(&self, features: &[String], label: &str) -> f64 {
        features
            .iter()
            .map(|f| self.weights.get(&emit_key(f, label)).copied().unwrap_or(0.0))
            .sum()
    }

    /// Computes the transition score from `prev` to `curr`.
    pub fn trans_score(&self, prev: &str, curr: &str) -> f64 {
        self.weights
            .get(&trans_key(prev, curr))
            .copied()
            .unwrap_or(0.0)
    }

    // -----------------------------------------------------------------------
    // Viterbi decoding
    // -----------------------------------------------------------------------

    /// Returns the most likely label sequence for the given per-token feature lists.
    ///
    /// Each element of `seq_features` is the list of active feature strings
    /// for one token (e.g. `["word=رفتم", "suffix-1=م", "prev_word=به"]`).
    pub fn tag(&self, seq_features: &[Vec<String>]) -> Vec<String> {
        let n = seq_features.len();
        if n == 0 {
            return vec![];
        }
        let l = self.labels.len();

        let mut dp = vec![vec![f64::NEG_INFINITY; l]; n];
        let mut back = vec![vec![0usize; l]; n];

        for (i, label) in self.labels.iter().enumerate() {
            dp[0][i] = self.emit_score(&seq_features[0], label)
                + self.trans_score(START_LABEL, label);
        }

        for t in 1..n {
            for (i, label) in self.labels.iter().enumerate() {
                let emit = self.emit_score(&seq_features[t], label);
                let (best_prev, best_score) = (0..l)
                    .map(|pi| {
                        let s =
                            dp[t - 1][pi] + self.trans_score(&self.labels[pi], label) + emit;
                        (pi, s)
                    })
                    .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal))
                    .unwrap();
                dp[t][i] = best_score;
                back[t][i] = best_prev;
            }
        }

        let mut path = vec![0usize; n];
        path[n - 1] = (0..l)
            .max_by(|&a, &b| {
                dp[n - 1][a]
                    .partial_cmp(&dp[n - 1][b])
                    .unwrap_or(std::cmp::Ordering::Equal)
            })
            .unwrap_or(0);
        for t in (0..n - 1).rev() {
            path[t] = back[t + 1][path[t + 1]];
        }

        path.into_iter().map(|i| self.labels[i].clone()).collect()
    }

    // -----------------------------------------------------------------------
    // Persistence
    // -----------------------------------------------------------------------

    /// Saves the model to a JSON file at `path`.
    pub fn save(&self, path: &std::path::Path) -> Result<()> {
        let json = serde_json::to_string(self)?;
        std::fs::write(path, json)?;
        Ok(())
    }

    /// Loads a model previously saved with [`save`](Self::save).
    pub fn load(path: &std::path::Path) -> Result<Self> {
        let json = std::fs::read_to_string(path)?;
        Ok(serde_json::from_str(&json)?)
    }

    // -----------------------------------------------------------------------
    // Construction
    // -----------------------------------------------------------------------

    /// Creates a model directly from labels and weights.
    pub fn from_parts(labels: Vec<String>, weights: HashMap<String, f64>) -> Self {
        Self { labels, weights }
    }
}