hs_predict/smiles/
mod.rs

1//! SMILES-based functional group detection and chapter-level HS classification.
2//!
3//! This module provides a pattern-matching engine that inspects a canonical
4//! SMILES string and infers:
5//!
6//! 1. **Organic vs. inorganic** classification
7//! 2. **Functional groups** present (up to 20 categories)
8//! 3. **HS chapter / heading hint** (approximate, confidence ≤ 0.70)
9//!
10//! The engine is used as Priority 3 in [`HsPipeline::classify`] when the CAS
11//! rule table (Priority 2) finds no match but a SMILES string is available.
12//!
13//! [`HsPipeline::classify`]: crate::pipeline::HsPipeline::classify
14//!
15//! # Example
16//! ```rust
17//! use hs_predict::smiles::classify_smiles;
18//! use hs_predict::smiles::detector::FunctionalGroup;
19//!
20//! let result = classify_smiles("CC(C)=O").unwrap(); // acetone
21//! assert_eq!(result.heading_hint.heading, Some(2914)); // ketone → 29.14
22//! ```
23
24pub mod chapter_map;
25pub mod detector;
26
27pub use chapter_map::HeadingHint;
28pub use detector::FunctionalGroup;
29
30use crate::types::OrganicInorganic;
31
32// ─────────────────────────────────────────────────────────────────────────────
33// SmilesClassification
34// ─────────────────────────────────────────────────────────────────────────────
35
36/// Result of SMILES-based functional group analysis and HS heading estimation.
37#[derive(Debug, Clone, serde::Serialize)]
38pub struct SmilesClassification {
39    /// Whether the compound is organic, inorganic, or organometallic.
40    pub organic_class: OrganicInorganic,
41
42    /// Functional groups detected in the SMILES string.
43    /// May be empty for simple hydrocarbons (alkanes, alkenes, etc.).
44    pub functional_groups: Vec<FunctionalGroup>,
45
46    /// Best-guess HS chapter / heading based on detected groups.
47    pub heading_hint: HeadingHint,
48}
49
50// ─────────────────────────────────────────────────────────────────────────────
51// Public entry point
52// ─────────────────────────────────────────────────────────────────────────────
53
54/// Analyse a SMILES string and return a chapter-level HS classification hint.
55///
56/// # Returns
57/// - `Some(SmilesClassification)` — analysis result; use
58///   [`SmilesClassification::heading_hint`] for the HS heading.
59/// - `None` — the SMILES string is empty or whitespace-only.
60///
61/// # Notes
62/// - Detection is based on substring matching against canonical SMILES
63///   (as produced by PubChem). Non-canonical or hand-written SMILES may
64///   yield reduced accuracy.
65/// - Results carry confidence ≤ 0.70; always verify with a trade-compliance
66///   expert before using in a customs declaration.
67///
68/// # Example
69/// ```rust
70/// use hs_predict::smiles::classify_smiles;
71///
72/// // Benzaldehyde → aldehyde → 29.12
73/// let r = classify_smiles("O=Cc1ccccc1").unwrap();
74/// assert_eq!(r.heading_hint.heading, Some(2912));
75///
76/// // Acetic acid → carboxylic acid → 29.15
77/// let r = classify_smiles("CC(=O)O").unwrap();
78/// assert_eq!(r.heading_hint.heading, Some(2915));
79/// ```
80pub fn classify_smiles(smiles: &str) -> Option<SmilesClassification> {
81    let smiles = smiles.trim();
82    if smiles.is_empty() {
83        return None;
84    }
85
86    let organic_class = detector::classify_organic(smiles);
87    let functional_groups = detector::detect_functional_groups(smiles);
88    let heading_hint = chapter_map::map_to_heading(&functional_groups, &organic_class);
89
90    Some(SmilesClassification {
91        organic_class,
92        functional_groups,
93        heading_hint,
94    })
95}
96
97// ─────────────────────────────────────────────────────────────────────────────
98// Tests
99// ─────────────────────────────────────────────────────────────────────────────
100
101#[cfg(test)]
102mod tests {
103    use super::*;
104
105    #[test]
106    fn empty_smiles_returns_none() {
107        assert!(classify_smiles("").is_none());
108        assert!(classify_smiles("   ").is_none());
109    }
110
111    #[test]
112    fn acetone_ketone_heading() {
113        // CC(C)=O — acetone (PubChem canonical)
114        let r = classify_smiles("CC(C)=O").unwrap();
115        assert_eq!(r.heading_hint.heading, Some(2914));
116        assert!(r.functional_groups.contains(&FunctionalGroup::Ketone));
117        assert!(matches!(r.organic_class, OrganicInorganic::Organic));
118    }
119
120    #[test]
121    fn acetic_acid_heading() {
122        // CC(=O)O — acetic acid
123        let r = classify_smiles("CC(=O)O").unwrap();
124        assert_eq!(r.heading_hint.heading, Some(2915));
125        assert!(r.functional_groups.contains(&FunctionalGroup::CarboxylicAcid));
126    }
127
128    #[test]
129    fn ethyl_acetate_heading() {
130        // CCOC(C)=O — ethyl acetate
131        let r = classify_smiles("CCOC(C)=O").unwrap();
132        assert_eq!(r.heading_hint.heading, Some(2915));
133        assert!(r.functional_groups.contains(&FunctionalGroup::Ester));
134    }
135
136    #[test]
137    fn benzaldehyde_heading() {
138        // O=Cc1ccccc1 — benzaldehyde
139        let r = classify_smiles("O=Cc1ccccc1").unwrap();
140        assert_eq!(r.heading_hint.heading, Some(2912));
141        assert!(r.functional_groups.contains(&FunctionalGroup::Aldehyde));
142    }
143
144    #[test]
145    fn ethanol_heading() {
146        // CCO — ethanol
147        let r = classify_smiles("CCO").unwrap();
148        assert_eq!(r.heading_hint.heading, Some(2905));
149        assert!(r.functional_groups.contains(&FunctionalGroup::Alcohol));
150    }
151
152    #[test]
153    fn methylamine_heading() {
154        // CN — methylamine
155        let r = classify_smiles("CN").unwrap();
156        assert_eq!(r.heading_hint.heading, Some(2921));
157    }
158
159    #[test]
160    fn chlorobenzene_heading() {
161        // Clc1ccccc1 — chlorobenzene
162        let r = classify_smiles("Clc1ccccc1").unwrap();
163        assert_eq!(r.heading_hint.heading, Some(2903));
164        assert!(r.functional_groups.contains(&FunctionalGroup::Halide));
165    }
166
167    #[test]
168    fn co2_is_inorganic_ch28() {
169        let r = classify_smiles("O=C=O").unwrap();
170        assert_eq!(r.heading_hint.chapter, 28);
171        assert!(matches!(r.organic_class, OrganicInorganic::Inorganic));
172    }
173
174    #[test]
175    fn epoxide_heading() {
176        // C1CO1 — ethylene oxide
177        let r = classify_smiles("C1CO1").unwrap();
178        assert_eq!(r.heading_hint.heading, Some(2910));
179    }
180
181    #[test]
182    fn phthalic_anhydride_heading() {
183        // O=C1OC(=O)c2ccccc21
184        let r = classify_smiles("O=C1OC(=O)c2ccccc21").unwrap();
185        assert!(r.functional_groups.contains(&FunctionalGroup::Anhydride));
186        assert_eq!(r.heading_hint.heading, Some(2915));
187    }
188}
hs_predict/smiles/mod.rs

hs_predict/smiles/
mod.rs
