docs/architecture.mmd

flowchart TD
    U[User / API] --> UI{UI lifecycle state}
    UI -->|demo selected + empty| DI[Lazy demo indexing]
    UI -->|ready| G[Input guardrails]
    DI --> G
    G --> P{Semantic QueryPlan}
    P --> PF{Workspace preflight}
    PF -->|missing local data| AB[Abstain]
    PF -->|structured data| SQL[Read-only Text2SQL / DuckDB]
    PF -->|external| W[Ask-the-Web]
    PF -->|corpus or mixed| RS{Task-aware retrieval strategy}

    RS -->|semantic| CI[Chunk index]
    RS -->|global| GB[Source-balanced global evidence]
    RS -->|hierarchical| SPI[Source-profile index]
    RS -->|analytical| AN[Source-balanced docs + DuckDB analytical context]
    SPI --> SEL[Semantic source selection]
    SEL --> SCI[Source-scoped chunk search]
    SCI --> CI

    CI --> D[FastEmbed dense / Qdrant]
    CI --> B[BM25 sparse]
    D --> F[RRF]
    B --> F
    F --> RP{Adaptive reranker policy}
    RP -->|skip for Fast / small easy corpus| EG
    RP -->|use for harder / larger tasks| X[Cross-encoder reranker]

    X --> EG{Task-aware evidence grader}
    GB --> EG
    AN --> EG
    EG -->|sufficient| A[Grounded Gemini generation]
    EG -->|weak first attempt| COR[Correct queries / strategy]
    COR --> RS
    EG -->|weak + web relevant + allowed| W
    EG -->|weak + web irrelevant| AB
    W --> A

    A --> V{Self-RAG verifier}
    V -->|revise once| RV[Faithfulness revision]
    RV --> V
    V -->|pass| O[Cited answer + sources + trace]
    SQL --> O
    AB --> O

    O -. cache-bypassed fresh benchmark .-> EV[Evaluation harness]
    EV --> ER[Bounded source metrics + reranker ablation]
    EV --> EP[Planner / web-policy metrics]
    EV --> EC[Citation + answer-key metrics]
    EV --> ES[Text2SQL + abstention + latency]
    EV --> HM[Hard-mode robustness]
    EV --> PB[Optional profile benchmark]
    EV --> NL[Node latency summary]
    EV --> EJ[Calibrated Gemini Deep judge]
    ER --> QG[Quality gates + diagnostics]
    EP --> QG
    EC --> QG
    ES --> QG
    EJ --> QG
    HM --> QG
    PB --> QG
    NL --> QG
    QG --> EH[Saved Quick / Standard / Deep reports]
    EH --> CMP[In-app comparison + saved-report API]
    EH --> HIST[Timestamped evaluation history + deltas]
    EH -. compatible Standard baseline .-> EJ

    API[FastAPI /docs + OpenAPI + Prometheus] -. live introspection .-> UI

%% v1.7: evidence-cited grounded-absence answers bypass the low-confidence revise loop.