feat(rag): hybrid retrieval + multilingual refinements on top of vector RAG (#246)

> **Stacked on `feat/221-rag-sources`.** Base this PR against that
branch, not `main`, and merge it after the base lands. The diff here is
only the retrieval-quality layer (~16 files); everything else belongs to
the base PR.

Turns the vector-only baseline into hybrid retrieval and adds the
language refinements. Same on-device guarantee — nothing new leaves the
device; this is purely a quality upgrade to how chunks are found and
ranked.

## What it adds on top of the baseline

- **Keyword index** (`database/keywordIndex.ts`) — a parallel FTS5/BM25
table keyed by the same `documentId:chunkIndex` chunk id, built
alongside the vector index and torn down with it. On first launch after
upgrading from the vector baseline it **backfills from the existing
`vectors` table**, so documents imported before this PR become
keyword-searchable without a re-import.
- **Hybrid retrieval** (`utils/hybridRetrieval.ts`, replacing the
vanilla `retrieve`) — semantic vector search + keyword BM25, fused with
Reciprocal Rank Fusion, then re-ranked (term-coverage boost → MMR
diversification → adaptive-k) before neighbor expansion.
- **Multilingual no-answer detection** — Polish refusal patterns added
to the existing English ones, so a PL "brak informacji" reply cites
nothing instead of over-citing.
- **`HybridRetriever`** — the app↔library boundary: a thin wrapper
binding store + embeddings into one `retrieve(query, options)` call.

## Why hybrid (the evidence)

BM25 recovers exact-match recall — names, codes, rare tokens — that
embeddings miss; vectors recover paraphrase. An offline eval harness
(real LFM 2.5 + FTS5, frozen embeddings, ~1000 queries) confirms hybrid
beats pure vector on exact and mixed queries, at parity on
pure-paraphrase. RRF fuses the two rankings without tuning a per-query
linear weight. The semantic floor those numbers were measured against
(`0.40` + `0.25` top-keep floor) is the calibrated gate that ships in
the base PR, so the measured recall is what this branch actually
delivers.

> Re-run the on-device eval before merging: the keyword stemming
(`utils/queryTerms.ts`) and the RRF/coverage/adaptive-k knobs are
exactly what the harness measures, so any tuning here should be
revalidated against it rather than trusted on unit tests alone.

## Key decisions / trade-offs

- **No cross-encoder re-ranker.** Re-ranking is RRF + term-coverage +
MMR + adaptive-k — all cheap and on-device. A cross-encoder would
improve precision but costs a second model and per-candidate inference
on a phone.
- **`HybridRetriever` has no interface and no generic.** One
implementation, one caller. Notably *not* `implements VectorStore`: the
hybrid is read-only and its `ContextChunk` output drops id/embedding, so
coercing it to a `QueryResult` would change results. Extract an
interface when a second retriever appears.
- **Retrieval constants live in `constants/retrieval.ts`** with
per-value rationale — the fusion weights, MMR lambda, coverage alpha,
adaptive-k ratios and semantic floor each document where the number
comes from.

## Known limitations

- **FTS5 degradation is soft.** If the native build lacks FTS5,
`ensureKeywordIndex` logs a warning and hybrid search silently falls
back to vector-only. Open question: leave as-is / surface a signal /
fail fast — depends on whether a supported build without FTS5 exists.
- **Query processing is PL/EN-tuned.** `utils/queryTerms.ts` hardcodes
Polish morphology (ł/Ł folding, stem-prefix) and the no-answer detection
is PL/EN. Other languages work but retrieve measurably worse. Follow-up:
a `LanguageAdapter` with a neutral fallback.

## How to test locally

1. **Exact-match win** — attach a doc containing a rare token (an error
code, a surname) and query it verbatim; the chunk should surface even
when semantic similarity alone would gate it out.
2. **PL refusal** — ask (in Polish) something the docs don't cover;
expect a no-answer reply with zero citations.
3. **Diversity** — a spanning multi-doc query should not return five
near-duplicate chunks from one file (MMR + per-file cap).
4. **FTS5 fallback** — on a build without FTS5, retrieval still returns
results (vector-only) with a logged warning.
5. **Backfill after upgrade** — open a build that imported documents on
the vector baseline, then upgrade to this branch; the pre-existing
documents are keyword-searchable (verbatim rare-token query surfaces
them) with no re-import.

---------
Co-authored-by: Norbert Klockiewicz <Nklockiewicz12@gmail.com>

Author: kfaracik

__mocks__/@gorhom/bottom-sheet.tsx

@@ -1,14 +1,53 @@
-import React from 'react';
-import { View, FlatList } from 'react-native';
+import React, { forwardRef, type PropsWithChildren } from 'react';
+import {
+  View,
+  FlatList,
+  type FlatListProps,
+  type ScrollViewProps,
+  type ViewProps,
+} from 'react-native';
 
-export const BottomSheetModal = React.forwardRef(
-  ({ children }: any, _ref: any) => <>{children}</>
-);
-export const BottomSheetView = ({ children, style }: any) => (
+export interface BottomSheetModalRef {
+  present: () => void;
+  dismiss: () => void;
+}
+
+export type SheetAnimationConfig = Record<string, number | boolean>;
+
+export const BottomSheetModal = forwardRef<
+  BottomSheetModalRef,
+  PropsWithChildren
+>(({ children }, _ref) => <>{children}</>);
+BottomSheetModal.displayName = 'BottomSheetModal';
+
+export const BottomSheetView = ({ children, style }: ViewProps) => (
   <View style={style}>{children}</View>
 );
-export const BottomSheetFlatList = (props: any) => <FlatList {...props} />;
+
+export const BottomSheetScrollView = ({
+  children,
+  contentContainerStyle,
+  testID,
+}: ScrollViewProps) => (
+  <View style={contentContainerStyle} testID={testID}>
+    {children}
+  </View>
+);
+
+export const BottomSheetFlatList = <ItemT,>(props: FlatListProps<ItemT>) => (
+  <FlatList {...props} />
+);
+
 export const BottomSheetBackdrop = () => null;
-export const BottomSheetModalProvider = ({ children }: any) => <>{children}</>;
-export const useBottomSheetTimingConfigs = (_config: any) => ({});
-export const useBottomSheetSpringConfigs = (_config: any) => ({});
+
+export const BottomSheetModalProvider = ({ children }: PropsWithChildren) => (
+  <>{children}</>
+);
+
+export const useBottomSheet = () => ({ close: () => {} });
+
+export const useBottomSheetTimingConfigs = (config: SheetAnimationConfig) =>
+  config;
+
+export const useBottomSheetSpringConfigs = (config: SheetAnimationConfig) =>
+  config;

__mocks__/react-native-executorch-expo-resource-fetcher.ts

@@ -1,4 +1,6 @@
 export const ExpoResourceFetcher = {
   cancelFetching: jest.fn(),
   deleteResources: jest.fn(),
+  listDownloadedFiles: jest.fn(async () => [] as string[]),
+  getFilesTotalSize: jest.fn(async () => 0),
 };

__mocks__/react-native-reanimated.ts

@@ -76,6 +76,7 @@ module.exports = {
     inOut: (fn: any) => fn,
     out: (fn: any) => fn,
     in: (fn: any) => fn,
+    bezier: () => (t: any) => t,
   },
   interpolate: (val: any, inputRange: any, outputRange: any) => {
     if (val <= inputRange[0]) return outputRange[0];

__tests__/ChatBar.test.tsx

@@ -1,8 +1,15 @@
 import React from 'react';
 import { render, screen, fireEvent, act } from '@testing-library/react-native';
+import type { LLMStore } from '../store/llmStore';
+import type { Attachment } from '../hooks/useAttachment';
+import type { PermissionStatus } from 'react-native-audio-api';
 
 // ── mocks ─────────────────────────────────────────────────────────────────────
 
+const mockRunWithModelOffloaded = jest.fn(
+  async (operation: () => Promise<unknown>) => operation()
+);
+
 jest.mock('../context/ThemeContext', () => ({
   useTheme: () => ({
     theme: {
@@ -13,17 +20,22 @@ jest.mock('../context/ThemeContext', () => ({
 }));
 
 jest.mock('../store/llmStore', () => ({
-  useLLMStore: jest.fn(() => ({
-    isGenerating: false,
-    isProcessingPrompt: false,
-    interrupt: jest.fn(),
-    loadModel: jest.fn(),
-    model: null,
-  })),
+  useLLMStore: jest.fn((selector?: (state: Partial<LLMStore>) => unknown) => {
+    const state = {
+      isGenerating: false,
+      isProcessingPrompt: false,
+      interrupt: jest.fn(),
+      loadModel: jest.fn(),
+      model: null,
+      runWithModelOffloaded:
+        mockRunWithModelOffloaded as unknown as LLMStore['runWithModelOffloaded'],
+    };
+    return selector ? selector(state) : state;
+  }),
 }));
 
 const mockUseAttachment = {
-  attachments: [] as any[],
+  attachments: [] as Attachment[],
   sheetRef: { current: null },
   pickFromLibrary: jest.fn(),
   pickFromCamera: jest.fn(),
@@ -45,7 +57,12 @@ jest.mock('../components/bottomSheets/AttachmentSheet', () => {
     onPickFromCamera,
     onPickDocument,
     isVisionModel,
-  }: any) => (
+  }: {
+    onPickFromLibrary: () => void;
+    onPickFromCamera: () => void;
+    onPickDocument: () => void;
+    isVisionModel: boolean;
+  }) => (
     <View testID="attachment-sheet">
       <Text>{`vision:${isVisionModel}`}</Text>
       <TouchableOpacity testID="pick-library-btn" onPress={onPickFromLibrary}>
@@ -63,7 +80,13 @@ jest.mock('../components/bottomSheets/AttachmentSheet', () => {
 
 jest.mock('../components/chat-screen/AttachmentThumbnail', () => {
   const { View, TouchableOpacity, Text } = require('react-native');
-  return ({ attachment, onRemove }: any) => (
+  return ({
+    attachment,
+    onRemove,
+  }: {
+    attachment: Attachment;
+    onRemove: () => void;
+  }) => (
     <View testID={`attachment-thumb-${attachment.id}`}>
       <Text>{attachment.name || attachment.uri}</Text>
       <TouchableOpacity
@@ -77,8 +100,14 @@ jest.mock('../components/chat-screen/AttachmentThumbnail', () => {
 });
 
 jest.mock('../components/chat-screen/ChatSpeechInput', () => {
-  const { View, TouchableOpacity, Text } = require('react-native');
-  return ({ onSubmit, onCancel }: any) => (
+  const { View, TouchableOpacity } = require('react-native');
+  return ({
+    onSubmit,
+    onCancel,
+  }: {
+    onSubmit: (transcript: string) => void;
+    onCancel: () => void;
+  }) => (
     <View testID="speech-input">
       <TouchableOpacity
         testID="speech-submit"
@@ -91,7 +120,7 @@ jest.mock('../components/chat-screen/ChatSpeechInput', () => {
 
 jest.mock('../components/chat-screen/PromptSuggestions', () => {
   const { TouchableOpacity, Text } = require('react-native');
-  return ({ onSelectPrompt }: any) => (
+  return ({ onSelectPrompt }: { onSelectPrompt: (prompt: string) => void }) => (
     <TouchableOpacity
       testID="prompt-suggestion"
       onPress={() => onSelectPrompt('Suggested prompt')}
@@ -114,7 +143,18 @@ jest.mock('../components/chat-screen/ChatBarActions', () => {
     onThinkingToggle,
     thinkingEnabled,
     onAttach,
-  }: any) => (
+  }: {
+    userInput: string;
+    hasAttachments: boolean;
+    onSend: () => void;
+    isGenerating: boolean;
+    isProcessingPrompt: boolean;
+    onInterrupt: () => void;
+    onSpeechInput: () => void;
+    onThinkingToggle: () => void;
+    thinkingEnabled: boolean;
+    onAttach: () => void;
+  }) => (
     <View testID="chat-bar-actions">
       <TouchableOpacity testID="attach-btn" onPress={onAttach}>
         <Text>+</Text>
@@ -175,7 +215,7 @@ const defaultProps = {
   onSelectModel: jest.fn(),
   onSelectPrompt: jest.fn(),
   model: downloadedModel,
-  scrollRef: { current: null } as any,
+  scrollRef: { current: null },
   isAtBottom: true,
   isVisionModel: false,
   thinkingEnabled: false,
@@ -187,23 +227,31 @@ const renderBar = (props: Partial<typeof defaultProps> = {}) =>
   render(<ChatBar {...defaultProps} {...props} />);
 
 beforeEach(() => {
-  mockUseLLMStore.mockReturnValue({
-    isGenerating: false,
-    isProcessingPrompt: false,
-    interrupt: jest.fn(),
-    loadModel: jest.fn(),
-    model: null,
-  });
+  mockUseLLMStore.mockImplementation(
+    (selector?: (state: Partial<LLMStore>) => unknown) => {
+      const state = {
+        isGenerating: false,
+        isProcessingPrompt: false,
+        interrupt: jest.fn(),
+        loadModel: jest.fn(),
+        model: null,
+        runWithModelOffloaded:
+          mockRunWithModelOffloaded as unknown as LLMStore['runWithModelOffloaded'],
+      };
+      return selector ? selector(state) : state;
+    }
+  );
   mockUseAttachment.attachments = [];
   mockUseAttachment.openSheet.mockClear();
   mockUseAttachment.clearAll.mockClear();
   mockUseAttachment.removeAttachment.mockClear();
+  mockRunWithModelOffloaded.mockClear();
   jest.clearAllMocks();
   jest.spyOn(console, 'error').mockImplementation(() => {});
   jest.spyOn(console, 'warn').mockImplementation(() => {});
   // Default: permission granted
   mockAudioManager.requestRecordingPermissions.mockResolvedValue(
-    'Granted' as any
+    'Granted' as PermissionStatus
   );
 });
 
@@ -293,26 +341,36 @@ describe('downloaded model — text input', () => {
 
 describe('generating state', () => {
   it('shows interrupt button when isGenerating', () => {
-    mockUseLLMStore.mockReturnValue({
-      isGenerating: true,
-      isProcessingPrompt: false,
-      interrupt: jest.fn(),
-      loadModel: jest.fn(),
-      model: null,
-    });
+    mockUseLLMStore.mockImplementation(
+      (selector?: (state: Partial<LLMStore>) => unknown) => {
+        const state = {
+          isGenerating: true,
+          isProcessingPrompt: false,
+          interrupt: jest.fn(),
+          loadModel: jest.fn(),
+          model: null,
+        };
+        return selector ? selector(state) : state;
+      }
+    );
     renderBar();
     expect(screen.getByTestId('interrupt-btn')).toBeTruthy();
   });
 
   it('calls interrupt when interrupt button is pressed', () => {
     const interrupt = jest.fn();
-    mockUseLLMStore.mockReturnValue({
-      isGenerating: true,
-      isProcessingPrompt: false,
-      interrupt,
-      loadModel: jest.fn(),
-      model: null,
-    });
+    mockUseLLMStore.mockImplementation(
+      (selector?: (state: Partial<LLMStore>) => unknown) => {
+        const state = {
+          isGenerating: true,
+          isProcessingPrompt: false,
+          interrupt,
+          loadModel: jest.fn(),
+          model: null,
+        };
+        return selector ? selector(state) : state;
+      }
+    );
     renderBar();
     fireEvent.press(screen.getByTestId('interrupt-btn'));
     expect(interrupt).toHaveBeenCalled();
@@ -332,7 +390,7 @@ describe('speech input', () => {
 
   it('shows toast and stays in text mode when microphone permission is denied', async () => {
     mockAudioManager.requestRecordingPermissions.mockResolvedValue(
-      'Denied' as any
+      'Denied' as PermissionStatus
     );
     renderBar();
     await act(async () => {
@@ -405,7 +463,7 @@ describe('speech input', () => {
     // Override speech mock to submit empty string
     jest.mock('../components/chat-screen/ChatSpeechInput', () => {
       const { View, TouchableOpacity } = require('react-native');
-      return ({ onSubmit }: any) => (
+      return ({ onSubmit }: { onSubmit: (transcript: string) => void }) => (
         <View testID="speech-input">
           <TouchableOpacity
             testID="speech-submit"
@@ -434,9 +492,15 @@ describe('attachment', () => {
     expect(screen.getByTestId('attach-btn')).toBeTruthy();
   });
 
-  it('opens attachment sheet when + button is pressed', () => {
+  it('offloads the LLM before opening the attachment sheet', async () => {
     renderBar();
-    fireEvent.press(screen.getByTestId('attach-btn'));
+    await act(async () => {
+      fireEvent.press(screen.getByTestId('attach-btn'));
+    });
+    expect(mockRunWithModelOffloaded).toHaveBeenCalledWith(
+      expect.any(Function),
+      { restore: false }
+    );
     expect(mockUseAttachment.openSheet).toHaveBeenCalled();
   });