# MagicAF

> MagicAF is the open-source Rust AI/ML/NLP framework by **Intracav**. It provides the foundational building blocks for AI systems — embeddings, vector search, LLM orchestration, RAG pipelines, and a full NLP toolkit — with zero cloud dependencies. Air-gapped-capable and built for on-premises deployment: designed for hospitals and other environments where data cannot leave the network. It is the framework underneath Lumen, Intracav's clinical AI platform, and this site also documents **Lumen UI**, the component DSL that renders Lumen's AI-generated interfaces.

## How to use this file

This is the structured index of magicaf.intracav.ai for AI agents — Claude, ChatGPT, Gemini, Perplexity, and the like. Every URL here is canonical and citable. Source code lives at https://github.com/magicaf/magicaf.

Three machine-readable formats are available:

- **This file** (https://magicaf.intracav.ai/llms.txt) — the index: every page on the site with a one-line description.
- **https://magicaf.intracav.ai/llms-full.txt** — the entire documentation corpus as a single Markdown document (195 pages). Use this when you want the whole thing in one fetch.
- **Per-page Markdown** — append `index.md` to any page URL for clean Markdown without site chrome. Example: `https://magicaf.intracav.ai/docs/getting-started/quickstart/index.md`. Every HTML page also advertises this via `<link rel="alternate" type="text/markdown">`.

Crawling is explicitly permitted for AI agents — see https://magicaf.intracav.ai/robots.txt and https://magicaf.intracav.ai/.well-known/ai.txt.

## Overview

- [MagicAF home](https://magicaf.intracav.ai/): Open-source Rust AI framework for RAG pipelines, NLP, embeddings, vector search, and LLM orchestration — built to run air-gapped with zero cloud dependencies, for environments where data cannot leave the network.
- [Documentation home](https://magicaf.intracav.ai/docs/)
- [About MagicAF](https://magicaf.intracav.ai/about/): what the framework is, who builds it, and the Intracav ecosystem.

## Getting Started

Install MagicAF, configure local services, and run your first RAG pipeline.

- [Getting Started (section hub)](https://magicaf.intracav.ai/docs/getting-started/)
- [Prerequisites](https://magicaf.intracav.ai/docs/getting-started/prerequisites/): System requirements and local services needed to run MagicAF.
- [Installation](https://magicaf.intracav.ai/docs/getting-started/installation/): Add MagicAF to your Rust project and configure the environment.
- [Quickstart](https://magicaf.intracav.ai/docs/getting-started/quickstart/): Build a complete RAG pipeline in under 50 lines of Rust — embed, store, retrieve, and answer, all against local services.

## Core Concepts

Understand MagicAF's architecture, layered design, and extension model.

- [Core Concepts (section hub)](https://magicaf.intracav.ai/docs/core-concepts/)
- [Architecture](https://magicaf.intracav.ai/docs/core-concepts/architecture/): MagicAF's three-layer architecture — how strict trait boundaries keep domain logic in adapters and make the same code portable from a laptop to an isolated network.
- [RAG Pipeline](https://magicaf.intracav.ai/docs/core-concepts/rag-pipeline/): How MagicAF's six-step Retrieval-Augmented Generation pipeline works — embed, retrieve, format, prompt, generate, parse — entirely on services you run yourself.
- [Traits & Interfaces](https://magicaf.intracav.ai/docs/core-concepts/traits-and-interfaces/): The trait system that makes every MagicAF component swappable.

## Decision Guides

Trade-off analysis and decision frameworks for engineers evaluating MagicAF for their organization.

- [Decision Guides (section hub)](https://magicaf.intracav.ai/docs/decision-guides/)
- [Choosing Models](https://magicaf.intracav.ai/docs/decision-guides/choosing-models/): Compare embedding models, LLMs, and quantization strategies for local MagicAF deployments.
- [Adapter Patterns](https://magicaf.intracav.ai/docs/decision-guides/adapter-patterns/): When to customize each MagicAF adapter trait, with common patterns and anti-patterns.
- [Deployment Strategy](https://magicaf.intracav.ai/docs/decision-guides/deployment-strategy/): Decision tree and comparison tables for choosing the right MagicAF deployment mode.

## Tutorials

Guided, narrative walkthroughs that teach MagicAF concepts through hands-on projects.

- [Tutorials (section hub)](https://magicaf.intracav.ai/docs/tutorials/)
- [Tutorial: Your First RAG Pipeline](https://magicaf.intracav.ai/docs/tutorials/your-first-rag-pipeline/): Build a working Retrieval-Augmented Generation pipeline from scratch and understand what each component does.
- [Tutorial: Custom Adapters](https://magicaf.intracav.ai/docs/tutorials/custom-adapters/): Learn when to customize MagicAF adapters, build a healthcare memo analyzer, and test it — all without modifying framework code.
- [Tutorial: Air-Gapped Deployment](https://magicaf.intracav.ai/docs/tutorials/air-gapped-deployment/): Walk through a complete prepare-transfer-build-verify cycle for deploying MagicAF in a disconnected defense lab.
- [Tutorial: Building a Clinical RAG Pipeline over The Clinical Database](https://magicaf.intracav.ai/docs/tutorials/clinical-rag-pipeline-clinical-database/): Build a healthcare RAG pipeline that grounds answers in The Clinical Database — a citable, clinician-reviewed clinical corpus — with citations back to canonical URLs.

## Guides

Step-by-step tutorials for building with MagicAF.

- [Guides (section hub)](https://magicaf.intracav.ai/docs/guides/)
- [Building Custom Adapters](https://magicaf.intracav.ai/docs/guides/building-adapters/): Implement domain-specific logic by creating custom EvidenceFormatter, PromptBuilder, and ResultParser traits.
- [Structured Output](https://magicaf.intracav.ai/docs/guides/structured-output/): Get typed JSON responses from the LLM using JsonResultParser<T> or custom parsers.
- [Testing](https://magicaf.intracav.ai/docs/guides/testing/): Unit test your adapters and workflows using mock services.

## API Reference

Complete API reference for the MagicAF Rust framework. Every trait, struct, configuration option, and error type across the core services and NLP pipelines.

- [API Reference (section hub)](https://magicaf.intracav.ai/docs/api-reference/)

### Core Services

API reference for MagicAF Core — traits, DTOs, configuration, and error types for embeddings, vector search, LLM orchestration, and RAG workflows.

- [Core Services (section hub)](https://magicaf.intracav.ai/docs/api-reference/core/)
- [EmbeddingService](https://magicaf.intracav.ai/docs/api-reference/core/embedding-service/): API reference for the EmbeddingService trait and LocalEmbeddingService.
- [VectorStore](https://magicaf.intracav.ai/docs/api-reference/core/vector-store/): API reference for the VectorStore trait, QdrantVectorStore, InMemoryVectorStore, and SearchResult.
- [LlmService](https://magicaf.intracav.ai/docs/api-reference/core/llm-service/): API reference for the LlmService trait, OpenAI-compatible DTOs, tool calling, multi-provider gateway, and streaming.
- [RAGWorkflow](https://magicaf.intracav.ai/docs/api-reference/core/rag-workflow/): API reference for the RAG pipeline engine — builder, execution, and result types.
- [Adapter Traits](https://magicaf.intracav.ai/docs/api-reference/core/adapter-traits/): API reference for EvidenceFormatter, PromptBuilder, ResultParser, and their default implementations.
- [Configuration](https://magicaf.intracav.ai/docs/api-reference/core/configuration/): All configuration structs, their fields, defaults, and serialization options — including resilience, TLS, connection pool, gateway, and ASR configs.
- [Error Handling](https://magicaf.intracav.ai/docs/api-reference/core/errors/): MagicError variants, numeric error codes, retryability, helper constructors, and the Result alias.
- [FFI](https://magicaf.intracav.ai/docs/api-reference/core/ffi/): FFI preparation, error code strategy, and planned language bindings.
- [Resilience](https://magicaf.intracav.ai/docs/api-reference/core/resilience/): API reference for retry with exponential backoff, circuit breaker, and rate limiter — production-grade fault tolerance for all MagicAF services.
- [Security](https://magicaf.intracav.ai/docs/api-reference/core/security/): API reference for prompt injection detection, PII redaction, LLM response validation, and FIPS mode assertion.
- [Compliance](https://magicaf.intracav.ai/docs/api-reference/core/compliance/): API reference for GDPR right-to-erasure workflows — entity deletion, verification, cache purging, and audit trail generation.
- [Observability](https://magicaf.intracav.ai/docs/api-reference/core/observability/): API reference for structured audit logging, OpenTelemetry metrics, and Prometheus integration.
- [Health & Shutdown](https://magicaf.intracav.ai/docs/api-reference/core/health-shutdown/): API reference for startup health gates, health reports, graceful shutdown handles, and signal handlers.
- [Embedding Cache](https://magicaf.intracav.ai/docs/api-reference/core/embedding-cache/): API reference for the LRU embedding cache with TTL, GDPR-aware purging, and transparent EmbeddingService wrapping.
- [Reranking](https://magicaf.intracav.ai/docs/api-reference/core/reranking/): API reference for the Reranker trait, score-threshold filtering, and cross-encoder reranking.
- [Streaming & Tool Calling](https://magicaf.intracav.ai/docs/api-reference/core/streaming/): API reference for SSE streaming, tool calling (function calling), and the multi-provider LLM gateway.
- [Speech-to-Text (ASR)](https://magicaf.intracav.ai/docs/api-reference/core/asr/): API reference for Automatic Speech Recognition — the AsrService trait, Voice Activity Detection, and Whisper integration.

### NLP Pipelines

Production-grade NLP pipelines that run entirely in-process — no external API servers required. Extract entities, analyze sentiment, translate text, answer questions, and more.

- [NLP Pipelines (section hub)](https://magicaf.intracav.ai/docs/api-reference/nlp/)
- [Question Answering](https://magicaf.intracav.ai/docs/api-reference/nlp/question-answering/): Extract answer spans from context passages using extractive question answering. Perfect for document Q&A when you have the source text.
- [Quick Start](https://magicaf.intracav.ai/docs/api-reference/nlp/quickstart/): Get up and running with MagicAF NLP pipelines in minutes. Install dependencies, load your first model, and run predictions.
- [Named Entity Recognition](https://magicaf.intracav.ai/docs/api-reference/nlp/named-entity-recognition/): Extract persons, locations, organisations, and miscellaneous entities from text using transformer-based NER. Perfect for structured information extraction.
- [Setup & Configuration](https://magicaf.intracav.ai/docs/api-reference/nlp/setup/): Complete guide to configuring NLP pipelines: native dependencies, model sources, device selection, and air-gapped deployment.
- [Pipelines](https://magicaf.intracav.ai/docs/api-reference/nlp/pipelines/): Complete reference for all MagicAF NLP pipelines: Question Answering, NER, Sentiment Analysis, Translation, Summarization, and more.
- [Sentiment Analysis](https://magicaf.intracav.ai/docs/api-reference/nlp/sentiment-analysis/): Classify text into positive or negative sentiment with confidence scores. Ideal for feedback analysis, social media monitoring, and opinion mining.
- [Zero-Shot Classification](https://magicaf.intracav.ai/docs/api-reference/nlp/zero-shot-classification/): Classify text into arbitrary categories without fine-tuning. Define your labels at inference time and the model predicts the best match.
- [Translation](https://magicaf.intracav.ai/docs/api-reference/nlp/translation/): Translate text between 25+ languages using neural machine translation models. Supports Marian (fast, pair-specific) and M2M100 (100+ languages).
- [Use Cases & Examples](https://magicaf.intracav.ai/docs/api-reference/nlp/use-cases/): Real-world examples using MagicAF NLP pipelines: document analysis, entity extraction, sentiment monitoring, and more.
- [Summarization](https://magicaf.intracav.ai/docs/api-reference/nlp/summarization/): Condense long documents into concise abstractive summaries. Powered by BART-large-CNN with configurable length, beam search, and length penalty.
- [Dialogue](https://magicaf.intracav.ai/docs/api-reference/nlp/dialogue/): Multi-turn conversational AI with built-in state management. Powered by DialoGPT with configurable temperature, sampling, and history tracking.
- [Text Generation](https://magicaf.intracav.ai/docs/api-reference/nlp/text-generation/): Auto-regressive language generation using in-process GPT-2 / GPT-Neo models. Full control over decoding strategy with no external server required.
- [Keyword Extraction](https://magicaf.intracav.ai/docs/api-reference/nlp/keyword-extraction/): Extract the most relevant keywords and keyphrases from documents using sentence embeddings, TF-IDF, and Maximal Marginal Relevance.
- [POS Tagging](https://magicaf.intracav.ai/docs/api-reference/nlp/pos-tagging/): Assign grammatical categories (noun, verb, adjective, etc.) to each word in text using BERT fine-tuned on the Penn Treebank tag set.
- [Masked Language Model](https://magicaf.intracav.ai/docs/api-reference/nlp/masked-language-model/): Predict masked (hidden) words in context using BERT. Perfect for fill-in-the-blank tasks, vocabulary assessment, text augmentation, and probing language understanding.

### Mobile

API reference for magicaf-mobile — on-device text intelligence for Flutter clients with zero async overhead.

- [Mobile (section hub)](https://magicaf.intracav.ai/docs/api-reference/mobile/)

## Deployment

Deploy MagicAF in production — Docker, air-gapped, edge/mobile, observability, and scaling.

- [Deployment (section hub)](https://magicaf.intracav.ai/docs/deployment/)
- [Docker Compose](https://magicaf.intracav.ai/docs/deployment/docker/): Reference Docker Compose configuration for deploying all MagicAF infrastructure services.
- [Air-Gapped Setup](https://magicaf.intracav.ai/docs/deployment/air-gapped/): Deploy MagicAF in fully disconnected environments with zero internet dependencies — dependency vendoring, offline model transfer, and verification for isolated networks.
- [Edge & Mobile](https://magicaf.intracav.ai/docs/deployment/edge-mobile/): Deploy MagicAF on resource-constrained devices — phones, tablets, embedded systems, and edge servers.
- [Observability](https://magicaf.intracav.ai/docs/deployment/observability/): Structured logging, health checks, and metrics for production MagicAF deployments.
- [Scaling](https://magicaf.intracav.ai/docs/deployment/scaling/): Horizontal scaling strategies for each MagicAF component.
- [Security](https://magicaf.intracav.ai/docs/deployment/security/): Security architecture and hardening guidance for MagicAF deployments — logging rules, secret handling, and a checklist for isolated and regulated environments.

## Examples

Working code examples for common MagicAF use cases.

- [Examples (section hub)](https://magicaf.intracav.ai/docs/examples/)
- [Minimal RAG](https://magicaf.intracav.ai/docs/examples/minimal-rag/): The simplest possible MagicAF RAG pipeline — default adapters, zero customization.
- [Document Q&A](https://magicaf.intracav.ai/docs/examples/document-qa/): Structured question-answering with custom adapters and JSON output parsing.
- [Multi-Source Analysis](https://magicaf.intracav.ai/docs/examples/multi-source-analysis/): Cross-reference multiple sources with fully custom adapters and complex structured output.

## MagicAF Reflex: Calibrated On-Device Decisions

A System One decision layer: one state, typed questions, calibrated answers with an explicit abstain. Runs on the device from hash-pinned ONNX, zero network.

- [MagicAF Reflex: Calibrated On-Device Decisions (section hub)](https://magicaf.intracav.ai/docs/reflex/)
- [The Decision Contract](https://magicaf.intracav.ai/docs/reflex/contract/): magicaf.reflex.request/v1 and response/v1 field by field: question types, dynamic options, abstain reasons, numeric error codes, and versioning.
- [Question Sets](https://magicaf.intracav.ai/docs/reflex/question-sets/): reflex.page_command@1.0.0 key by key: route, intent, section, clinical, commit_risk, with meanings, safe defaults, semver rules, and planned sets.
- [Architecture](https://magicaf.intracav.ai/docs/reflex/architecture/): Swappable Reflex backends, the shared encoder and heads, the two ONNX graphs and their I/O, text canonicalisation, tokenizer parity, and the hash-verified runtime.
- [Calibration and Abstention](https://magicaf.intracav.ai/docs/reflex/calibration-and-abstention/): How Reflex turns logits into calibrated probabilities and certifies thresholds: temperature and Platt scaling, selective thresholds, veto costs, and λ by RCPS.
- [Evaluation Harness](https://magicaf.intracav.ai/docs/reflex/evaluation/): Frozen, hashed datasets with a held-out vocabulary split, gold labels by construction, the JSON eval report, and the lane-policy safety metrics.
- [The Promotion Ladder](https://magicaf.intracav.ai/docs/reflex/promotion-ladder/): Shadow, veto, strict two-key, model decides: how a decision model earns authority, the invariants at every rung, and the hard gate before it may act alone.
- [Privacy and Supply Chain](https://magicaf.intracav.ai/docs/reflex/privacy-and-supply-chain/): Zero network proven by CDP capture in an end-to-end test, fail-closed SHA-256 on every runtime and model file, counts-only telemetry, and internal-only packaging.
- [Reflex v2 on the Device: magicaf-reflex](https://magicaf.intracav.ai/docs/reflex/on-device-scorer/): The Lumen Hospital sim's fitted Reflex v2 scorer as a Rust crate: Rust, WASM and Swift builds; exact, Core ML and cloud backends; bit-exact with the TypeScript scorer.
- [Running Reflex in Other Runtimes](https://magicaf.intracav.ai/docs/reflex/other-runtimes/): The planned Flutter (ONNX Runtime + Dart FFI) and Rust (magicaf-reflex-onnx, DecisionService) ports, and the parity fixtures every port must pass.
- [Reflex v2: Reflex Core and Reflex_02](https://magicaf.intracav.ai/docs/reflex/reflex-v2/): The in-house System One model family: a Laya-class instruction-following model (Reflex Core) and its on-device distillate (Reflex_02), shipped as a MagicAF SDK capability. Status, what is proven, what is not.
- [Adding a Question to a Question Set](https://magicaf.intracav.ai/docs/reflex/adding-a-question/): Add a key to a Reflex question set, teach the backends to answer it, and get it calibrated and evaluated, following the real code paths. Plus: writing a backend.

## Lumen Models: LMN Sirona and LMN Brigid

How Lumen serves its clinical model family, LMN Sirona and LMN Brigid, on MagicAF, and how it evaluates them as a system rather than as models.

- [Lumen Models: LMN Sirona and LMN Brigid (section hub)](https://magicaf.intracav.ai/docs/lumen-models/)
- [Serving a Model Family Behind LlmGateway](https://magicaf.intracav.ai/docs/lumen-models/serving-a-model-family/): Address models by stable family-version names, resolve them from private configuration into an LlmGateway, and keep provider identity out of logs and artifacts.
- [Evaluating a Clinical RAG System](https://magicaf.intracav.ai/docs/lumen-models/evaluating-clinical-rag/): Measure a clinical retrieval pipeline the way Lumen is measured: temporal-cut items, a SHA-256 commitment over the held-out set, product-mode runs, grounded accuracy, and an independent judge.

## Lumen UI

A component DSL for AI-generated user interfaces. 71 components across 8 categories, rendered from structured definitions in real time.

- [Lumen UI (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/)
- [Introduction](https://magicaf.intracav.ai/docs/lumen-ui/introduction/): What Lumen UI is, how it works, and the design principles behind AI-generated component rendering.
- [Quick Start](https://magicaf.intracav.ai/docs/lumen-ui/quick-start/): Render your first Lumen UI component in under 20 lines of Dart code.

### Core Concepts

The foundational concepts behind Lumen UI — DSL syntax, JSON format, rendering pipeline, theming, streaming, and actions.

- [Core Concepts (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/core-concepts/)
- [DSL Syntax](https://magicaf.intracav.ai/docs/lumen-ui/core-concepts/dsl-syntax/): Complete reference for the Lumen DSL — the PascalCase function-call syntax used by LLMs to describe component trees.
- [JSON Format](https://magicaf.intracav.ai/docs/lumen-ui/core-concepts/json-format/): The JSON representation of Lumen UI component trees — structure, conventions, and streaming recovery.
- [Rendering](https://magicaf.intracav.ai/docs/lumen-ui/core-concepts/rendering/): How Lumen UI converts parsed component trees into Flutter widgets — the registry, renderer, context, and error boundaries.
- [Theming](https://magicaf.intracav.ai/docs/lumen-ui/core-concepts/theming/): Lumen UI's zero-config theme system — semantic colors, typography, chart palettes, spacing, radii, shadows, and animations.
- [Streaming](https://magicaf.intracav.ai/docs/lumen-ui/core-concepts/streaming/): How Lumen UI handles partial, truncated, and in-progress content during LLM streaming.
- [Actions](https://magicaf.intracav.ai/docs/lumen-ui/core-concepts/actions/): How Lumen UI components dispatch events back to the host application — forms, navigation, clipboard, and custom actions.

### Component Reference

Complete reference for all 72 Lumen UI components — props, examples, and usage guidance across 8 categories.

- [Component Reference (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/components/)

#### Layout

Components for structuring and organizing content — cards, grids, tabs, accordions, and more.

- [Layout (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/components/layout/)
- [Card](https://magicaf.intracav.ai/docs/lumen-ui/components/layout/card/): Bordered container with optional title, description, and variant styling.
- [Stack](https://magicaf.intracav.ai/docs/lumen-ui/components/layout/stack/): Flex layout container for vertical or horizontal arrangement of children.
- [Grid](https://magicaf.intracav.ai/docs/lumen-ui/components/layout/grid/): Responsive multi-column grid layout.
- [Tabs](https://magicaf.intracav.ai/docs/lumen-ui/components/layout/tabs/): Tabbed container where each child maps to a labeled tab.
- [Accordion](https://magicaf.intracav.ai/docs/lumen-ui/components/layout/accordion/): Collapsible sections for progressive disclosure of content.
- [Steps](https://magicaf.intracav.ai/docs/lumen-ui/components/layout/steps/): Numbered step indicator for wizard flows and multi-stage processes.
- [Section](https://magicaf.intracav.ai/docs/lumen-ui/components/layout/section/): Labeled content section with optional description and collapsible behavior.
- [Separator](https://magicaf.intracav.ai/docs/lumen-ui/components/layout/separator/): Divider line with optional text label.
- [ScrollArea](https://magicaf.intracav.ai/docs/lumen-ui/components/layout/scroll-area/): Scrollable container with configurable maximum height and direction.
- [SplitView](https://magicaf.intracav.ai/docs/lumen-ui/components/layout/split-view/): Two-pane layout with adjustable width ratio.

#### Data Display

Components for presenting data — tables, statistics, code, timelines, and structured text.

- [Data Display (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/components/data-display/)
- [Table](https://magicaf.intracav.ai/docs/lumen-ui/components/data-display/table/): Data table with column headers, row striping, and flag-based cell highlighting.
- [KeyValue](https://magicaf.intracav.ai/docs/lumen-ui/components/data-display/key-value/): Displays key-value pairs in stacked or inline layout with optional separators.
- [Stat](https://magicaf.intracav.ai/docs/lumen-ui/components/data-display/stat/): Big number KPI card with label, unit, trend arrow, and change indicator.
- [Markdown](https://magicaf.intracav.ai/docs/lumen-ui/components/data-display/markdown/): Renders markdown-formatted text with themed styling.
- [CodeBlock](https://magicaf.intracav.ai/docs/lumen-ui/components/data-display/code-block/): Syntax-highlighted code block with language detection, header, and copy button.
- [JsonViewer](https://magicaf.intracav.ai/docs/lumen-ui/components/data-display/json-viewer/): Syntax-highlighted JSON viewer with copy support.
- [ListView](https://magicaf.intracav.ai/docs/lumen-ui/components/data-display/list-view/): Bulleted, numbered, or checklist-style list of items.
- [Timeline](https://magicaf.intracav.ai/docs/lumen-ui/components/data-display/timeline/): Vertical timeline with dated events, color-coded by variant.
- [DescriptionList](https://magicaf.intracav.ai/docs/lumen-ui/components/data-display/description-list/): Definition list with term-description pairs in a bordered list layout.

#### Charts & Visualization

Interactive chart components powered by fl_chart — bar, line, area, pie, radar, scatter, gauge, and sparkline.

- [Charts & Visualization (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/components/charts/)
- [BarChart](https://magicaf.intracav.ai/docs/lumen-ui/components/charts/bar-chart/): Categorical bar chart for comparing discrete values across groups.
- [LineChart](https://magicaf.intracav.ai/docs/lumen-ui/components/charts/line-chart/): Trend line chart with one or more series for continuous data over time.
- [AreaChart](https://magicaf.intracav.ai/docs/lumen-ui/components/charts/area-chart/): Filled area chart — line chart variant with shaded regions beneath each series.
- [PieChart](https://magicaf.intracav.ai/docs/lumen-ui/components/charts/pie-chart/): Pie or donut chart for proportional distribution of categorical data.
- [RadarChart](https://magicaf.intracav.ai/docs/lumen-ui/components/charts/radar-chart/): Spider/radar chart for multi-axis comparison across two or more series.
- [ScatterChart](https://magicaf.intracav.ai/docs/lumen-ui/components/charts/scatter-chart/): Scatter plot for correlation analysis between two continuous variables.
- [Gauge](https://magicaf.intracav.ai/docs/lumen-ui/components/charts/gauge/): Semi-circular gauge for single-value display with configurable thresholds.
- [Sparkline](https://magicaf.intracav.ai/docs/lumen-ui/components/charts/sparkline/): Compact inline trend line designed for embedding in stats, cards, or table cells.

#### Forms & Input

Interactive form components — text inputs, selectors, checkboxes, sliders, and date pickers. All dispatch actions to the host application.

- [Forms & Input (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/components/forms/)
- [Input](https://magicaf.intracav.ai/docs/lumen-ui/components/forms/input/): Single-line text input with label, placeholder, type variants, and validation error display.
- [Select](https://magicaf.intracav.ai/docs/lumen-ui/components/forms/select/): Dropdown selector for choosing from a list of predefined options.
- [Checkbox](https://magicaf.intracav.ai/docs/lumen-ui/components/forms/checkbox/): Checkbox toggle with label and optional help text.
- [RadioGroup](https://magicaf.intracav.ai/docs/lumen-ui/components/forms/radio-group/): Radio button group for single selection from multiple options.
- [Slider](https://magicaf.intracav.ai/docs/lumen-ui/components/forms/slider/): Numeric range slider with configurable min, max, and step.
- [DatePicker](https://magicaf.intracav.ai/docs/lumen-ui/components/forms/date-picker/): Date selection field with ISO-format output.
- [Toggle](https://magicaf.intracav.ai/docs/lumen-ui/components/forms/toggle/): Switch component for binary on/off state.
- [TextArea](https://magicaf.intracav.ai/docs/lumen-ui/components/forms/text-area/): Multi-line text input for longer-form content.

#### Clinical

20 healthcare-specialized components for clinical decision support — drug information, lab results, triage, FHIR patient data, dosing calculators, and more.

- [Clinical (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/)
- [TriageCard](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/triage-card/): ESI triage assessment card with color-coded acuity level, wait time, and recommended action.
- [DrugCard](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/drug-card/): RxNorm drug information card with ingredients, brand names, dose forms, and NDC codes.
- [DrugInteractions](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/drug-interactions/): FDA drug interaction display with structured label data and severity-coded interaction pairs.
- [LabRanges](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/lab-ranges/): Lab reference range display with demographic breakdowns and clinical notes per test.
- [Calculator](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/calculator/): Medical calculator result display with score, severity classification, and input breakdown.
- [DifferentialDx](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/differential-dx/): Ranked differential diagnosis list with likelihood, ICD-10 codes, and workup suggestions.
- [ClinicalNote](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/clinical-note/): Structured clinical note viewer for SOAP notes, H&P, discharge summaries, and progress notes.
- [FhirPatient](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/fhir-patient/): FHIR patient summary with demographics, conditions, medications, allergies, and encounters.
- [IVDrip](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/iv-drip/): IV drip rate calculator result with dose range check, titration table, and clinical notes.
- [RenalDose](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/renal-dose/): Renal dose adjustment guidance with CrCl calculation, CKD staging, and FDA dosing recommendations.
- [Antimicrobial](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/antimicrobial/): Antibiotic selection guidance with spectrum, dosing, duration, and monitoring recommendations.
- [AllergySafety](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/allergy-safety/): Allergy cross-reactivity and safety assessment with risk level and clinical recommendation.
- [AdverseEvents](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/adverse-events/): FDA adverse event reports with top reactions chart and serious outcome counts.
- [DrugRecalls](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/drug-recalls/): FDA drug recall notices with classification severity, recall reason, and recalling firm.
- [ClinicalTrials](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/clinical-trials/): ClinicalTrials.gov search results with trial status, phase, sponsor, and summary.
- [Guidelines](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/guidelines/): Clinical practice guidelines with ranked recommendations, evidence levels, and supporting references.
- [NpiResult](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/npi-result/): NPI provider lookup results with specialty, credentials, practice location, and contact details.
- [HcpcsCodes](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/hcpcs-codes/): HCPCS/CPT code listing with code badges and procedure descriptions.
- [CmsCoverage](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/cms-coverage/): CMS coverage determination display with policy ID, coverage status, and criteria sections.
- [Checklist](https://magicaf.intracav.ai/docs/lumen-ui/components/clinical/checklist/): Interactive checklist with toggleable items, section headers, and progress tracking.

#### Media

Components for displaying images, files, PDFs, and embedded HTML content.

- [Media (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/components/media/)
- [Image](https://magicaf.intracav.ai/docs/lumen-ui/components/media/image/): Single image display with optional caption, sizing controls, and rounded corners.
- [ImageGallery](https://magicaf.intracav.ai/docs/lumen-ui/components/media/image-gallery/): Responsive grid of images with configurable column count and spacing.
- [FileCard](https://magicaf.intracav.ai/docs/lumen-ui/components/media/file-card/): File attachment card showing name, type, size, and download link.
- [PdfViewer](https://magicaf.intracav.ai/docs/lumen-ui/components/media/pdf-viewer/): PDF document display card with title and page count metadata.
- [HtmlEmbed](https://magicaf.intracav.ai/docs/lumen-ui/components/media/html-embed/): HTML content preview card for rendering external pages or inline HTML safely.

#### Feedback & Status

Components for alerts, progress indicators, status badges, and empty states.

- [Feedback & Status (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/components/feedback/)
- [Alert](https://magicaf.intracav.ai/docs/lumen-ui/components/feedback/alert/): Alert banner with variant-based styling for info, warning, error, and success states.
- [Callout](https://magicaf.intracav.ai/docs/lumen-ui/components/feedback/callout/): Highlighted information callout with optional children for rich content.
- [Badge](https://magicaf.intracav.ai/docs/lumen-ui/components/feedback/badge/): Inline label or tag for categorization and status indication.
- [Progress](https://magicaf.intracav.ai/docs/lumen-ui/components/feedback/progress/): Progress bar for visualizing completion percentage.
- [StatusBadge](https://magicaf.intracav.ai/docs/lumen-ui/components/feedback/status-badge/): Status indicator dot with label for presence and state display.
- [EmptyState](https://magicaf.intracav.ai/docs/lumen-ui/components/feedback/empty-state/): Placeholder for empty content areas with optional call-to-action.

#### AI / Chat

Components for rendering AI agent interactions — tool calls, reasoning blocks, source citations, follow-up suggestions, and streaming text.

- [AI / Chat (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/components/ai/)
- [ToolCall](https://magicaf.intracav.ai/docs/lumen-ui/components/ai/tool-call/): Compact badge/card displaying an AI tool invocation with status, arguments, and duration.
- [ToolResult](https://magicaf.intracav.ai/docs/lumen-ui/components/ai/tool-result/): Labeled container wrapping tool output content with status and summary.
- [ThinkingBlock](https://magicaf.intracav.ai/docs/lumen-ui/components/ai/thinking-block/): Collapsible block showing AI reasoning and chain-of-thought text.
- [FollowUp](https://magicaf.intracav.ai/docs/lumen-ui/components/ai/follow-up/): Row of tappable suggestion buttons for follow-up questions.
- [SourceCard](https://magicaf.intracav.ai/docs/lumen-ui/components/ai/source-card/): Citation card displaying a source document with title, snippet, and relevance score.
- [StreamingText](https://magicaf.intracav.ai/docs/lumen-ui/components/ai/streaming-text/): Text display with blinking cursor for streaming AI responses.

### Integration

How Lumen UI connects to LLMs, servers, and rendering surfaces — prompt injection, artifact adapters, the envelope protocol, and integration points.

- [Integration (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/integration/)
- [LLM Integration](https://magicaf.intracav.ai/docs/lumen-ui/integration/llm-integration/): How the Lumen UI component catalog is generated and injected into LLM system prompts so the LLM knows how to render rich UI.
- [Envelope Protocol](https://magicaf.intracav.ai/docs/lumen-ui/integration/envelope-protocol/): The __lumen__ envelope format used by MCP tools on the server to send structured component data to the client.
- [Artifact Adapter](https://magicaf.intracav.ai/docs/lumen-ui/integration/artifact-adapter/): How the ArtifactAdapter converts 30+ legacy artifact types — from RxNorm lookups to FHIR resources — into renderable Lumen component trees.
- [Rendering Surfaces](https://magicaf.intracav.ai/docs/lumen-ui/integration/rendering-surfaces/): The five places in the Lumen application where Lumen UI components are rendered — chat, artifacts, agents, workflows, and blueprints.

### Advanced

Advanced Lumen UI topics — full language specification, composition patterns, custom components, and error handling.

- [Advanced (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/advanced/)
- [Language Specification](https://magicaf.intracav.ai/docs/lumen-ui/advanced/language-specification/): Formal grammar, token types, and parsing rules for the Lumen DSL.
- [Composition Patterns](https://magicaf.intracav.ai/docs/lumen-ui/advanced/composition-patterns/): Proven patterns for composing Lumen UI components into dashboards, clinical summaries, comparisons, and other complex layouts.
- [Custom Components](https://magicaf.intracav.ai/docs/lumen-ui/advanced/custom-components/): How to create, register, and expose new Lumen UI components to the LLM.
- [Error Handling](https://magicaf.intracav.ai/docs/lumen-ui/advanced/error-handling/): How Lumen UI handles errors at every level — parse errors, render errors, unknown components, and malformed props.

### API Reference

Dart API reference for Lumen UI core classes — parser, renderer, registry, node model, theme, and render context.

- [API Reference (section hub)](https://magicaf.intracav.ai/docs/lumen-ui/api-reference/)
- [LumenParser](https://magicaf.intracav.ai/docs/lumen-ui/api-reference/lumen-parser/): API reference for LumenParser — the auto-detecting parser that handles both DSL and JSON input formats.
- [LumenRenderer](https://magicaf.intracav.ai/docs/lumen-ui/api-reference/lumen-renderer/): API reference for LumenRenderer — the top-level widget that converts LumenNode trees into Flutter widgets.
- [ComponentRegistry](https://magicaf.intracav.ai/docs/lumen-ui/api-reference/component-registry/): API reference for ComponentRegistry — the singleton registry of all component definitions with catalog generation.
- [LumenNode](https://magicaf.intracav.ai/docs/lumen-ui/api-reference/lumen-node/): API reference for LumenNode — the data model for parsed component nodes with typed prop accessors.
- [LumenThemeData](https://magicaf.intracav.ai/docs/lumen-ui/api-reference/lumen-theme-data/): API reference for LumenThemeData — the theme data structure with colors, typography, chart palettes, and factory constructors.
- [LumenRenderContext](https://magicaf.intracav.ai/docs/lumen-ui/api-reference/render-context/): API reference for LumenRenderContext — the context object carrying action dispatch, streaming state, and rendering depth.

## Other Documentation Pages

- [Learning Paths](https://magicaf.intracav.ai/docs/learning-paths/): Curated reading sequences for new users, decision-makers, and production engineers.

## Sister sites

- [Intracav](https://intracav.ai): the clinical AI platform company behind MagicAF. AI-friendly index: [/llms.txt](https://intracav.ai/llms.txt).
- [Lumen docs](https://docs.intracav.ai): end-user documentation for Lumen, the clinical AI platform built on MagicAF.
- [Lumen](https://lumen.intracav.ai): the clinical AI app — chat, agents, workflows. Free for individual clinicians.
- [The Clinical Database](https://clinical-database.com): open, citation-friendly clinical reference site. AI-friendly index: [/llms.txt](https://clinical-database.com/llms.txt).
- [qPolicy](https://qpolicy.ai): hospital policy management and compliance platform with a dedicated org-wide Lumen instance. AI-friendly: [/llms.txt](https://qpolicy.ai/llms.txt).

## Feeds

- Full text: https://magicaf.intracav.ai/llms-full.txt
- Sitemap: https://magicaf.intracav.ai/sitemap.xml
- Robots: https://magicaf.intracav.ai/robots.txt
- AI/TDM policy: https://magicaf.intracav.ai/.well-known/ai.txt
- RSS: https://magicaf.intracav.ai/index.xml

## Citation guidelines

- Use the canonical URL of the specific page.
- Credit "MagicAF (Intracav)" when citing framework capabilities or documentation.
- Content is free to read, quote, and cite without registration.
- For long quotations, link back to the source page.
- Code is open source: https://github.com/magicaf/magicaf.

## Contact

- General: hello@intracav.ai
- Site: https://magicaf.intracav.ai
- GitHub: https://github.com/magicaf/magicaf
- Parent: Intracav (https://intracav.ai)