madi/

lib.rs

//! # madi(마디) — 순수 Rust 한국어 형태소 분석기
//!
//! 이 크레이트는 madi 의 **라이브러리 진입점**입니다. 사전과 언어 모델을 열어 [`Engine`] 을 만들고,
//! 스레드마다 [`EngineWorker`] 를 하나씩 받아 문장을 분석합니다. 명령줄 도구는 `madi-cli`,
//! Python 패키지는 `madipy`(`import madi`), 둘 다 이 크레이트 위에 얹혀 있습니다.
//!
//! - 품사는 세종 태그 체계([`Tag`]: NNG·VV·JKS …)이고, 분석 관행은 국립국어원 모두의 말뭉치
//!   형태 분석 지침을 따릅니다.
//! - 형태소 분석을 이용한 **문장 분리**(종결 부호가 없어도 종결 어미 뒤에서 끊음)를 함께 제공합니다.
//! - 소개 페이지 <https://p14jeffwest.github.io/madi-release/>, 모델·이용 조건
//!   <https://github.com/p14jeffwest/madi-release>.
//!
//! ## 모델 파일
//!
//! 사전·언어 모델은 크레이트에 들어 있지 않습니다. 위 저장소의 Release `models-kword5` 에서 받아 풉니다
//! (CC BY-SA 2.0 KR).
//!
//! | 파일 | 무엇 | 필요한 때 |
//! |---|---|---|
//! | `madi.dict` | 사전(어휘·활용형·복합어·연접표) | 항상 |
//! | `knlm.bin` | n-gram 언어 모델(KnLM) | 권장 — 없으면 ko-dic 연접표만으로 분석 |
//! | `model.nlm` | 신경망 언어 모델(NLM) | 기본 모드(feature `nlm`, 기본 켬) |
//! | `precise.tlm` | 정밀 모드 교사(작은 트랜스포머) | `precise` 를 줄 때만 |
//!
//! ## 빠른 시작
//!
//! ```no_run
//! use madi::{Engine, EngineConfig, NLM_MIX_WEIGHTS};
//!
//! // 기본 모드(사전 + KnLM + NLM). Python 패키지·CLI 의 기본값과 같다.
//! let cfg = EngineConfig {
//!     knlm: Some("models/knlm.bin".into()),
//!     nlm: Some("models/model.nlm".into()),
//!     lm_weight: NLM_MIX_WEIGHTS.0,
//!     nlm_weight: NLM_MIX_WEIGHTS.1,
//!     skip: madi::Skip::Off,            // 문서 정제·문장 버리기 없이 (라이브러리 용도)
//!     min_len: 0,
//!     ..EngineConfig::new("models/madi.dict")
//! };
//! let engine = Engine::load(&cfg)?;           // 1초 안팎, 한 번만 만들어 공유
//! println!("{}", engine.version());           // 0.2.1+decdb.r3p.f11.k838c.n15e6.s-
//!
//! let mut w = engine.worker();                // 스레드마다 하나
//! for t in w.analyze_sentence("아버지가 방에 들어가신다.") {
//!     print!("{}/{} ", t.form, t.tag.code());  // 아버지/NNG 가/JKS 방/NNG 에/JKB 들어가/VV 시/EP ㄴ다/EF ./SF
//! }
//! # Ok::<(), anyhow::Error>(())
//! ```
//!
//! ## 어느 함수를 쓰나
//!
//! | 하고 싶은 것 | 함수 | 돌려주는 것 |
//! |---|---|---|
//! | 문장 하나 분석 | [`EngineWorker::analyze_sentence`] | `Vec<Token>` (위치는 그 문장 안) |
//! | 여러 줄을 문장으로 나누고 각 문장 분석 | [`EngineWorker::sentences`] | `Vec<SentSpan>` (입력 전체 기준 위치·어절 번호) |
//! | 위 결과를 한 줄로 | [`EngineWorker::tokenize`] | `Vec<Morph>` |
//! | 문장 경계만 | [`EngineWorker::split_sentences`] | `Vec<String>` |
//! | 상위 n 개 후보와 점수 | [`EngineWorker::analyze_nbest`] | `Vec<(f32, Vec<Token>)>` |
//! | 특정 구간을 정해진 형태소로 | [`EngineWorker::analyze_pretokenized`] | `(Vec<Token>, Vec<bool>)` |
//! | 기사·문서를 말뭉치 만들 듯 처리(정제·보일러플레이트 제거) | [`EngineWorker::analyze_doc`] | `Vec<Sentence>` |
//! | 사전에 없는 말 보태기 | [`Engine::add_user_word`], [`Engine::load_user_dictionary`], [`EngineConfig::user`] | — |
//!
//! ## 모드
//!
//! | 모드 | 설정 | 특징 |
//! |---|---|---|
//! | 기본 | `knlm` + `nlm`, 가중 [`NLM_MIX_WEIGHTS`] | 대부분의 용도 |
//! | 정밀 | 기본 + `precise: Some("precise.tlm")` | 애매한 어절을 교사가 다시 고름. 약 10배 느림 |
//! | 가벼운 | `knlm` 만(`nlm: None`, `lm_weight: 1.0`) | 메모리 약 130 MB 적음, 정확도 조금 낮음. `default-features = false` 로 빌드 가능 |
//!
//! ## 스레드
//!
//! [`Engine`] 은 `Send + Sync` 라 `Arc` 로 여러 스레드가 공유하고, 각 스레드는 [`Engine::worker`] 로
//! 자기 작업 버퍼를 받습니다. 분석은 문장마다 독립이라 스레드 수와 관계없이 결과가 같습니다.
//!
//! ## 위치와 어절
//!
//! 모든 위치는 **글자(`char`) 단위** 반열린 구간 `[start, end)` 입니다(바이트가 아님). 축약된 활용형은
//! 여러 형태소가 같은 구간을 가리킵니다: "신다" → 시/EP(11..13) + ㄴ다/EF(11..13). [`Token::space_before`]
//! 가 참이면 그 형태소가 새 어절의 시작입니다.
//!
//! ## 판본 문자열
//!
//! [`Engine::version`] 은 `0.2.1+decdb.r3p.f11.k838c.n15e6.s-[.u…][.w…][.p…]` 꼴로, 크레이트 판본 뒤에
//! 사전·점수 가중 판·가지치기 문턱·KnLM·NLM·보일러플레이트 규칙의 해시가 붙습니다. 사용자 사전을 쓰면 `.u`,
//! 기본값과 다른 가중·옵션이 있으면 `.w`, 정밀 모드면 `.p` 가 더 붙습니다. 두 실행의 판본 문자열이 같으면
//! 같은 입력에 같은 출력을 냅니다.

/// 형태소 분석 결과를 쓰는 문장 분리 규칙 ([`EngineWorker::split_sentences`]·[`EngineWorker::sentences`] 가 쓴다).
pub mod split;
/// 문서 전처리: 보일러플레이트 규칙, 규칙 기반 문장 분리([`text::split_sentences`]), 토큰 줄 형식.
pub mod text;

/// 분석 옵션·품사·토큰 — `madi-core` 의 것을 그대로 내보낸다.
pub use madi_core::{Options, Tag, TagStyle, Token};
/// 정밀 모드 설정(τ 문턱·후보 수 등). [`EngineConfig::precise_opt`].
pub use madi_lm::precise::PreciseOpt;
/// 신문 기사 수집·정제 도구(`madi-news`). 보통의 분석에는 필요 없다.
pub use madi_news as news;

use anyhow::{bail, Context, Result};
use madi_core::{Analyzer, Dict, LangModel, Worker};
use madi_lm::tlm::TlmState;
use madi_lm::{KnLm, Tlm};
#[cfg(feature = "nlm")]
use madi_lm::{Mixed, Nlm};
use std::io::Read;
use std::path::{Path, PathBuf};
use text::SkipRules;

