# ai_core_codespark

> Intent: On-device text-embedding + vector-search engine for Flutter. The foundation the other codespark AI packages build on.
> Model: quantized MiniLM (ONNX), auto-downloaded (~23 MB) and cached on first init. SHA-256 verified. No API key, no cloud.
> When to use: to generate embeddings and build custom pipelines — semantic search, classification, diversity (MMR), or a vector store — when you want the raw primitives.
> When NOT to use: if you just want ready-made search, use `semantic_search_codespark` instead.

## Quick Start
```dart
import 'package:ai_core_codespark/ai_core_codespark.dart';

// 1. Initialize (first run downloads + caches the model)
final engine = CodesparkEngine(model: ModelCatalog.miniLmL6V2);
await engine.initialize(
  onProgress: (received, total) => print('$received / $total'),
);

// 2. Embed
final vector = await engine.embed('hello world'); // Float32List, length 384
final vectors = await engine.embedBatch(['a', 'b']);
```

## Rank a list by meaning
```dart
final store = VectorStore();
final vecs = await engine.embedBatch(items);
for (var i = 0; i < items.length; i++) {
  store.add(VectorRecord(id: items[i], vector: vecs[i]));
}
final hits = store.search(await engine.embed('car'), k: 5, threshold: 0.3);
```

## Errors (write try/catch around initialize / embed)
```dart
try {
  await engine.initialize();
} on ModelDownloadOfflineException {
  // device offline — prompt to connect, then retry
} on InsufficientStorageException {
  // not enough space for the ~23 MB model
}
// EngineNotInitializedException — thrown if embed() runs before initialize()
// All extend CodesparkException.
```

## Gotchas
- `await initialize()` before any `embed()`.
- On web, construct `CodesparkEngine(useIsolate: false)` (no FFI isolates).
- The model downloads once, then the app works fully offline.
