Codex/flutter gemma integration points

.gitignore

@@ -61,8 +61,12 @@ example/assets/backup_onnx/
 # Python scripts (local tooling only)
 scripts/*.py
 
-# Validation artifacts / corpora (local only)
+# Validation artifacts / corpora / generated reports (local only)
 artifacts/
+docs/reports/*.html
+docs/perf/ondevice-query-profiler/GOALS-P5-*.md
+docs/perf/ondevice-query-profiler/PR-P5-[2-9]*.html
+docs/perf/ondevice-query-profiler/artifacts/
 example/assets/corpus/
 example/assets/evalsets/
 example/assets/sample_data/*.pdf
@@ -71,3 +75,10 @@ example/assets/sample_data/*.pdf
 
 # Example evaluation/performance runners (local only)
 example/lib/*_runner.dart
+example/lib/profiling/relevance_evalset.dart
+example/lib/profiling/relevance_metrics.dart
+example/test/profiling/relevance_evalset_test.dart
+example/test/profiling/relevance_metrics_test.dart
+example/integration_test/hybrid_relevance_measure_test.dart
+example/integration_test/hybrid_passage_relevance_measure_test.dart
+example/integration_test/pdf_to_rag_passage_measure_test.dart

README.md

@@ -1,14 +1,21 @@
 # Mobile RAG Engine
 
+**Build local, on-device RAG in Flutter with a Dart package.**
+
+Mobile RAG Engine is a Flutter package for local Retrieval-Augmented Generation
+(RAG): ingest local documents, chunk and embed them on-device, then run hybrid
+semantic + keyword search through a Dart API. No server, no API cost, no network
+round-trip for retrieval.
+
 ![pub package](https://img.shields.io/pub/v/mobile_rag_engine)
 ![flutter](https://img.shields.io/badge/Flutter-3.9%2B-blue)
 ![rust](https://img.shields.io/badge/Core-Rust-orange)
 ![platform](https://img.shields.io/badge/Platform-iOS%20|%20Android%20|%20macOS-lightgrey)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Production-ready, fully local RAG (Retrieval-Augmented Generation) engine for Flutter.**
-
-Powered by a **Rust core**, it runs vector search and embedding generation directly on the device. No servers, no API costs, no network round-trips.
+Use it when you need a **Flutter local RAG engine** for private notes, document
+Q&A, chat with PDF, offline assistants, or enterprise apps where user data must
+stay on the device.
 
 ---
 
@@ -30,6 +37,21 @@ This package includes **pre-compiled binaries** for iOS, Android, and macOS. Jus
 
 > Numbers vary by device and corpus. See [`benchmark_service`](https://github.com/dev07060/mobile_rag_engine/blob/main/lib/services/benchmark_service.dart) and the `0.18.0` retrieval-hot-path notes in [CHANGELOG.md](https://github.com/dev07060/mobile_rag_engine/blob/main/CHANGELOG.md) for measured deltas on your own hardware.
 
+### Supported and Verified Scope
+
+| Area | Current status | Evidence / boundary |
+|:-----|:---------------|:--------------------|
+| **Local Flutter RAG retrieval** | Supported | Dart facade over a Rust core for ingest, chunking, embedding, SQLite storage, HNSW vector search, BM25 keyword search, RRF fusion, and context assembly |
+| **Offline / on-device operation** | Supported | Models and user documents stay local after you bundle the ONNX model and tokenizer assets |
+| **Hybrid source retrieval** | Verified on benchmark fixtures | 80-source balanced profile run: `source_recall@10 = 1.000` for shipped `default_hybrid` |
+| **Passage/context retrieval** | Verified on benchmark fixtures | 80-query passage run: `passage_recall@10 = 0.925`, `answerable_context@10 = 0.938`; semantic passage misses remain the main improvement area |
+| **Text-layer PDF-to-RAG** | Verified on sample scope | `sample_eng.pdf` and `sample_kor.pdf` profile run: 8/8 PDF-derived queries reached source, passage, and answerable context at top-10 |
+| **Scanned/image-only PDFs** | Detected, not OCR-processed | OCR-required PDFs are surfaced as extraction errors so your app can route to an OCR layer; OCR is not bundled in this package |
+| **Large, table-heavy, OCR-heavy PDFs** | Still being validated | Do not treat the PDF smoke result as broad PDF robustness or mobile latency/memory proof |
+
+For the implementation-oriented guide, see
+[Flutter Local RAG Engine Guide](https://github.com/dev07060/mobile_rag_engine/blob/main/docs/local-rag-engine.md).
+
 ### 100% Offline & Private
 
 Data never leaves the user's device. Perfect for privacy-focused apps (journals, secure chats, enterprise tools).
@@ -110,6 +132,7 @@ curl -L -o tokenizer.json "https://huggingface.co/sentence-transformers/all-Mini
 *   [Search Strategies](https://github.com/dev07060/mobile_rag_engine/blob/main/docs/features/search_strategies.md) - Tune ranking and retrieval.
 
 ### Guides
+*   [Flutter Local RAG Engine Guide](https://github.com/dev07060/mobile_rag_engine/blob/main/docs/local-rag-engine.md) - Build local/on-device RAG in Flutter with Dart APIs.
 *   [Quick Start](https://github.com/dev07060/mobile_rag_engine/blob/main/docs/guides/quick_start.md) - Setup in 5 minutes.
 *   [Model Setup](https://github.com/dev07060/mobile_rag_engine/blob/main/docs/guides/model_setup.md) - Choosing and downloading models.
 *   [Release Build](https://github.com/dev07060/mobile_rag_engine/blob/main/docs/guides/release_build.md) - Bundle size optimization for production.

docs/local-rag-engine.md

@@ -0,0 +1,116 @@
+# Flutter Local RAG Engine Guide
+
+This guide explains how to build local, on-device RAG in Flutter with
+`mobile_rag_engine`.
+
+Korean search intent: **Flutter 로컬 RAG 구현 방법**, **Flutter 온디바이스
+RAG 패키지**, **Dart 로컬 문서 검색**, **Flutter PDF RAG**.
+
+## What This Package Does
+
+`mobile_rag_engine` provides the retrieval layer for local RAG apps:
+
+- document ingest from local text-layer PDF, Markdown, plain text, and beta DOCX;
+- chunking and embedding on the device;
+- SQLite-backed document and chunk storage;
+- HNSW vector search plus BM25 keyword search;
+- RRF-based hybrid ranking;
+- context assembly for an LLM prompt.
+
+It does not bundle an LLM or OCR engine. Your app can pair the retrieved context
+with a local model, remote model, or custom OCR pipeline.
+
+## Basic Local RAG Flow
+
+```dart
+await MobileRag.initialize(
+  tokenizerAsset: 'assets/tokenizer.json',
+  modelAsset: 'assets/model.onnx',
+  deferIndexWarmup: true,
+);
+
+await MobileRag.instance.addDocumentFromFile(
+  '/path/to/manual.pdf',
+  name: 'manual.pdf',
+);
+
+final result = await MobileRag.instance.search(
+  'What does the manual say about setup?',
+  tokenBudget: 2000,
+);
+
+final contextForLlm = result.context.text;
+```
+
+For full setup instructions, see [Quick Start](guides/quick_start.md) and
+[Model Setup](guides/model_setup.md).
+
+## Architecture
+
+```text
+Local file / text
+  -> parser
+  -> chunker
+  -> embedding model
+  -> SQLite chunks + metadata
+  -> HNSW vector index + BM25 keyword index
+  -> hybrid retrieval
+  -> LLM-ready context
+```
+
+The public Dart API stays small while the hot path runs in Rust. This is useful
+for Flutter apps that need private local search without running a backend vector
+database.
+
+## Supported vs Still Being Validated
+
+| Area | Status | Notes |
+|:-----|:-------|:------|
+| Local document retrieval in Flutter | Supported | Use `MobileRag.initialize`, `addDocument`, `addDocumentFromFile`, and `search`. |
+| Offline semantic search | Supported | Retrieval runs locally after model/tokenizer assets are bundled. |
+| Hybrid search | Supported and benchmarked | HNSW vector search, BM25 keyword search, and RRF fusion are available through the default hybrid path. |
+| Passage/context retrieval quality | Verified on benchmark fixtures | The 80-query passage benchmark measured `passage_recall@10 = 0.925` and `answerable_context@10 = 0.938` for the shipped default hybrid profile. |
+| Text-layer PDF-to-RAG | Verified on sample scope | The PDF-to-RAG smoke run covered `sample_eng.pdf` and `sample_kor.pdf`; all 8 PDF-derived queries reached source, passage, and answerable context at top-10. |
+| Scanned/image-only PDFs | Detected, OCR not bundled | Extraction errors are classified as OCR-required so your UI can route to an OCR workflow. |
+| Large/table-heavy/OCR-heavy PDFs | Still being validated | Do not generalize the two-sample PDF smoke result to every PDF layout or mobile memory/latency condition. |
+| LLM generation | App responsibility | This package returns context; your app chooses the LLM. |
+
+## PDF-to-RAG Boundary
+
+The current PDF claim should be worded narrowly:
+
+> In a profile-mode macOS run, `sample_eng.pdf` and `sample_kor.pdf` were parsed
+> through the real PDF parser and `addDocumentFromFile()`. The shipped default
+> hybrid profile retrieved the expected source, answer-bearing passage, and
+> assembled context for 8/8 PDF-derived queries at top-10.
+
+The current PDF claim should not be expanded to:
+
+> All PDF document processing quality is validated.
+
+Scanned/image-only PDFs require OCR before indexing. Table-heavy PDFs, very
+large reports, layout-noisy documents, and mobile latency/memory behavior should
+be validated separately.
+
+## When To Use It
+
+Use this package when you want:
+
+- a local RAG engine inside a Flutter app;
+- private document search without uploading user data;
+- chat-with-document or chat-with-PDF retrieval;
+- on-device semantic search with keyword fallback;
+- a Dart API over a Rust retrieval core.
+
+Use a server-side RAG stack instead when you need centralized multi-user
+indexing, managed OCR at scale, or large shared vector databases.
+
+## Related Docs
+
+- [README](../README.md)
+- [Quick Start](guides/quick_start.md)
+- [Search Strategies](features/search_strategies.md)
+- [Search by Source](features/search_by_source.md)
+- [Troubleshooting](guides/troubleshooting.md)
+- [P5-4 Expanded Passage Relevance Report](perf/ondevice-query-profiler/PR-P5-4-expanded-passage-relevance.html)
+- [P5-5 PDF-to-RAG Passage Relevance Report](perf/ondevice-query-profiler/PR-P5-5-pdf-to-rag-passage-relevance.html)

lib/mobile_rag_engine.dart

@@ -50,6 +50,7 @@ export 'services/rag_engine.dart';
 export 'services/context_builder.dart';
 export 'services/source_rag_service.dart';
 export 'services/embedding_service.dart';
+export 'services/mobile_rag_vector_store.dart';
 export 'services/benchmark_service.dart';
 export 'services/quality_test_service.dart';
 export 'services/prompt_compressor.dart';