/// 문서 정제·문장 버리기 규칙(보일러플레이트 규칙)을 어디서 가져올지. [`EngineConfig::skip`].
///
/// 이 규칙은 [`EngineWorker::analyze_doc`] 에서만 쓰인다(신문 기사의 "무단 전재 금지" 같은 상투 문장 제거).
/// 문장을 그대로 분석하는 용도([`EngineWorker::analyze_sentence`]·[`sentences`](EngineWorker::sentences))라면
/// [`Skip::Off`] 로 두는 것이 판본 문자열도 짧고(`.s-`) 뜻도 분명하다.
#[derive(Debug, Clone, PartialEq)]
pub enum Skip {
    /// 빌드 때 넣은 기본 규칙(`boilerplate.txt`). [`EngineConfig::new`] 의 기본값
    Builtin,
    /// 같은 형식의 규칙 파일에서 읽는다
    File(PathBuf),
    /// 정제·문장 버리기를 하지 않는다 (라이브러리 용도 권장)
    Off,
}

/// [`Engine`] 을 만드는 설정. [`EngineConfig::new`] 로 사전 경로만 주고 나머지는 구조체 갱신 문법으로 바꾼다.
///
/// ```no_run
/// let cfg = madi::EngineConfig {
///     knlm: Some("models/knlm.bin".into()),
///     nlm: Some("models/model.nlm".into()),
///     lm_weight: madi::NLM_MIX_WEIGHTS.0,
///     nlm_weight: madi::NLM_MIX_WEIGHTS.1,
///     user: vec!["my_dict.tsv".into()],
///     ..madi::EngineConfig::new("models/madi.dict")
/// };
/// ```
///
/// 가중치 조합: KnLM 만 쓰면 `lm_weight` 1.0(기본), NLM 을 함께 쓰면 [`NLM_MIX_WEIGHTS`] (0.7, 0.3).
/// 그 밖의 값을 주면 판본 문자열에 `.w…` 가 붙어 기본 설정과 구별된다.
#[derive(Debug, Clone)]
pub struct EngineConfig {
    /// 사전 파일 `madi.dict` (필수)
    pub dict: PathBuf,
    /// n-gram 언어 모델 `knlm.bin`. 없으면 ko-dic 연접표만으로 분석한다(정확도 낮음, 시험용)
    pub knlm: Option<PathBuf>,
    /// 신경망 언어 모델 `model.nlm` (feature `nlm`, 기본 켬). 기본 모드에 필요하다. `madi nlm-pack` 으로 묶은 파일(권장)
    /// 또는 `model.i8`(어휘는 같은 디렉터리의 `vocab.tsv`). 로드 때 모델·어휘의 짝을 확인하고 어긋나면 오류
    pub nlm: Option<PathBuf>,
    /// KnLM 가중치. NLM 과 함께 쓸 때는 [`NLM_MIX_WEIGHTS`]`.0`(0.7), KnLM 만 쓸 때는 1.0([`EngineConfig::new`] 기본)
    pub lm_weight: f32,
    /// NLM 가중치. NLM 과 함께 쓸 때 [`NLM_MIX_WEIGHTS`]`.1`(0.3). `nlm` 이 없으면 쓰이지 않는다
    pub nlm_weight: f32,
    /// KnLM 미등록어 클래스 강도 (기본 0.0 = 모델 그대로). 보통 건드리지 않는다
    pub unk_scale: f32,
    /// 분석·출력 옵션([`Options`]): 복합어 펼치기, 2025년판 출력(`std_2025`), 탐색 설정 등. 기본값이 공개판 운영 설정이다
    pub options: Options,
    /// 문서 정제 규칙([`Skip`]). [`analyze_doc`](EngineWorker::analyze_doc) 에만 쓰인다. 기본 [`Skip::Builtin`]
    pub skip: Skip,
    /// [`analyze_doc`](EngineWorker::analyze_doc) 에서 이 글자 수보다 짧은 문장은 버린다 (기본 5; 규칙을 끄면 0 을 권장)
    pub min_len: usize,
    /// 한자 독음 자료 디렉터리(`hanja_char.csv`·`dueum.csv`·`hanja_word.csv`). 주면 한자 표기를 독음으로 분석하고
    /// [`Token::hanja`] 에 원 한자를 둔다. 없으면 한자는 SH 로 남는다
    pub hanja: Option<PathBuf>,
    /// 사용자 사전 파일들(탭 구분; 형식은 [`Engine::load_user_dictionary`]). 생성 때 읽어 두는 권장 경로
    pub user: Vec<PathBuf>,
    /// 정밀 모드 교사 `precise.tlm`. 주면 정밀 모드: 1차 분석에서 점수 차가 τ 안쪽인 어절만 교사가 다시 고른다(약 10배 느림)
    pub precise: Option<PathBuf>,
    /// 정밀 모드 설정([`PreciseOpt`]: τ 문턱·대안 수 등). 기본값이 공개판 설정
    pub precise_opt: PreciseOpt,
    /// 교사를 분석에는 쓰지 않고 [`EngineWorker::set_teacher_score`] 재채점에만 쓴다 (맞춤법 검사기용; 보통 false)
    pub teacher_only: bool,
}

impl EngineConfig {
    /// 사전 경로만 주고 나머지는 기본값으로: 언어 모델 없음, `lm_weight` 1.0, [`Skip::Builtin`], `min_len` 5,
    /// 사용자 사전·한자·정밀 모드 없음. 보통 구조체 갱신 문법으로 `knlm`·`nlm` 을 채워 쓴다
    pub fn new(dict: impl Into<PathBuf>) -> Self {
        Self {
            dict: dict.into(),
            knlm: None,
            nlm: None,
            lm_weight: 1.0,
            nlm_weight: 1.0,
            unk_scale: 0.0,
            options: Options::default(),
            skip: Skip::Builtin,
            min_len: 5,
            hanja: None,
            user: Vec::new(),
            precise: None,
            precise_opt: PreciseOpt::default(),
            teacher_only: false,
        }
    }
}

enum Inner {
    Conn(Analyzer<madi_core::ConnCost>),
    Kn(Analyzer<KnLm>),
    #[cfg(feature = "nlm")]
    Nl(Analyzer<Nlm>),
    #[cfg(feature = "nlm")]
    KnNl(Analyzer<Mixed<KnLm, Nlm>>),
}

/// 공유 분석기: 사전·언어 모델·옵션을 한 번 메모리에 올린 것. `Send + Sync`.
///
/// - [`Engine::load`] 로 만든다(1초 안팎, 기본 모드 약 470 MB). 한 프로세스에 하나를 만들어 `Arc` 로 공유한다.
/// - 분석은 [`Engine::worker`] 가 돌려주는 [`EngineWorker`] 로 한다 — 스레드마다 하나.
/// - 사용자 단어를 실행 중에 더하려면 `&mut Engine` 이 필요하다([`Engine::add_user_word`]). 더한 뒤 새로 만든
///   worker 부터 쓰인다.
///
/// ```no_run
/// use std::sync::Arc;
/// let engine = Arc::new(madi::Engine::load(&madi::EngineConfig::new("models/madi.dict"))?);
/// let handles: Vec<_> = (0..4).map(|i| {
///     let e = Arc::clone(&engine);
///     std::thread::spawn(move || {
///         let mut w = e.worker();
///         w.analyze_sentence(&format!("{}번째 스레드", i)).len()
///     })
/// }).collect();
/// # Ok::<(), anyhow::Error>(())
/// ```
pub struct Engine {
    inner: Inner,
    skip: Option<SkipRules>,
    min_len: usize,
    options: Options,
    version: String,
    /// 정밀 모드 교사 (읽기 전용 — 상태는 worker 마다)
    precise: Option<(Tlm, PreciseOpt)>,
    /// 교사는 재채점용으로만 (분석은 보통 경로)
    teacher_only: bool,
    /// 사용자 사전·한자 자료의 해시 (판본 문자열 `.u`; 실행 중 사용자 단어를 더하면 갱신, 0.2.0)
    user_h: Option<u64>,
}

