%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#f0f4ff', 'primaryTextColor': '#1a1a2e', 'primaryBorderColor': '#4a6fa5', 'lineColor': '#4a6fa5', 'secondaryColor': '#fefefe', 'tertiaryColor': '#e8f4f8'}}}%%
flowchart TB
    subgraph User["User"]
        UI[("User Input")]
    end

    subgraph ML["ravana_ml — ML Substrate"]
        TG["tensor.py<br/>Raw/State tensors"]
        NN["nn/<br/>Module, Linear, GRU<br/>NeuralDecoder, RLMv2"]
        GR["graph.py<br/>ConceptGraph<br/>ConceptNode, ConceptEdge"]
        FE["free_energy.py<br/>FreeEnergyAccumulator"]
        PL["plasticity.py<br/>Hebbian/Anti-Hebbian"]
        EM["embedder.py<br/>GloVe→64D Projection"]
        OT["mapper.py<br/>AttributeEncoder<br/>LancasterEncoder"]
    end

    subgraph CHAT["ravana — Chat Engine"]
        BR["chat/brain_regions.py<br/>SelfModel, EpisodicIndex<br/>CauseClassifier, Empathy"]
        EN["chat/engine.py<br/>CognitiveChatEngine<br/>(8 mixins below)"]
        CW["chat/engine_graph.py<br/>GraphMixin<br/>_seed_concepts, _spread_and_collect"]
        RG["chat/engine_generation.py<br/>GenerationMixin<br/>Neural decoder, templates"]
        WL["chat/engine_web_search.py<br/>WebSearchMixin<br/>Web search → graph edges"]
        CG["chat/coherence_gate.py<br/>CoherenceGate<br/>Junk/Salad detection"]
        IR["chat/intent_router.py<br/>IntentRouter<br/>6-class routing"]
        SR["chat/self_model_router.py<br/>SelfAddressRouter"]
        HIG["chat/harm_intent_gate.py<br/>HarmIntentGate<br/>pre-generation safety"]
        SUP["chat/support_router.py<br/>SupportRouter<br/>advice/wellbeing"]
        CM["chat/consistency_monitor.py<br/>cross-turn consistency"]
        PFS["chat/personal_fact_store.py<br/>learned user-profile facts"]
        LG["language/<br/>SurfaceRealizer, VerbLexicon<br/>SyntacticAssembly, PFC"]

        WEB["web/<br/>SearchEngine, WebLearner<br/>OpenIE, WebToGraph"]
        DEC["decoder/<br/>DecoderEngine<br/>PredictiveCodingGenerator"]
        GRA["graph/<br/>GraphEngine"]

        COR["core/<br/>VADEmotion, Identity, Meaning<br/>WorkingMemory, PredictiveCoding<br/>VSAManager, HRRReasoner<br/>System1/System2<br/>fact_reasoning, temporal_*<br/>multi_hop, in_prompt_reasoner<br/>frequency_model, situation_model"]
        BOOT["bootstrap/<br/>BootstrapManager, PMISeeder"]
        LEARN["learn/<br/>CuriosityEngine, HippocampalReplay"]
        ONT["ontology/<br/>DerivedOntology, ConceptNet<br/>LingGenConditioner"]
        NN2["nn/rlm/<br/>RelationPredictor, Propagation, Plasticity"]
    end

    subgraph GRACE["ravana_grace — GRACE Governor"]
        GV["core/governor.py<br/>Governor, GovernorConfig<br/>RegulationMode"]
        EM2["core/emotion.py<br/>VADEmotionEngine<br/>Valence/Arousal/Dominance"]
        ID["core/identity.py<br/>IdentityEngine<br/>Self-concept stabilization"]
        SL["core/sleep.py<br/>SleepConsolidation<br/>4-stage SWS+REM"]
        ME["core/meaning.py<br/>MeaningEngine<br/>Intrinsic motivation"]
        MC["core/meta_cognition.py<br/>MetaCognition, BiasDetector<br/>ConfidenceCalibrator"]
        BE["core/belief_reasoner.py<br/>BeliefReasoner<br/>Multi-hypothesis reasoning"]
        DP["core/dual_process.py<br/>DualProcessController<br/>System 1/2 routing"]
        GW["core/global_workspace.py<br/>GlobalWorkspace<br/>Conscious broadcast"]
        HM["core/human_memory.py<br/>HumanMemoryEngine<br/>Episodic/Semantic"]

        ACT["core/active_epistemology.py<br/>ActiveEpistemology<br/>VoI-driven action"]
        WO["core/predictive_world.py<br/>LearnedWorldModel<br/>FalseWorldTester"]
        ST["core/strategy.py<br/>StrategyLayer<br/>Exploration modes"]
        OC["core/occam_layer.py<br/>OccamLayer<br/>Hypothesis discipline"]
    end

    UI --> BR
    BR --> EN
    EN --> CG
    CG --> IR
    IR --> SR
    SR --> CW
    CW --> GR
    CW --> RG
    RG --> DEC
    DEC --> NN
    RG --> LG
    LG --> ME
    LG --> EM2
    WL --> WEB
    WL --> GR
    COR --> EN
    EN --> GW
    EN --> DP
    EN --> MC
    EN --> SL
    EN --> EM2
    EN --> ID
    EN --> BE
    LEARN --> EN
    ONT --> EN
    BOOT --> CW

    GR -.-> NN
    GR -.-> FE
    GR -.-> PL

    GV -.-> EM2
    GV -.-> ID
    GV -.-> SL
    GV -.-> ME
    GV -.-> WO
    GV -.-> ACT

    style UI fill:#e1f5fe,stroke:#0288d1
    style EN fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style GR fill:#e8f5e9,stroke:#388e3c
    style NN fill:#e8f5e9,stroke:#388e3c
    style GV fill:#fce4ec,stroke:#c62828
    style EM2 fill:#fce4ec,stroke:#c62828

