CHINN — Chapter Hierarchy Intelligence Neural Network (retry 1)

## CHINN — Chapter Hierarchy Intelligence Neural Network ### Origin Jack Chang (Cubeship/C8 QP-in-training) identified that classification needs chapter-specific domain expertise, not one monolithic model. His insight: "chapter by chapter subagents — ontology mapping we need to finesse." This maps directly to CBP's 10 Centers of Excellence and Expertise (CEEs), which already organize trade enforcement by industry domain. ### What CHINN Does CHINN is a **Layer 2 Trade Operations INN** that routes classification requests to chapter-specialized logic. It sits between UINN (user intent) and the existing INNs (RINN, TEINN, OINN, FINN), adding a chapter-awareness layer that no current INN provides. **Flow:** ``` Product → UINN (intent) → CHINN (chapter router) → Chapter Specialist → RINN/OINN/FINN ``` **Why it's not TEINN:** TEINN handles tariff *engineering* (strategic manipulation). CHINN handles *domain expertise* (a textiles specialist knows different classification signals than a metals specialist). ### Architecture Requirements #### 1. CEE Domain Registry Map CBP's 10 CEEs to HTS chapter ranges. Each domain defines: - Chapter range (e.g., CEE004 Apparel = Ch. 50-67) - Classification signals (what matters for this domain: material composition? function? use?) - PGA agencies involved (FDA, FWS, CPSC, EPA, etc.) - Trade agreement gotchas (USMCA content thresholds vary by chapter) - Risk flags (UFLPA for textiles, CBAM for metals, §301 for electronics) ```python class CEEDomain(Enum): PHARMA_HEALTH_CHEMICALS = "CEE001" # Ch. 28-30, 33-34, 38 AGRICULTURE_PREPARED = "CEE002" # Ch. 01-24 AUTOMOTIVE_AEROSPACE = "CEE003" # Ch. 87-88 APPAREL_FOOTWEAR_TEXTILES = "CEE004" # Ch. 50-67 BASE_METALS = "CEE005" # Ch. 72-83 PETROLEUM_GAS_MINERALS = "CEE006" # Ch. 25-27 ELECTRONICS = "CEE007" # Ch. 84-85 (partial) CONSUMER_MASS_MERCH = "CEE008" # Mixed: 39, 42, 69, 94-96 INDUSTRIAL_MANUFACTURING = "CEE009" # Ch. 39-40, 44, 68-70 MACHINERY = "CEE010" # Ch. 84-85, 90 ``` #### 2. Chapter Router Given a product description + initial HS2/HS4 candidate, determine: - Which CEE domain owns this product - What classification signals to prioritize - Which PGA agencies to pre-screen - Which GRI rules are most likely to apply The router should handle ambiguous cases (e.g., a "smart watch" could be CEE007 Electronics or CEE008 Consumer — essential character determines routing). #### 3. Chapter Specialist Config Each CEE domain gets a specialist config (NOT a separate model — a prompt template + signal weights): ```python @dataclass class ChapterSpecialist: domain: CEEDomain chapter_range: list[str] # ["50", "51", ..., "67"] classification_signals: list[str] # ["material_composition", "weave_type", "fiber_content"] primary_gri: list[GRIRule] # Which GRI rules dominate this domain pga_agencies: list[str] # ["CPSC", "FTC", "CBP"] risk_flags: list[str] # ["UFLPA", "cotton_provenance", "COO_marking"] de_minimis_patterns: dict # Domain-specific de minimis behaviors fta_rules: dict # Domain-specific FTA qualification rules (e.g., yarn-forward for textiles) ``` #### 4. Pattern Bus Integration Add `CHAPTER` pattern type to PatternType enum in `pattern_bus.py`: ```python CHAPTER = "chapter" # Chapter routing decisions (from CHINN) ``` CHINN publishes patterns like: - `chapter:route:abc123` → ChapterRoutingResult (which domain, which specialist, confidence) - `chapter:signals:abc123` → ChapterSignals (what to look for in this domain) - `chapter:qp:jack` → QPCertification (which chapters Jack is certified for) CHINN subscribes to: - `classification:*` patterns from VINN/UINN (initial candidates to route) - `regulatory:*` patterns from RINN (domain-specific rule changes) #### 5. QP Certification Tracking Jack is C8's first QP (Qualified Person) in training. CHINN should track: - Which chapters a QP is certified for - Certification date and expiration - Ruling history per chapter (Jack's track record) - Escalation rules (when to auto-route vs require QP review) ```python @dataclass class QPCertification: qp_name: str # "Jack Chang" certified_chapters: list[str] # ["61", "62", "63"] certification_date: date rulings_count: int # How many classifications in these chapters accuracy_rate: float # Tracked against CBP rulings cee_domain: CEEDomain # CEE004 ``` #### 6. Jack's 4 Intake Questions as CHINN Signals Jack's real-world broker workflow defines the input schema for CHINN: 1. **Visual/SKU** → `analyze_product` output → CHINN routes by detected product type 2. **COO tags** → OINN origin signal + CHINN checks if chapter requires COO marking (19 CFR 134) 3. **Price points** → FINN declared value → CHINN determines H7/H1 path + LDP routing 4. **Upstream materials** → OINN provenance + CHINN checks domain-specific supply chain rules (UFLPA for Ch. 50-67, CBAM for Ch. 72-83) ### File Location `oneworld_trade/agents/chinn.py` ### Conventions (match existing INNs) - Dataclasses + Enums (see teinn.py, rinn.py pattern) - No Flask, no DB at module level — pure Python, testable standalone - Supabase integration via optional import (see rinn.py lines 33-37) - Pattern Bus integration via publish/subscribe (see pattern_bus.py) - Docstring header explaining the INN's philosophy (see rinn.py "never embed regulatory state" / teinn.py "Merritt v. Welsh") ### CHINN's Philosophy (for docstring) "Classify by domain, not by code. A textile specialist sees fiber content where a metals specialist sees alloy grade. The chapter determines what matters — CHINN routes the question to the expert who knows what to look for." ### Deliverables 1. `oneworld_trade/agents/chinn.py` — Full CHINN implementation with CEE registry, chapter router, specialist configs, QP tracking 2. Add `CHAPTER` to `PatternType` enum in `pattern_bus.py` 3. Unit tests: `tests/test_chinn.py` — route ceramic mug → CEE008, steel beam → CEE005, silk scarf → CEE004, smart watch → CEE007/CEE008 disambiguation 4. One worked example: Jack's textile intake (Ch. 61-62) showing full flow from product description through CHINN routing to specialist signals ### Context - CBP CEE directory: https://www.cbp.gov/trade/centers-excellence-and-expertise-information/cee-directory - Existing INNs: `oneworld_trade/agents/*.py` (25 INNs, Pattern Bus) - TEINN pattern: `oneworld_trade/agents/teinn.py` (closest precedent) - RINN pattern: `oneworld_trade/agents/rinn.py` (dynamic vs embedded principle) - Jack's QP path: First CBP filing target, ABI VPN onboarding in progress