enum WInner<'a> {
    Conn(Worker<'a, madi_core::ConnCost>),
    Kn(Worker<'a, KnLm>),
    #[cfg(feature = "nlm")]
    Nl(Worker<'a, Nlm>),
    #[cfg(feature = "nlm")]
    KnNl(Worker<'a, Mixed<KnLm, Nlm>>),
}

/// 스레드 하나의 분석 작업 버퍼. [`Engine::worker`] 로 받는다.
///
/// 격자·탐색 버퍼와 정밀 모드 교사 상태를 들고 있어 `Send` 가 아니다 — 스레드를 넘기지 말고 스레드마다 새로 받는다.
/// 모든 분석 메서드는 `&mut self` 를 받지만 엔진 자체는 바꾸지 않으므로 몇 번을 불러도 결과가 같다.
///
/// 주요 메서드: [`analyze_sentence`](Self::analyze_sentence)(문장 하나) · [`sentences`](Self::sentences)(문장 분리 + 위치) ·
/// [`tokenize`](Self::tokenize) · [`split_sentences`](Self::split_sentences) · [`analyze_nbest`](Self::analyze_nbest)(여러 후보) ·
/// [`analyze_pretokenized`](Self::analyze_pretokenized)(구간 지정) · [`analyze_doc`](Self::analyze_doc)(문서 정제 포함).
pub struct EngineWorker<'a> {
    w: WInner<'a>,
    e: &'a Engine,
    /// `analyze_query_nbest` 에만 쓰는 옵션 (`None` 이면 엔진 옵션). 맞춤법 검사기가 재채점 점수차를 예전 눈금(`legacy_score`)으로 재려고 쓴다 (10.13)
    nbest_opt: Option<Options>,
    /// 정밀 모드 교사 상태 (엔진에 교사가 있을 때만)
    tst: Option<TlmState>,
    /// `analyze_query_nbest` 의 점수를 교사 로그 확률로 (맞춤법 gate Teacher)
    teacher_score: bool,
}

/// [`EngineWorker::analyze_doc`] 이 돌려주는 문장 하나: 정제된 문장 글과 그 형태소들.
/// 토큰 위치는 **이 문장 안** 글자 위치다(입력 전체 기준이 필요하면 [`EngineWorker::sentences`]).
#[derive(Debug, Clone)]
pub struct Sentence {
    /// 정제·분리를 거친 문장 글
    pub text: String,
    /// 형태소들(위치는 `text` 안 글자 위치)
    pub tokens: Vec<Token>,
}

/// 위치가 붙은 형태소 — [`EngineWorker::sentences`]·[`EngineWorker::tokenize`] 의 결과 단위.
///
/// [`Token`] 에 "입력 안 어디에 있는가"를 더한 것이다. Python 패키지의 `Token` 이 이것에 해당한다.
#[derive(Debug, Clone)]
pub struct Morph {
    /// 형태소. `token.start`/`end` 는 **입력 전체** 기준 글자 위치(문장 안이 아님)
    pub token: Token,
    /// 문장 안 어절 번호 (0부터)
    pub word: u32,
    /// 입력 안 문장 번호 (0부터)
    pub sent: u32,
}

/// 문장 하나의 구간과 형태소 — [`EngineWorker::sentences`] 의 결과 단위.
///
/// `&input.chars().collect::<Vec<_>>()[start..end]` 가 `text` 와 같다 — 원문에서 그 문장을 그대로 잘라 낼 수 있다.
#[derive(Debug, Clone)]
pub struct SentSpan {
    /// 입력 전체 기준 글자 위치 (시작)
    pub start: usize,
    /// 입력 전체 기준 글자 위치 (끝, 포함하지 않음)
    pub end: usize,
    /// 문장 글 (원문 그대로)
    pub text: String,
    /// 형태소들 (입력 전체 기준 위치, 어절·문장 번호 포함)
    pub tokens: Vec<Morph>,
}

/// 미리 정한 구간 — [`EngineWorker::analyze_pretokenized`] 의 입력 (Kiwi 의 `pretokenized` 에 해당).
///
/// 입력 글자 구간 `[start, end)` 를 `form`·`tag` 인 형태소 하나로 분석하게 한다.
/// - `form` 이 `None` 이면 그 구간 원문 그대로.
/// - `tag` 가 `None` 이면 아무 품사나. 품사 코드는 **접두 일치**: `"NN"` 이면 NNG·NNP·NNB 가운데 하나.
///
/// 격자에 큰 보너스를 주는 방식이라 사전에 그런 (형태, 품사) 후보가 전혀 없으면 지키지 못할 수 있다 —
/// 그때 [`analyze_pretokenized`](EngineWorker::analyze_pretokenized) 가 돌려주는 `bool` 이 `false` 다.
#[derive(Debug, Clone)]
pub struct Pretoken {
    /// 입력 글자 위치 (시작)
    pub start: usize,
    /// 입력 글자 위치 (끝, 포함하지 않음)
    pub end: usize,
    /// 형태(사전 표기). `None` 이면 구간 원문
    pub form: Option<String>,
    /// 품사 코드(접두 일치). `None` 이면 제한 없음
    pub tag: Option<String>,
}

/// 원형(lemma): 용언(VV·VA·VX·VCP·VCN)은 어간 + "다"(들어가 → 들어가다), 그 밖은 형태 그대로.
///
/// madi 의 `form` 은 이미 사전 표기(활용·축약을 되돌린 꼴)라 원형이 따로 필요한 경우는 용언뿐이다.
pub fn lemma(t: &Token) -> String {
    match t.tag {
        Tag::VV | Tag::VA | Tag::VX | Tag::VCP | Tag::VCN => format!("{}다", t.form),
        _ => t.form.clone(),
    }
}

/// 바이트열의 64비트 해시(FNV 식, 8바이트 단위). 판본 문자열을 만드는 데 쓴다. `h` 는 시작값(이어서 해시할 때 앞 결과).
pub fn hash_bytes(h: u64, b: &[u8]) -> u64 {
    let mut h = h;
    let mut ch = b.chunks_exact(8);
    for c in &mut ch {
        h = (h ^ u64::from_le_bytes(c.try_into().unwrap())).wrapping_mul(0x100000001b3).rotate_left(23);
    }
    for &x in ch.remainder() {
        h = (h ^ x as u64).wrapping_mul(0x100000001b3);
    }
    h
}

/// 텍스트의 64비트 해시. BOM 을 떼고 줄끝을 LF 로 맞춘 뒤 재므로 Windows 에서 CRLF 로 풀린 파일도 같은 값이 난다.
/// 사용자 사전·규칙 파일의 판본 해시(`.u`·`.s`)에 쓴다.
pub fn hash_text(t: &str) -> u64 {
    let t = t.strip_prefix('\u{feff}').unwrap_or(t);
    if t.contains('\r') {
        hash_bytes(0xcbf29ce484222325, t.replace("\r\n", "\n").as_bytes())
    } else {
        hash_bytes(0xcbf29ce484222325, t.as_bytes())
    }
}

/// 파일 내용의 64비트 해시([`hash_bytes`] 와 같은 값을 1 MB 씩 읽어 가며). 사전·모델 파일의 판본 해시에 쓴다.
pub fn hash_file(path: &Path) -> Result<u64> {
    let mut f = std::fs::File::open(path).with_context(|| path.display().to_string())?;
    let mut buf = vec![0u8; 1 << 20];
    let mut h = 0xcbf29ce484222325u64;
    let mut carry: Vec<u8> = Vec::new();
    loop {
        let n = f.read(&mut buf)?;
        if n == 0 {
            break;
        }
        // 8바이트 정렬을 유지하려고 남은 조각을 다음 읽기와 잇는다
        carry.extend_from_slice(&buf[..n]);
        let k = carry.len() / 8 * 8;
        h = hash_bytes(h, &carry[..k]);
        carry.drain(..k);
    }
    Ok(hash_bytes(h, &carry))
}

/// [`hash_file`] 과 같은 값을 메모리 버퍼에서 낸다 — `words` 는 8바이트 단위로 담은 내용, `len` 은 실제 바이트 수.
/// [`Engine::from_memory`](WASM 등 파일이 없는 환경) 가 쓴다. 리틀 엔디언 가정(x86·wasm32).
pub fn hash_words(words: &[u64], len: usize) -> u64 {
    let full = len / 8;
    let mut h = 0xcbf29ce484222325u64;
    for &w in &words[..full] {
        h = (h ^ u64::from_le(w)).wrapping_mul(0x100000001b3).rotate_left(23);
    }
    if len % 8 != 0 {
        let b = words[full].to_le_bytes();
        for &x in &b[..len % 8] {
            h = (h ^ x as u64).wrapping_mul(0x100000001b3);
        }
    }
    h
}

fn short(h: u64) -> String {
    format!("{:04x}", (h ^ (h >> 16) ^ (h >> 32) ^ (h >> 48)) & 0xffff)
}

#[cfg(feature = "nlm")]
fn load_nlm(p: &Path, weight: f32, dict: &Dict) -> Result<Nlm> {
    let mut n = madi_lm::nlm::load_checked(p).with_context(|| format!("load {}", p.display()))?;
    n.weight = weight;
    n.attach(dict);
    Ok(n)
}

/// `Inner` 의 분석기에 같은 일을 한다 (변형 넷)
macro_rules! with_an {
    ($inner:expr, $an:ident => $body:expr) => {
        match &mut $inner {
            Inner::Conn($an) => $body,
            Inner::Kn($an) => $body,
            #[cfg(feature = "nlm")]
            Inner::Nl($an) => $body,
            #[cfg(feature = "nlm")]
            Inner::KnNl($an) => $body,
        }
    };
}

/// 사용자 사전·한자 자료 파일의 해시 (판본 문자열 `.u`). 둘 다 없으면 None
fn user_hash(cfg: &EngineConfig) -> Result<Option<u64>> {
    if cfg.hanja.is_none() && cfg.user.is_empty() {
        return Ok(None);
    }
    let mut h = 0u64;
    if let Some(d) = &cfg.hanja {
        for f in ["hanja_char.csv", "dueum.csv", "hanja_word.csv"] {
            let t = std::fs::read_to_string(d.join(f)).with_context(|| d.join(f).display().to_string())?;
            h = h.rotate_left(5) ^ hash_text(&t);
        }
    }
    for p in &cfg.user {
        let t = std::fs::read_to_string(p).with_context(|| p.display().to_string())?;
        h = h.rotate_left(5) ^ hash_text(&t);
    }
    Ok(Some(h))
}

fn prepare<L: LangModel>(mut an: Analyzer<L>, cfg: &EngineConfig) -> Result<Analyzer<L>> {
    if let Some(dir) = &cfg.hanja {
        an.load_hanja(dir).with_context(|| format!("load hanja from {}", dir.display()))?;
    }
    for p in &cfg.user {
        let bad = an.load_user_dict(p).with_context(|| format!("read {}", p.display()))?;
        if let Some((ln, line)) = bad.first() {
            bail!("{}:{}: 사용자 사전 줄 형식 오류: {}", p.display(), ln, line);
        }
    }
    Ok(an)
}

impl Engine {
    /// 설정대로 사전·언어 모델·(있으면) 정밀 모드 교사·사용자 사전을 열어 엔진을 만든다. 보통의 진입점.
    ///
    /// 파일이 없거나 사전과 모델의 짝이 맞지 않거나 사용자 사전 줄 형식이 틀리면 오류를 돌려준다.
    /// feature `nlm` 없이 빌드했는데 `cfg.nlm` 이 있으면 오류.
    pub fn load(cfg: &EngineConfig) -> Result<Self> {
        let dict = Dict::open(&cfg.dict).with_context(|| format!("open {}", cfg.dict.display()))?;
        Self::from_dict(dict, cfg)
    }

    /// 이미 연 [`Dict`] 로 엔진을 만든다([`load`](Self::load) 의 뒷부분). 사전을 미리 고쳐 넘길 때(CLI 의 실험용) 쓰며,
    /// 판본 문자열의 사전 해시는 여전히 `cfg.dict` 파일로 낸다. 보통은 [`load`](Self::load) 를 쓴다.
    pub fn from_dict(dict: Dict, cfg: &EngineConfig) -> Result<Self> {
        #[cfg(not(feature = "nlm"))]
        if cfg.nlm.is_some() {
            bail!("this madi was built without feature \"nlm\"");
        }
        let knlm = match &cfg.knlm {
            Some(p) => {
                let mut lm = KnLm::load(p).with_context(|| format!("load {}", p.display()))?;
                lm.weight = cfg.lm_weight;
                lm.unk_scale = cfg.unk_scale;
                lm.attach(&dict);
                Some(lm)
            }
            None => None,
        };
        let inner = match (knlm, &cfg.nlm) {
            (None, None) => Inner::Conn(prepare(Analyzer::with_lm(dict, madi_core::ConnCost), cfg)?),
            (Some(lm), None) => Inner::Kn(prepare(Analyzer::with_lm(dict, lm), cfg)?),
            #[cfg(feature = "nlm")]
            (None, Some(np)) => {
                let nlm = load_nlm(np, cfg.nlm_weight, &dict)?;
                Inner::Nl(prepare(Analyzer::with_lm(dict, nlm), cfg)?)
            }
            #[cfg(feature = "nlm")]
            (Some(lm), Some(np)) => {
                let mut nlm = load_nlm(np, cfg.nlm_weight, &dict)?;
                nlm.weight *= cfg.options.search.nlm_scale; // 10.12 기본 가중의 NLM 몫 (보간일 때만)
                Inner::KnNl(prepare(Analyzer::with_lm(dict, Mixed { a: lm, b: nlm }), cfg)?)
            }
            #[cfg(not(feature = "nlm"))]
            (_, Some(_)) => unreachable!(),
        };
        let (skip, skip_text) = match &cfg.skip {
            Skip::Builtin => (Some(SkipRules::builtin()), Some(text::BUILTIN_SKIP.to_string())),
            Skip::File(p) => {
                let t = std::fs::read_to_string(p).with_context(|| p.display().to_string())?;
                (Some(SkipRules::parse(&t, &p.display().to_string())?), Some(t))
            }
            Skip::Off => (None, None),
        };
        let version = Self::make_version(cfg, skip_text.as_deref())?;
        let precise = match &cfg.precise {
            Some(p) => Some((Tlm::load(p).with_context(|| format!("load {} (정밀 모드 교사)", p.display()))?, cfg.precise_opt)),
            None => None,
        };
        Ok(Self { inner, skip, min_len: cfg.min_len, options: cfg.options.clone(), version, precise, teacher_only: cfg.teacher_only, user_h: user_hash(cfg)? })
    }

    /// 파일 없이 메모리에 있는 사전·KnLM 바이트로 엔진을 만든다 (WASM 처럼 파일 시스템이 없는 환경용).
    ///
    /// `dict_words`/`knlm` 은 파일 내용을 8바이트 단위 `Vec<u64>` 에 담은 것과 실제 바이트 수. `cfg` 의 파일 경로 항목
    /// (`dict`·`knlm`·`nlm`·`precise`·`user`·`hanja`)은 쓰지 않고 가중치·옵션·`skip`·`min_len` 만 읽는다.
    /// NLM·정밀 모드·사용자 사전·한자 자료·[`Skip::File`] 은 아직 지원하지 않는다(오류).
    /// 판본 문자열은 같은 파일을 경로로 열 때와 같다.
    pub fn from_memory(dict_words: Vec<u64>, dict_len: usize, knlm: Option<(Vec<u64>, usize)>, cfg: &EngineConfig) -> Result<Self> {
        if cfg.nlm.is_some() || cfg.precise.is_some() || !cfg.user.is_empty() || cfg.hanja.is_some() {
            bail!("from_memory: NLM·정밀 모드·사용자 사전·한자 자료는 아직 지원하지 않는다");
        }
        let mut v = format!("{}+d{}", env!("CARGO_PKG_VERSION"), short(hash_words(&dict_words, dict_len)));
        v += &rev_tag(cfg);
        let kh = knlm.as_ref().map(|(w, n)| hash_words(w, *n));
        let dict = Dict::from_words(dict_words, dict_len).context("사전")?;
        let lm = match knlm {
            Some((w, n)) => {
                let mut lm = KnLm::from_raw(madi_core::dict::RawSections::from_words(w, n).context("KnLM")?)?;
                lm.weight = cfg.lm_weight;
                lm.unk_scale = cfg.unk_scale;
                lm.attach(&dict);
                Some(lm)
            }
            None => None,
        };
        match kh {
            Some(h) => v += &format!(".k{}", short(h)),
            None => v += ".k-",
        }
        v += ".n-";
        let skip = match &cfg.skip {
            Skip::Builtin => {
                v += &format!(".s{}", short(hash_text(text::BUILTIN_SKIP)));
                Some(SkipRules::builtin())
            }
            Skip::File(_) => bail!("from_memory: Skip::File 은 쓸 수 없다 (Builtin 또는 Off)"),
            Skip::Off => {
                v += ".s-";
                None
            }
        };
        v += &knob_tag(cfg);
        let inner = match lm {
            None => Inner::Conn(Analyzer::with_lm(dict, madi_core::ConnCost)),
            Some(lm) => Inner::Kn(Analyzer::with_lm(dict, lm)),
        };
        Ok(Self { inner, skip, min_len: cfg.min_len, options: cfg.options.clone(), version: v, precise: None, teacher_only: false, user_h: None })
    }

    /// `0.1.0-kword1+d3f2a.k91c0.n-.s7e1b[.u…][.w…]`: 크레이트 버전 + 사전·KnLM·NLM·보일러플레이트 규칙 해시 앞 4자리.
    /// 사용자 사전·한자 자료를 쓰면 `u`, 기본이 아닌 가중치·옵션이면 `w` 가 붙는다
    fn make_version(cfg: &EngineConfig, skip_text: Option<&str>) -> Result<String> {
        let mut v = format!("{}+d{}", env!("CARGO_PKG_VERSION"), short(hash_file(&cfg.dict)?));
        // 기본 점수 가중 판본 (10.12): 기본값 자체가 바뀐 것은 아래 `.w` 로 드러나지 않으므로
        v += &rev_tag(cfg);
        match &cfg.knlm {
            Some(p) => v += &format!(".k{}", short(hash_file(p)?)),
            None => v += ".k-",
        }
        match &cfg.nlm {
            Some(p) => {
                // 묶음 파일이면 그 파일만, 아니면 같은 디렉터리의 vocab.tsv 도
                #[allow(unused_mut)]
                let mut h = hash_file(p)?;
                #[cfg(feature = "nlm")]
                if !Nlm::is_packed(p) {
                    h ^= hash_file(&p.parent().unwrap_or(Path::new(".")).join("vocab.tsv"))?.rotate_left(7);
                }
                v += &format!(".n{}", short(h));
            }
            None => v += ".n-",
        }
        match skip_text {
            Some(t) => v += &format!(".s{}", short(hash_text(t))),
            None => v += ".s-",
        }
        if let Some(h) = user_hash(cfg)? {
            v += &format!(".u{}", short(h));
        }
        // 가중치·옵션이 기본과 다르면 그 차이도 버전에 (같은 파일이라도 결과가 달라지므로)
        v += &knob_tag(cfg);
        // 정밀 모드 (없으면 아무것도 붙지 않아 예전 버전 문자열 그대로)
        if let Some(p) = &cfg.precise {
            let mut h = hash_file(p)?;
            let po = cfg.precise_opt.diff_default();
            if !po.is_empty() {
                h ^= hash_bytes(11, po.join(" ").as_bytes());
            }
            v += &format!(".p{}", short(h));
        }
        Ok(v)
    }

    /// 판본 문자열: `0.2.1+decdb.r3p.f11.k838c.n15e6.s-[.u…][.w…][.p…]`.
    ///
    /// 크레이트 판본 + 사전(`d`)·점수 가중 판(`r`)·전후향 가지치기 문턱(`f`)·KnLM(`k`)·NLM(`n`)·정제 규칙(`s`) 해시.
    /// 사용자 사전이 있으면 `.u`, 기본값과 다른 가중·옵션이 있으면 `.w`, 정밀 모드면 `.p`. 같은 문자열이면 같은 출력을
    /// 보장하므로 결과를 저장할 때 함께 적어 두면 좋다(없는 모델은 `-`: `.k-`, `.n-`).
    pub fn version(&self) -> &str {
        &self.version
    }

    /// 사용자 단어를 더한다 — 사전 파일의 `형태 ⇥ 품사 [⇥ 보너스]` 줄과 같다. 보너스(`score`)는 로그 확률 눈금의
    /// 가산점으로 기본 3.0; 문맥이 강하게 다른 쪽을 가리키면 질 수 있으니 그때는 올린다.
    ///
    /// 용언은 어간만 넣는다(`달리`, `VV` — `달리다`·`달려` 가 아님). 이미 만든 [`EngineWorker`] 에는 반영되지 않고
    /// 그 뒤 [`worker`](Self::worker) 로 받은 것부터 쓰인다. 판본 문자열의 `.u` 가 바뀐다.
    pub fn add_user_word(&mut self, form: &str, tag: Tag, score: Option<f32>) {
        with_an!(self.inner, an => an.add_user_word(form, tag, score));
        self.bump_user(&format!("{form}\t{}\t{score:?}", tag.code()));
    }

    /// 기분석 항목을 더한다 — 표면형 `surface` 가 나오면 `morphs` 열로 분석하는 후보를 추가한다. 사전 파일의
    /// `표면형 ⇥ = ⇥ 형태/품사 형태/품사 …` 줄과 같다. 보너스 기본 6.0. 역시 다음 worker 부터 쓰인다.
    ///
    /// ```no_run
    /// # let mut engine = madi::Engine::load(&madi::EngineConfig::new("models/madi.dict"))?;
    /// engine.add_pre_analyzed_word("달라고", &[("달".into(), madi::Tag::VX), ("라고".into(), madi::Tag::EC)], None);
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn add_pre_analyzed_word(&mut self, surface: &str, morphs: &[(String, Tag)], score: Option<f32>) {
        with_an!(self.inner, an => an.add_preanalysis(surface, morphs, score));
        let ms: Vec<String> = morphs.iter().map(|(f, t)| format!("{f}/{}", t.code())).collect();
        self.bump_user(&format!("{surface}\t=\t{}\t{score:?}", ms.join(" ")));
    }

    /// 사용자 사전 파일을 읽어 더한다. 잘못된 줄이 있으면 그 줄 번호와 함께 오류. 다음 worker 부터 쓰인다.
    ///
    /// 파일 형식(탭 구분, `#` 뒤는 주석, 품사는 코드·한글 축약 어느 쪽이든):
    /// ```text
    /// 케데헌	NNP                        # 단어 ⇥ 품사 [⇥ 보너스]            (기본 3.0)
    /// 먹깨비	고유명	5
    /// 달라고	=	달/VX 라고/EC             # 표면형 ⇥ = ⇥ 형태/품사 …           기분석 (기본 6.0)
    /// 운주사	운주사/NNG	=>	운주사/NNP    # 표면형 ⇥ 틀린 분석 ⇥ => ⇥ 맞는 분석   분석 뒤 고치기(문맥 안 봄)
    /// ```
    /// 단어·기분석 줄은 후보를 더하는 것이라 문맥에 따라 질 수 있고, `=>` 줄은 결과를 무조건 바꾼다.
    /// 엔진을 만들 때 읽는 [`EngineConfig::user`] 가 권장 경로다.
    pub fn load_user_dictionary(&mut self, path: &Path) -> Result<()> {
        let t = std::fs::read_to_string(path).with_context(|| path.display().to_string())?;
        let bad = with_an!(self.inner, an => an.load_user_dict(path)).with_context(|| format!("read {}", path.display()))?;
        if let Some((ln, line)) = bad.first() {
            bail!("{}:{}: 사용자 사전 줄 형식 오류: {}", path.display(), ln, line);
        }
        self.bump_user(&t);
        Ok(())
    }

    /// 판본 문자열의 `.u` 를 갱신 (`…s0968[.uXXXX][.w…][.p…]`)
    fn bump_user(&mut self, text: &str) {
        let h = self.user_h.unwrap_or(0).rotate_left(5) ^ hash_text(text);
        self.user_h = Some(h);
        let (head, rest) = self.version.split_once('+').map(|(a, b)| (a.to_string(), b.to_string())).unwrap_or_default();
        let mut segs: Vec<String> = rest.split('.').filter(|x| !x.starts_with('u')).map(String::from).collect();
        let at = segs.iter().position(|x| x.starts_with('s')).map(|i| i + 1).unwrap_or(segs.len());
        segs.insert(at, format!("u{}", short(h)));
        self.version = format!("{head}+{}", segs.join("."));
    }

    /// 엔진이 쓰는 분석 옵션([`EngineConfig::options`] 의 사본)
    pub fn options(&self) -> &Options {
        &self.options
    }

    /// 정밀 모드 교사를 실었는가(`precise` 를 주고 만들었는가)
    pub fn is_precise(&self) -> bool {
        self.precise.is_some()
    }

    /// 언어 모델 구성 이름: `"conn"`(연접표만) · `"knlm"`(가벼운 모드) · `"nlm"` · `"knlm+nlm"`(기본 모드)
    pub fn lm_name(&self) -> &'static str {
        match &self.inner {
            Inner::Conn(_) => "conn",
            Inner::Kn(_) => "knlm",
            #[cfg(feature = "nlm")]
            Inner::Nl(_) => "nlm",
            #[cfg(feature = "nlm")]
            Inner::KnNl(_) => "knlm+nlm",
        }
    }

    /// 열어 둔 사전(어휘 조회·사전 통계가 필요할 때)
    pub fn dict(&self) -> &Dict {
        match &self.inner {
            Inner::Conn(a) => &a.dict,
            Inner::Kn(a) => &a.dict,
            #[cfg(feature = "nlm")]
            Inner::Nl(a) => &a.dict,
            #[cfg(feature = "nlm")]
            Inner::KnNl(a) => &a.dict,
        }
    }

    /// 문서 정제 규칙 수 ([`Skip::Off`] 면 0)
    pub fn n_skip_rules(&self) -> usize {
        self.skip.as_ref().map(|r| r.len()).unwrap_or(0)
    }

    /// 분석 작업 버퍼를 하나 만든다. 스레드마다 하나씩 받아 그 스레드 안에서만 쓴다. 만드는 비용은 작다(격자 버퍼 할당 정도).
    pub fn worker(&self) -> EngineWorker<'_> {
        let w = match &self.inner {
            Inner::Conn(a) => WInner::Conn(a.worker()),
            Inner::Kn(a) => WInner::Kn(a.worker()),
            #[cfg(feature = "nlm")]
            Inner::Nl(a) => WInner::Nl(a.worker()),
            #[cfg(feature = "nlm")]
            Inner::KnNl(a) => WInner::KnNl(a.worker()),
        };
        let tst = self.precise.as_ref().map(|(t, _)| t.new_state());
        EngineWorker { w, e: self, nbest_opt: None, tst, teacher_score: false }
    }
}