user text
   │
   ▼
[1] brain_regions.py  ── BRAIN-REPAIR PREPASSES ──
      • SelfModel.from_graph        (who am I / who is the user)
      • EpisodicIndex               (FIRST/LAST/BY_ENTITY recall)
      • classify_cause              (GloVe-centroid cause classification)
      • select_empathy_frame        (tightly-gated empathy)
      • humor_is_coherent           (learned salad classifier ORed with
                                     rule-based _is_word_salad; fail-closed)
      • parse_number_phrase / mirror_deictic / consult_internal
   │
   ▼
[2] engine.py :: CognitiveChatEngine.process_turn
      (engine.py composes 8 mixins: GenerationMixin, GraphMixin,
       ReasoningMixin, MemoryMixin, WebSearchMixin, SelfQueryMixin,
       PersistenceMixin, MonitorMixin)
      • harm_intent_gate         (pre-generation safety classifier; blocks
                                  harmful-intent user messages before routing)
      • intent_router          (chitchat / factual / hypothetical / identity / OOD)
      • support_router         (advice/wellbeing → web learner)
      • monitor_gate           (abstention / free-energy check)
      • coherence_gate         (GloVe-cosine coherence floor)
      • junk_scorer            (word-salad / degenerate-text rejection)
      • consistency_monitor    (cross-turn self-consistency of own claims)
   │
   ├─ if unknown / low-confidence ─► honest abstention ("I don't know")
   │
   ▼
[3] graph walk  (chain_walker.py)  over the typed ConceptGraph
      edges: causal, contrastive, analogical, temporal, semantic, is_a
   │
   ▼
[4] neural decoder  (ravana_ml.nn.neural_decoder)
      conditions generation on the graph-walk embedding + sensorimotor
      (LingGen) signal when promoted
   │
   ▼
[5] surface_realizer + syntactic cell assembly  →  natural-language response
   │
   ▼
[6] web_learning.py  (background)  ── if a gap was detected, learn from the web
      and write new typed edges into the graph for next time