LINE1 10 20 30 40 50 60 70 80 9012345678910use std::sync::Arc;1112use serde::{Deserialize, Serialize};13use serde_json::{Map, Value};1415use crate::engine::ExtractOptions;16use crate::engine::schema::{ClassificationTask, Field, Structure};171819const MAX_LABELS: usize = 1024;20const MAX_TEXT_CHARS: usize = 100_000;2122const DEFAULT_STRUCTURE: &str = "record";2324const DEFAULT_THRESHOLD: f64 = 0.5;252627#[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}363738#[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}474849505152#[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}686970pub struct AppState {71 pub engine: Arc<crate::engine::Engine>,72 73 pub gate: std::sync::Mutex<()>,74}757677787980pub 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}96979899100101pub 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}126127128129130131pub 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 161 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}168169170fn 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}204205206fn 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}265266267fn 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}323324325type 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}399400401fn read_optional_threshold(value: Option<f64>) -> Result<Option<f64>, String> {402 value.map(check_threshold).transpose()403}404405406fn 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}450451452fn 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}