/// [`EngineWorker::analyze_doc_full`] 의 결과: 남은 문장들과 버린 문장 수.
pub struct DocResult {
    /// 분석된 문장들
    pub sentences: Vec<Sentence>,
    /// 정제 규칙([`Skip`])으로 버린 문장 수
    pub skipped: usize,
    /// [`EngineConfig::min_len`] 보다 짧아 버린 문장 수
    pub short: usize,
}

impl EngineWorker<'_> {
    fn run(&mut self, text: &str) -> Vec<Token> {
        let opt = &self.e.options;
        if let (Some((tlm, po)), Some(st), false) = (&self.e.precise, &mut self.tst, self.e.teacher_only) {
            // 정밀 모드 (CLI `best_tokens` 와 같음): 국소 대안(τ 문턱) → 교사로 다시 고르기
            let r = match &mut self.w {
                WInner::Conn(w) => w.analyze_alts_local_gated(text, opt, po.cand_margin, po.max_alts, Some(po.tau)),
                WInner::Kn(w) => w.analyze_alts_local_gated(text, opt, po.cand_margin, po.max_alts, Some(po.tau)),
                #[cfg(feature = "nlm")]
                WInner::Nl(w) => w.analyze_alts_local_gated(text, opt, po.cand_margin, po.max_alts, Some(po.tau)),
                #[cfg(feature = "nlm")]
                WInner::KnNl(w) => w.analyze_alts_local_gated(text, opt, po.cand_margin, po.max_alts, Some(po.tau)),
            };
            let mut stats = Default::default();
            return madi_lm::precise::apply(tlm, st, &r, po, &mut stats);
        }
        match &mut self.w {
            WInner::Conn(w) => w.analyze(text, opt),
            WInner::Kn(w) => w.analyze(text, opt),
            #[cfg(feature = "nlm")]
            WInner::Nl(w) => w.analyze(text, opt),
            #[cfg(feature = "nlm")]
            WInner::KnNl(w) => w.analyze(text, opt),
        }
    }

    /// 문서(기사 본문 등 여러 줄)를 말뭉치 만들 듯 처리한다: 정제 → 문장 분리 → 상투 문장 버리기 → 짧은 문장 버리기 → 분석.
    ///
    /// `madi corpus` 명령이 쓰는 것과 같은 경로다. 정제 규칙은 [`EngineConfig::skip`], 길이 문턱은 [`EngineConfig::min_len`].
    /// 문장 분리는 규칙 기반([`text::split_sentences`]: 종결 부호 뒤)이며, 돌려주는 토큰 위치는 각 문장 안 위치다.
    /// 입력을 그대로 두고 위치까지 받고 싶으면 [`sentences`](Self::sentences) 를 쓴다.
    pub fn analyze_doc(&mut self, text: &str) -> Vec<Sentence> {
        self.analyze_doc_full(text).sentences
    }

    /// [`analyze_doc`](Self::analyze_doc) 과 같되 버린 문장 수까지 돌려준다
    pub fn analyze_doc_full(&mut self, text: &str) -> DocResult {
        let e = self.e;
        let cleaned;
        let text = match &e.skip {
            Some(r) => {
                cleaned = r.clean(text);
                cleaned.as_str()
            }
            None => text,
        };
        let mut ss = text::split_sentences(text);
        let mut skipped = 0;
        if let Some(r) = &e.skip {
            let before = ss.len();
            ss.retain(|s| !r.skip(s));
            skipped = before - ss.len();
        }
        let mut short = 0;
        let mut sentences = Vec::with_capacity(ss.len());
        for s in ss {
            if s.chars().count() < e.min_len {
                short += 1;
                continue;
            }
            let tokens = self.run(&s);
            sentences.push(Sentence { text: s, tokens });
        }
        DocResult { sentences, skipped, short }
    }

    /// 형태소 분석을 이용한 문장 분리. 문장 글만 돌려준다.
    ///
    /// 줄마다 분석해 **종결 부호 뒤**와 **종결 어미(EF)로 끝난 어절 뒤**에서 끊으므로 마침표 없이 이어 쓴 글
    /// (메신저·댓글·구어)도 나눈다. 괄호·따옴표 안에서는 끊지 않고, 줄바꿈은 늘 경계다. 빈 줄은 건너뛴다.
    /// 규칙은 [`split`] 모듈에 있다. 모델 없이 종결 부호만 보는 가벼운 분리는 [`text::split_sentences`].
    ///
    /// ```no_run
    /// # let engine = madi::Engine::load(&madi::EngineConfig::new("models/madi.dict"))?;
    /// let mut w = engine.worker();
    /// assert_eq!(w.split_sentences("밥 먹었니 나는 먹었어"), ["밥 먹었니", "나는 먹었어"]);
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn split_sentences(&mut self, text: &str) -> Vec<String> {
        let mut out = Vec::new();
        for line in text.lines() {
            if line.trim().is_empty() {
                continue;
            }
            let toks = self.run(line);
            let chars: Vec<char> = line.chars().collect();
            for (s, e) in split::split_line(line, &toks) {
                out.push(chars[s..e].iter().collect());
            }
        }
        out
    }

    /// 입력(여러 줄 가능)을 문장으로 나누고, 문장마다 구간과 위치가 붙은 형태소를 돌려준다. **라이브러리 용도의 기본 진입점.**
    ///
    /// - 정제·버리기 없이 입력을 그대로 다룬다. 문장 경계는 [`split_sentences`](Self::split_sentences) 와 같다.
    /// - [`SentSpan::start`]/`end` 와 각 [`Morph`] 의 `token.start`/`end` 는 **입력 전체** 기준 글자 위치라
    ///   원문에서 바로 잘라 낼 수 있다. `word` 는 문장 안 어절 번호, `sent` 는 문장 번호.
    /// - 빈 줄은 건너뛴다(문장 번호에도 들어가지 않는다).
    ///
    /// ```no_run
    /// # let engine = madi::Engine::load(&madi::EngineConfig::new("models/madi.dict"))?;
    /// let mut w = engine.worker();
    /// let input = "비가 온다. 우산을 챙겨라";
    /// let chars: Vec<char> = input.chars().collect();
    /// for s in w.sentences(input) {
    ///     assert_eq!(s.text, chars[s.start..s.end].iter().collect::<String>());
    ///     for m in &s.tokens {
    ///         println!("{}/{} 어절{} {}..{}", m.token.form, m.token.tag.ko(), m.word, m.token.start, m.token.end);
    ///     }
    /// }
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn sentences(&mut self, text: &str) -> Vec<SentSpan> {
        let mut out = Vec::new();
        let mut off = 0usize; // 줄 시작의 char 위치
        for raw in text.split('\n') {
            let line = raw.strip_suffix('\r').unwrap_or(raw);
            let n_line = raw.chars().count() + 1;
            if !line.trim().is_empty() {
                let toks = self.run(line);
                let chars: Vec<char> = line.chars().collect();
                for (s, e) in split::split_line(line, &toks) {
                    let sent = out.len() as u32;
                    let mut word = 0u32;
                    let mut ms = Vec::new();
                    for t in toks.iter().filter(|t| t.start >= s && t.end <= e) {
                        if !ms.is_empty() && t.space_before {
                            word += 1;
                        }
                        let mut t = t.clone();
                        t.start += off;
                        t.end += off;
                        ms.push(Morph { token: t, word, sent });
                    }
                    out.push(SentSpan { start: off + s, end: off + e, text: chars[s..e].iter().collect(), tokens: ms });
                }
            }
            off += n_line;
        }
        out
    }

    /// [`sentences`](Self::sentences) 의 형태소를 문장 구분 없이 한 줄로 이어 붙인 것. 문장 번호는 `Morph::sent` 에 남아 있다.
    /// Python 패키지의 `tokenize` 가 이것이다.
    pub fn tokenize(&mut self, text: &str) -> Vec<Morph> {
        self.sentences(text).into_iter().flat_map(|s| s.tokens).collect()
    }

    /// 문장 하나의 상위 `n` 개 분석 후보를 `(점수, 형태소들)` 로, 좋은 것부터. 애매한 문장이 어떻게 갈렸는지 보거나
    /// 뒤에서 다른 정보로 후보 가운데 고를 때 쓴다.
    ///
    /// - 점수는 탐색의 로그 확률 합이라 클수록(0 에 가까울수록) 좋다. 언어 모델 구성마다 눈금이 달라 다른 엔진끼리
    ///   비교할 값은 아니다.
    /// - 1번 후보는 늘 [`analyze_sentence`](Self::analyze_sentence) 와 같다(정밀 모드면 교사가 고른 것이고 그때 점수는
    ///   격자 1위의 값). 후보가 `n` 보다 적을 수 있다.
    /// - 입력 전체를 한 문장으로 본다(문장을 나누지 않는다). `n > 1` 이면 2단 채점 문턱을 꺼서 1-best 보다 느리다.
    ///
    /// ```no_run
    /// # let engine = madi::Engine::load(&madi::EngineConfig::new("models/madi.dict"))?;
    /// let mut w = engine.worker();
    /// for (score, toks) in w.analyze_nbest("감기는 무서운 병이다", 3) {
    ///     println!("{score:.2} {}", madi::format_tokens(&toks));
    /// }
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn analyze_nbest(&mut self, text: &str, n: usize) -> Vec<(f32, Vec<Token>)> {
        let n = n.max(1);
        // 2단 채점 문턱(nlm_gate)은 노드마다 1위 근처 경로만 남겨 2위 이하 후보를 지운다 → 후보가 여럿일 때는 끈다.
        // 1번 후보는 아래에서 늘 `run`(문턱 켬) 결과로 맞추므로 1-best 출력은 바뀌지 않는다
        let mut o2 = self.e.options.clone();
        if n > 1 {
            o2.search.nlm_gate = 0.0;
        }
        let opt = &o2;
        let mut r = match &mut self.w {
            WInner::Conn(w) => w.analyze_nbest(text, n, opt),
            WInner::Kn(w) => w.analyze_nbest(text, n, opt),
            #[cfg(feature = "nlm")]
            WInner::Nl(w) => w.analyze_nbest(text, n, opt),
            #[cfg(feature = "nlm")]
            WInner::KnNl(w) => w.analyze_nbest(text, n, opt),
        };
        let best = self.run(text);
        let same = |a: &[Token], b: &[Token]| a.len() == b.len() && a.iter().zip(b).all(|(x, y)| x.form == y.form && x.tag == y.tag && x.start == y.start && x.end == y.end);
        if r.first().map_or(true, |(_, t)| !same(t, &best)) {
            let sc = r.first().map_or(0.0, |x| x.0);
            r.retain(|(_, t)| !same(t, &best));
            r.insert(0, (sc, best));
            r.truncate(n);
        }
        r
    }

    /// 미리 정한 구간([`Pretoken`])을 지키며 분석한다. 돌려주는 것은 `(형태소들, 구간마다 지켰는가)`.
    /// 이미 아는 고유 명사 구간을 고정하거나 분석을 일부러 다른 쪽으로 보내 볼 때 쓴다.
    ///
    /// ```no_run
    /// # let engine = madi::Engine::load(&madi::EngineConfig::new("models/madi.dict"))?;
    /// let mut w = engine.worker();
    /// let pre = [madi::Pretoken { start: 0, end: 1, form: Some("감".into()), tag: Some("VV".into()) }];
    /// let (toks, ok) = w.analyze_pretokenized("감기는 무서운 병이다", &pre);
    /// assert!(ok[0]);                                 // 감/VV 기/ETN 는/JX …
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn analyze_pretokenized(&mut self, text: &str, pre: &[Pretoken]) -> (Vec<Token>, Vec<bool>) {
        let chars: Vec<char> = text.chars().collect();
        let cons: Vec<madi_core::lattice::Boost> = pre
            .iter()
            .map(|p| {
                let e = p.end.min(chars.len());
                let s = p.start.min(e);
                madi_core::lattice::Boost {
                    c0: s as u32,
                    c1: e as u32,
                    form: p.form.clone().unwrap_or_else(|| chars[s..e].iter().collect()),
                    tag: p.tag.clone().unwrap_or_default(),
                    bonus: 30.0,
                }
            })
            .collect();
        let opt = &self.e.options;
        match &mut self.w {
            WInner::Conn(w) => w.analyze_constrained(text, opt, &cons),
            WInner::Kn(w) => w.analyze_constrained(text, opt, &cons),
            #[cfg(feature = "nlm")]
            WInner::Nl(w) => w.analyze_constrained(text, opt, &cons),
            #[cfg(feature = "nlm")]
            WInner::KnNl(w) => w.analyze_constrained(text, opt, &cons),
        }
    }

    /// 문장 하나를 그대로 분석한다(정제·문장 분리 없이). 가장 단순한 진입점.
    ///
    /// 토큰 위치는 `text` 안 글자 위치. 정밀 모드 엔진이면 교사 재선택까지 거친 결과다.
    /// 여러 문장이 든 글은 [`sentences`](Self::sentences) 로 나눠 분석하는 편이 정확하다.
    pub fn analyze_sentence(&mut self, text: &str) -> Vec<Token> {
        self.run(text)
    }

    /// 검색어처럼 짧은 입력 하나를 분석한다. 앞뒤 공백을 떼는 것 말고는 [`analyze_sentence`](Self::analyze_sentence) 와 같다.
    pub fn analyze_query(&mut self, text: &str) -> Vec<Token> {
        self.run(text.trim())
    }

    /// [`analyze_query_nbest`](Self::analyze_query_nbest) 가 쓸 옵션을 따로 정한다(`None` 이면 엔진 옵션).
    /// 점수 눈금만 바꿔 재야 하는 특수 용도(맞춤법 검사기)이며 보통은 쓰지 않는다.
    pub fn set_nbest_options(&mut self, opt: Option<Options>) {
        self.nbest_opt = opt;
    }

    /// 검색어용 n-best — 격자 탐색의 후보를 가공 없이 돌려준다(정밀 모드·2단 문턱 보정 없음). 일반 용도는
    /// [`analyze_nbest`](Self::analyze_nbest) 를 쓴다. [`set_teacher_score`](Self::set_teacher_score) 가 켜져 있으면 점수가
    /// 교사 로그 확률로 바뀐다.
    pub fn analyze_query_nbest(&mut self, text: &str, n: usize) -> Vec<(f32, Vec<Token>)> {
        let opt = self.nbest_opt.as_ref().unwrap_or(&self.e.options);
        let text = text.trim();
        let mut r = match &mut self.w {
            WInner::Conn(w) => w.analyze_nbest(text, n, opt),
            WInner::Kn(w) => w.analyze_nbest(text, n, opt),
            #[cfg(feature = "nlm")]
            WInner::Nl(w) => w.analyze_nbest(text, n, opt),
            #[cfg(feature = "nlm")]
            WInner::KnNl(w) => w.analyze_nbest(text, n, opt),
        };
        if self.teacher_score {
            if let (Some((tlm, _)), Some(st)) = (&self.e.precise, &mut self.tst) {
                for (sc, toks) in r.iter_mut() {
                    *sc = teacher_logprob(tlm, st, toks);
                }
            }
        }
        r
    }

    /// 켜면 [`analyze_query_nbest`](Self::analyze_query_nbest) 의 점수가 정밀 모드 교사의 문장 로그 확률(클수록 좋음)이 된다.
    /// 엔진에 교사가 없으면 무시. 특수 용도(맞춤법 검사기).
    pub fn set_teacher_score(&mut self, on: bool) {
        self.teacher_score = on;
    }
}

