Skip to content
1        10        20        30        40        50        60        70        80        901//! The decision API.2//!3//! The wire shapes are a one-to-one port of `gliner2`'s Python surface:4//! `classify_text(text, tasks, ...)`, `batch_classify_text(texts, tasks, ...)`5//! and `extract_json(text, structures, ...)` take a *text* plus the label sets6//! or property names, and answer with the same object the Python call returns —7//! `{"intent": "refund_request"}` for a head, `{"taxes": "210", "costs": "2000"}`8//! for an extraction.910use std::sync::Arc;1112use serde::{Deserialize, Serialize};13use serde_json::{Map, Value};1415use crate::engine::ExtractOptions;16use crate::engine::schema::{ClassificationTask, Field, Structure};1718/// A label set may be given as plain labels or as label/description pairs.19const MAX_LABELS: usize = 1024;20const MAX_TEXT_CHARS: usize = 100_000;21/// Prompt name used for the `properties` shorthand.22const DEFAULT_STRUCTURE: &str = "record";23/// Score cutoff used when the request does not set one.24const DEFAULT_THRESHOLD: f64 = 0.5;2526/// `POST /v1/classify_text`27#[derive(Debug, Deserialize)]28pub struct ClassifyRequest {29    pub text: String,30    pub tasks: Map<String, Value>,31    #[serde(default)]32    pub include_confidence: bool,33    #[serde(default)]34    pub max_len: Option<usize>,35}3637/// `POST /v1/batch_classify_text`38#[derive(Debug, Deserialize)]39pub struct BatchClassifyRequest {40    pub texts: Vec<String>,41    pub tasks: Map<String, Value>,42    #[serde(default)]43    pub include_confidence: bool,44    #[serde(default)]45    pub max_len: Option<usize>,46}4748/// `POST /v1/extract`49///50/// Either `properties` (a flat list, answered with one object) or `structures`51/// (the `gliner2` shape, answered per structure name).52#[derive(Debug, Deserialize)]53pub struct ExtractRequest {54    pub text: String,55    #[serde(default)]56    pub properties: Vec<Value>,57    #[serde(default)]58    pub structures: Map<String, Value>,59    #[serde(default)]60    pub threshold: Option<f64>,61    #[serde(default)]62    pub include_confidence: bool,63    #[serde(default)]64    pub include_spans: bool,65    #[serde(default)]66    pub max_len: Option<usize>,67}6869/// Shared application state: the loaded model plus the inference gate.70pub struct AppState {71    pub engine: Arc<crate::engine::Engine>,72    /// Serializes inference so concurrent requests do not fight over the CPU.73    pub gate: std::sync::Mutex<()>,74}7576/// Run one classification request against the loaded engine.77///78/// # Errors79/// Returns a message when the request is malformed or inference fails.80pub fn classify(81    state: &AppState,82    text: &str,83    tasks: &Map<String, Value>,84    include_confidence: bool,85    max_len: Option<usize>,86) -> Result<Value, String> {87    let heads = build_tasks(tasks)?;88    validate_text(text)?;89    let _permit = state90        .gate91        .lock()92        .map_err(|_| "the inference engine is poisoned".to_owned())?;93    let answers = state.engine.classify(text, &heads, max_len)?;94    Ok(format_answers(tasks, &answers, include_confidence))95}9697/// Validate a batch and classify every text against the same heads.98///99/// # Errors100/// Returns a message when the request is malformed or inference fails.101pub fn batch_classify(102    state: &AppState,103    texts: &[String],104    tasks: &Map<String, Value>,105    include_confidence: bool,106    max_len: Option<usize>,107) -> Result<Vec<Value>, String> {108    if texts.is_empty() {109        return Err("texts must contain at least one text".to_owned());110    }111    let heads = build_tasks(tasks)?;112    for text in texts {113        validate_text(text)?;114    }115    let _permit = state116        .gate117        .lock()118        .map_err(|_| "the inference engine is poisoned".to_owned())?;119    let mut results = Vec::with_capacity(texts.len());120    for text in texts {121        let answers = state.engine.classify(text, &heads, max_len)?;122        results.push(format_answers(tasks, &answers, include_confidence));123    }124    Ok(results)125}126127/// Run an extraction request, mirroring `model.extract_json`.128///129/// # Errors130/// Returns a message when the request is malformed or scoring fails.131pub fn extract(state: &AppState, text: &str, request: &ExtractRequest) -> Result<Value, String> {132    validate_text(text)?;133    if request.properties.is_empty() && request.structures.is_empty() {134        return Err("properties or structures must not be empty".to_owned());135    }136    let threshold = read_optional_threshold(request.threshold)?.unwrap_or(DEFAULT_THRESHOLD);137    let options = ExtractOptions {138        threshold,139        include_confidence: request.include_confidence,140        include_spans: request.include_spans,141    };142143    let (structures, flat) = read_structures(request)?;144    let _permit = state145        .gate146        .lock()147        .map_err(|_| "the inference engine is poisoned".to_owned())?;148    let results = state149        .engine150        .extract(text, &structures, options, request.max_len)?;151152    if !flat {153        let mut answer = Map::new();154        for (structure, instances) in structures.iter().zip(results) {155            answer.insert(structure.name.clone(), Value::Array(instances));156        }157        return Ok(Value::Object(answer));158    }159160    // The flat form asks for one record: answer with the object itself, or with161    // the list when the model reports more than one instance.162    let instances: Vec<Value> = results.into_iter().flatten().collect();163    Ok(match instances.len() {164        1 => instances.into_iter().next().unwrap_or(Value::Null),165        _ => Value::Array(instances),166    })167}168169/// Build the structures for a request; `flat` marks the `properties` shorthand.170fn read_structures(request: &ExtractRequest) -> Result<(Vec<Structure>, bool), String> {171    if !request.properties.is_empty() {172        let fields = request173            .properties174            .iter()175            .map(read_field)176            .collect::<Result<_, _>>()?;177        return Ok((178            vec![Structure {179                name: DEFAULT_STRUCTURE.to_owned(),180                prompt: None,181                fields,182            }],183            true,184        ));185    }186187    let mut structures = Vec::with_capacity(request.structures.len());188    for (name, specs) in &request.structures {189        let specs: Vec<&Value> = match specs {190            Value::Array(items) => items.iter().collect(),191            single => vec![single],192        };193        structures.push(Structure {194            name: name.clone(),195            prompt: None,196            fields: specs197                .into_iter()198                .map(read_field)199                .collect::<Result<_, _>>()?,200        });201    }202    Ok((structures, false))203}204205/// A field spec: a bare name, `name::str::description`, or an object.206fn read_field(spec: &Value) -> Result<Field, String> {207    let default_dtype = "str".to_owned();208    match spec {209        Value::String(text) => {210            let mut parts = text.split("::");211            let name = parts.next().unwrap_or_default().trim();212            if name.is_empty() {213                return Err("field names must not be empty".to_owned());214            }215            let mut field = Field {216                name: name.to_owned(),217                dtype: default_dtype,218                description: None,219                threshold: None,220            };221            for part in parts {222                match part.trim() {223                    "str" | "list" => part.trim().clone_into(&mut field.dtype),224                    other => field.description = Some(other.to_owned()),225                }226            }227            Ok(field)228        }229        Value::Object(options) => {230            let name = read_label(options.get("name").unwrap_or(&Value::Null))?;231            let dtype = match options.get("dtype") {232                None | Some(Value::Null) => default_dtype,233                Some(Value::String(dtype)) if matches!(dtype.as_str(), "str" | "list") => {234                    dtype.clone()235                }236                Some(_) => return Err("dtype must be str or list".to_owned()),237            };238            let description = options.get("description").map(read_label).transpose()?;239            let threshold = read_threshold_option(options.get("threshold"))?;240            Ok(Field {241                name,242                dtype,243                description,244                threshold,245            })246        }247        _ => Err("fields must be strings or objects".to_owned()),248    }249}250251#[derive(Debug, Serialize)]252pub struct ErrorResponse {253    pub error: String,254}255256fn validate_text(text: &str) -> Result<(), String> {257    if text.trim().is_empty() {258        return Err("text must not be empty".to_owned());259    }260    if text.chars().count() > MAX_TEXT_CHARS {261        return Err(format!("text must be at most {MAX_TEXT_CHARS} characters"));262    }263    Ok(())264}265266/// Turn the request's head map into engine heads, preserving the given order.267fn build_tasks(tasks: &Map<String, Value>) -> Result<Vec<ClassificationTask>, String> {268    if tasks.is_empty() {269        return Err("tasks must contain at least one head".to_owned());270    }271    let mut heads = Vec::with_capacity(tasks.len());272    let mut total_labels = 0;273    for (name, config) in tasks {274        let head = build_head(name, config)?;275        total_labels += head.labels.len();276        heads.push(head);277    }278    if total_labels > MAX_LABELS {279        return Err(format!(280            "at most {MAX_LABELS} labels are supported per request"281        ));282    }283    Ok(heads)284}285286fn build_head(name: &str, config: &Value) -> Result<ClassificationTask, String> {287    if name.trim().is_empty() {288        return Err("task names must not be empty".to_owned());289    }290    match config {291        Value::Array(_) => {292            let (labels, descriptions) = read_labels(config)?;293            Ok(ClassificationTask {294                name: name.to_owned(),295                labels,296                label_descriptions: descriptions,297                prompt: None,298                examples: Vec::new(),299                multi_label: false,300                cls_threshold: 0.5,301                class_act: None,302            })303        }304        Value::Object(options) => {305            let labels = options306                .get("labels")307                .ok_or_else(|| format!("task '{name}' needs 'labels'"))?;308            let (labels, label_descriptions) = read_labels(labels)?;309            Ok(ClassificationTask {310                name: name.to_owned(),311                labels,312                label_descriptions,313                prompt: read_prompt(options.get("prompt"))?,314                examples: read_examples(options.get("examples"))?,315                multi_label: read_bool(options.get("multi_label"), "multi_label")?,316                cls_threshold: read_threshold(options.get("cls_threshold"))?,317                class_act: read_class_act(options.get("class_act"))?,318            })319        }320        _ => Err(format!("task '{name}' must be a label list or an object")),321    }322}323324/// Candidate labels plus the descriptions that were given with them.325type Labels = (Vec<String>, Vec<(String, String)>);326327fn read_labels(value: &Value) -> Result<Labels, String> {328    let (labels, descriptions): Labels = match value {329        Value::Array(items) => {330            let mut labels = Vec::with_capacity(items.len());331            for item in items {332                labels.push(read_label(item)?);333            }334            (labels, Vec::new())335        }336        Value::Object(map) => {337            let mut labels = Vec::with_capacity(map.len());338            let mut descriptions = Vec::with_capacity(map.len());339            for (label, description) in map {340                labels.push(read_label(&Value::String(label.clone()))?);341                descriptions.push((label.clone(), read_label(description)?));342            }343            (labels, descriptions)344        }345        _ => {346            return Err(347                "labels must be a list of strings or a label/description object".to_owned(),348            );349        }350    };351    if labels.is_empty() {352        return Err("labels must contain at least one label".to_owned());353    }354    Ok((labels, descriptions))355}356357fn read_label(value: &Value) -> Result<String, String> {358    value359        .as_str()360        .map(str::to_owned)361        .filter(|label| !label.trim().is_empty())362        .ok_or_else(|| "labels must be non-empty strings".to_owned())363}364365fn read_prompt(value: Option<&Value>) -> Result<Option<String>, String> {366    match value {367        None | Some(Value::Null) => Ok(None),368        Some(Value::String(prompt)) if prompt.trim().is_empty() => Ok(None),369        Some(Value::String(prompt)) => Ok(Some(prompt.clone())),370        Some(_) => Err("prompt must be a string".to_owned()),371    }372}373374fn read_examples(value: Option<&Value>) -> Result<Vec<(String, String)>, String> {375    let Some(Value::Array(items)) = value else {376        if value.is_none() || matches!(value, Some(Value::Null)) {377            return Ok(Vec::new());378        }379        return Err("examples must be a list of [input, label] pairs".to_owned());380    };381    items382        .iter()383        .map(|item| match item {384            Value::Array(pair) if pair.len() == 2 => {385                Ok((read_label(&pair[0])?, read_label(&pair[1])?))386            }387            _ => Err("examples must be a list of [input, label] pairs".to_owned()),388        })389        .collect()390}391392fn read_bool(value: Option<&Value>, field: &str) -> Result<bool, String> {393    match value {394        None | Some(Value::Null) => Ok(false),395        Some(Value::Bool(flag)) => Ok(*flag),396        Some(_) => Err(format!("{field} must be a boolean")),397    }398}399400/// `Some` only when the caller set a threshold, validated to be a probability.401fn read_optional_threshold(value: Option<f64>) -> Result<Option<f64>, String> {402    value.map(check_threshold).transpose()403}404405/// The same, reading the JSON form, where an absent key means "not set".406fn read_threshold_option(value: Option<&Value>) -> Result<Option<f64>, String> {407    match value {408        None | Some(Value::Null) => Ok(None),409        Some(Value::Number(number)) => {410            let threshold = number411                .as_f64()412                .ok_or_else(|| "threshold must be a number".to_owned())?;413            Ok(Some(check_threshold(threshold)?))414        }415        Some(_) => Err("threshold must be a number".to_owned()),416    }417}418419fn check_threshold(threshold: f64) -> Result<f64, String> {420    if !(0.0..=1.0).contains(&threshold) {421        return Err("threshold must be between 0 and 1".to_owned());422    }423    Ok(threshold)424}425426fn read_threshold(value: Option<&Value>) -> Result<f64, String> {427    match value {428        None | Some(Value::Null) => Ok(DEFAULT_THRESHOLD),429        Some(Value::Number(number)) => {430            let threshold = number431                .as_f64()432                .ok_or_else(|| "cls_threshold must be a number".to_owned())?;433            check_threshold(threshold)434                .map_err(|_| "cls_threshold must be between 0 and 1".to_owned())435        }436        Some(_) => Err("cls_threshold must be a number".to_owned()),437    }438}439440fn read_class_act(value: Option<&Value>) -> Result<Option<String>, String> {441    match value {442        None | Some(Value::Null) => Ok(None),443        Some(Value::String(act)) => match act.as_str() {444            "auto" | "sigmoid" | "softmax" => Ok(Some(act.clone())),445            _ => Err("class_act must be auto, sigmoid or softmax".to_owned()),446        },447        Some(_) => Err("class_act must be auto, sigmoid or softmax".to_owned()),448    }449}450451/// Report the answers in the order the heads were requested.452fn format_answers(453    tasks: &Map<String, Value>,454    answers: &[Vec<(String, f64)>],455    include_confidence: bool,456) -> Value {457    let mut result = Map::new();458    for (name, answer) in tasks.keys().zip(answers) {459        let multi_label = answer.len() != 1 || is_multi_label(tasks.get(name));460        let value = if multi_label {461            Value::Array(462                answer463                    .iter()464                    .map(|(label, confidence)| label_value(label, *confidence, include_confidence))465                    .collect(),466            )467        } else {468            label_value(&answer[0].0, answer[0].1, include_confidence)469        };470        result.insert(name.clone(), value);471    }472    Value::Object(result)473}474475fn is_multi_label(config: Option<&Value>) -> bool {476    config477        .and_then(Value::as_object)478        .and_then(|options| options.get("multi_label"))479        .and_then(Value::as_bool)480        .unwrap_or(false)481}482483fn label_value(label: &str, confidence: f64, include_confidence: bool) -> Value {484    if include_confidence {485        let mut entry = Map::new();486        entry.insert("label".to_owned(), Value::String(label.to_owned()));487        entry.insert("confidence".to_owned(), confidence_json(confidence));488        Value::Object(entry)489    } else {490        Value::String(label.to_owned())491    }492}493494fn confidence_json(confidence: f64) -> Value {495    serde_json::Number::from_f64(confidence).map_or(Value::Null, Value::Number)496}497498#[cfg(test)]499mod tests {500    use serde_json::json;501502    use super::{build_tasks, format_answers};503504    #[test]505    fn plain_label_lists_become_single_label_heads() {506        let tasks = json!({ "sentiment": ["positive", "negative"] });507        let heads = build_tasks(tasks.as_object().unwrap()).unwrap();508        assert_eq!(heads.len(), 1);509        assert_eq!(heads[0].labels, ["positive", "negative"]);510        assert!(!heads[0].multi_label);511    }512513    #[test]514    fn multi_label_heads_keep_their_threshold_and_descriptions() {515        let tasks = json!({516            "intent": { "labels": ["a", "b"], "multi_label": true, "cls_threshold": 0.4 },517            "greeting": { "labels": { "hi": "a greeting", "bye": "a farewell" } },518        });519        let heads = build_tasks(tasks.as_object().unwrap()).unwrap();520        assert!(heads[0].multi_label);521        assert!((heads[0].cls_threshold - 0.4).abs() < f64::EPSILON);522        assert_eq!(523            heads[1].label_descriptions,524            [525                ("hi".to_owned(), "a greeting".to_owned()),526                ("bye".to_owned(), "a farewell".to_owned())527            ]528        );529    }530531    #[test]532    fn invalid_head_definitions_are_rejected() {533        for tasks in [534            json!({}),535            json!({ "intent": { "multi_label": true } }),536            json!({ "intent": [] }),537            json!({ "intent": { "labels": ["a"], "cls_threshold": 2 } }),538            json!({ "intent": { "labels": ["a"], "class_act": "relu" } }),539            json!({ "intent": { "labels": ["a"], "examples": [["x"]] } }),540        ] {541            assert!(build_tasks(tasks.as_object().unwrap()).is_err(), "{tasks}");542        }543    }544545    #[test]546    fn answers_are_reported_in_request_order() {547        let tasks =548            json!({ "intent": ["a", "b"], "aspects": { "labels": ["x"], "multi_label": true } });549        let answers = vec![550            vec![("b".to_owned(), 0.75)],551            vec![("x".to_owned(), 0.6), ("y".to_owned(), 0.5)],552        ];553        let formatted = format_answers(tasks.as_object().unwrap(), &answers, false);554        assert_eq!(formatted, json!({ "intent": "b", "aspects": ["x", "y"] }));555    }556557    #[test]558    fn confidences_are_opt_in() {559        let tasks = json!({ "intent": ["a", "b"] });560        let answers = vec![vec![("b".to_owned(), 0.75)]];561        let formatted = format_answers(tasks.as_object().unwrap(), &answers, true);562        assert_eq!(563            formatted,564            json!({ "intent": { "label": "b", "confidence": 0.75 } })565        );566    }567}