/// 교사로 본 형태소열 로그 확률: BOS×3 + 토큰 + EOS. 교사 문맥(ctx)보다 길면 64 토큰씩 앞 문맥을 이어 가며 더한다
fn teacher_logprob(tlm: &Tlm, st: &mut TlmState, toks: &[Token]) -> f32 {
    use madi_lm::precise::{BOS, EOS};
    let mut seq: Vec<u16> = toks.iter().map(|t| tlm.id_of(&t.form, t.tag)).collect();
    seq.push(EOS);
    let mut prefix: Vec<u16> = vec![BOS, BOS, BOS];
    let mut total = 0.0;
    for chunk in seq.chunks(64) {
        total += tlm.score(st, &prefix, &[chunk])[0];
        prefix.extend_from_slice(chunk);
    }
    total
}

/// 토큰들을 한 줄 글로: `형태/코드 형태/코드 | 형태/코드 …` (어절 경계는 `|`). `madi corpus --tokens` 출력의 둘째 열과 같은 형식.
///
/// ```no_run
/// # let engine = madi::Engine::load(&madi::EngineConfig::new("models/madi.dict"))?;
/// let mut w = engine.worker();
/// println!("{}", madi::format_tokens(&w.analyze_sentence("아버지가 방에")));   // 아버지/NNG 가/JKS | 방/NNG 에/JKB
/// # Ok::<(), anyhow::Error>(())
/// ```
pub fn format_tokens(toks: &[Token]) -> String {
    text::format_tokens(toks)
}

/// 판본 문자열의 점수 가중·탐색 판 (10.17 A2): `.r3p`(기본, 논문 판 3p) 또는 `.r3`(옛 운영 가중 `--score-preset rev3`),
/// 그 뒤 전후향 가지치기 문턱 `.fN`(기본 `.f11`, 끄면 `.f0`). 가중이 두 프리셋 어느 쪽도 아니면 `.r3p` 로 두고 차이는 `.w` 에 든다
fn rev_tag(cfg: &EngineConfig) -> String {
    let s = &cfg.options.search;
    let r = if s.is_rev3() && !s.is_rev3p() { format!(".r{}", madi_core::lattice::SCORE_REV) } else { format!(".r{}p", madi_core::lattice::SCORE_REV) };
    let f = s.fb_cutoff;
    let f = if f == f.trunc() { format!("{}", f as i64) } else { format!("{}", f) };
    format!("{r}.f{f}")
}

/// 신경망 LM 을 함께 쓸 때의 운영 가중 `(lm_weight, nlm_weight)` = (0.7, 0.3). 기본 모드의 [`EngineConfig::lm_weight`]·
/// [`nlm_weight`](EngineConfig::nlm_weight) 에 이 값을 넣는다. CLI 는 `--nlm` 만 주면 이 값을 쓴다.
pub const NLM_MIX_WEIGHTS: (f32, f32) = (0.7, 0.3);

/// 판본 문자열의 `.w`: 가중치·옵션 가운데 **기본값과 다른 칸만** `이름=값` 로 모아 해시한다. 옵션 구조에 칸이 늘어도
/// 그 칸이 기본값이면 해시가 바뀌지 않는다. 점수 가중 프리셋(`.r3`/`.r3p`)과 `fb_cutoff`(`.fN`)는 앞 태그로 나타내므로 뺀다.
/// 아무것도 다르지 않으면 빈 문자열
fn knob_tag(cfg: &EngineConfig) -> String {
    let d = knob_diff(cfg);
    if d.is_empty() { String::new() } else { format!(".w{}", short(hash_bytes(7, d.join(" ").as_bytes()))) }
}

/// 설정 가운데 기본값과 다른 칸을 `이름=값` 목록으로 — 판본 문자열의 `.w` 해시가 무엇에서 왔는지 확인할 때
/// (`madi version --knobs` 가 이것을 찍는다). 비어 있으면 기본 설정이다.
pub fn knob_diff(cfg: &EngineConfig) -> Vec<String> {
    let def = EngineConfig::new("");
    let mut d: Vec<String> = Vec::new();
    // 가중 기준: NLM 을 쓰면 0.7 / 0.3, 아니면 KnLM 1.0 (NLM 가중은 쓰이지 않으므로 보지 않는다)
    if cfg.nlm.is_some() {
        if cfg.lm_weight != NLM_MIX_WEIGHTS.0 { d.push(format!("lm_weight={}", cfg.lm_weight)); }
        if cfg.nlm_weight != NLM_MIX_WEIGHTS.1 { d.push(format!("nlm_weight={}", cfg.nlm_weight)); }
    } else if cfg.lm_weight != def.lm_weight {
        d.push(format!("lm_weight={}", cfg.lm_weight));
    }
    if cfg.unk_scale != def.unk_scale { d.push(format!("unk_scale={}", cfg.unk_scale)); }
    // 짧은 문장 버리기는 `.s` 와 짝으로 본다: 규칙을 쓰면 5, 규칙을 끄면(`.s-`) 0 이 기본 (Python·WASM·맞춤법은 끄고 0)
    let min_def = if cfg.skip == Skip::Off { 0 } else { def.min_len };
    if cfg.min_len != min_def { d.push(format!("min_len={}", cfg.min_len)); }
    let s = &cfg.options.search;
    let preset = s.is_rev3() || s.is_rev3p();
    d.extend(s.diff_default(!preset, false));
    let o = &cfg.options;
    let od = &def.options;
    madi_core::diff_fields!(d, o, od; split_compound, split_unknown_compound, fine_tags, merge_nouns, std_2025);
    d
}