Arya
Software Engineer / AI & ML
RAG usually means four things. Chunk the source documents, embed each chunk, store the vectors, and run similarity search at query time.
Apple's Foundation Models framework skips all four steps, no embedding API, no vector store, no chunker. Core Spotlight is what fills the gap instead, a full-text index that's been running on every device since iOS 9.
This post walks the pipeline this app actually ships, organized around the three stages a RAG system has, ingestion, retrieval, and synthesis, using Core Spotlight in place of a vector database, with the real, shipping code for each stage.
Like the multi-agent post, this one targets iOS 26. SpotlightSearchTool, Apple's convenience wrapper announced at WWDC26 alongside iOS 27, folds embedding storage and retrieval into the same Spotlight index plus a model-generated query. It is currently developer beta and does not compile against iOS 26, so it gets its own post once it ships. Everything below is CSSearchQuery and CSSearchableIndex, both long-stable APIs.
Ingestion
Ingestion is how a record gets into the system, and here that means donating a search-optimized subset of each bean profile to Spotlight, while the JSON itself remains the real record and Spotlight only ever holds a copy built for matching.
CSSearchableItemAttributeSet is a fixed vocabulary of roughly a hundred known fields, title, keywords, contentDescription, textContent, contentCreationDate, and so on. The job during ingestion is deciding which of your fields map onto which of those.
static func makeSearchableItem(from profile: BeanProfile) -> CSSearchableItem { let attrs = CSSearchableItemAttributeSet(contentType: .text) attrs.title = profile.name attrs.keywords = profile.flavorNotes.map(\.rawValue) + [profile.island.rawValue, profile.island.label, profile.subregion, profile.processingMethod.rawValue, profile.processingMethod.label, profile.acidity.rawValue + " acidity", profile.body.rawValue + " body", "moka " + profile.mokaPotSuitability.rawValue] + (profile.roastRecommendation.map { [$0.rawValue, $0.label] } ?? []) attrs.textContent = profile.searchableText return CSSearchableItem( uniqueIdentifier: profile.id, domainIdentifier: "bean-profile", attributeSet: attrs ) } func donate(_ profiles: [BeanProfile]) async throws { let items = profiles.map { profile -> CSSearchableItem in let item = Self.makeSearchableItem(from: profile) item.expirationDate = .distantFuture return item } try await index.indexSearchableItems(items) }
cuppingScore and dataSource don't fit that vocabulary, so they're left out of ingestion entirely and come back later during synthesis, through hydration rather than through search matching.
CoffeeAgent.init(resource:) -> JSONDecoder().decode([BeanProfile].self) -> profiles (source of truth, unchanged) -> BeanIndexer.donate(profiles) -> BeanIndexer.makeSearchableItem(from:), one per profile -> CSSearchableItemAttributeSet title, keywords, textContent -> index.indexSearchableItems(items) -> Spotlight's on-device index (a donated copy only)
This runs once at CoffeeAgent.init and again whenever the corpus changes.
Retrieval
Classic RAG retrieval turns the question into an embedding and searches a vector database for the nearest chunks. Retrieval here is more literal, turning the question into a Spotlight query string and matching tokens directly against what ingestion donated.
session.respond(to: "fruity beans above 1400 meters") -> LanguageModelSession (model decides searchBeanCorpus is needed) -> BeanCorpusTool.call(arguments:) -> CSSearchQuery(queryString: spotlightQuery(for:), queryContext:) -> Spotlight's on-device index -> matches title + keywords + textContent, token by token -> for try await result in query.results -> ids -> ids handed to synthesis for hydration
The query string itself is hand-built, one clause per word, matched against three fields at once.
static func spotlightQuery(for needle: String) -> String { let fields = ["title", "keywords", "textContent"] return needle .split(whereSeparator: \.isWhitespace) .map { token in let escaped = token .replacingOccurrences(of: "\\", with: "\\\\") .replacingOccurrences(of: "\"", with: "\\\"") let clauses = fields.map { "\($0) == \"\(escaped)*\"cdw" } return "(" + clauses.joined(separator: " || ") + ")" } .joined(separator: " && ") }
And this is the tool method itself, trimmed only of logging and the UI card side channel, the actual retrieval and status logic this app runs on every search.
func call(arguments: Arguments) async throws -> BeanSearchOutcome { let needle = arguments.query.trimmingCharacters(in: .whitespacesAndNewlines) guard !needle.isEmpty else { return BeanSearchOutcome(status: .noMatchesInIndex, beans: []) } guard CSSearchableIndex.isIndexingAvailable() else { return BeanSearchOutcome(status: .indexUnavailable, beans: []) } let context = CSSearchQueryContext() context.fetchAttributes = [] var ids: [String] = [] let query = CSSearchQuery(queryString: Self.spotlightQuery(for: needle), queryContext: context) defer { query.cancel() } do { for try await result in query.results { ids.append(result.item.uniqueIdentifier) if ids.count >= arguments.limit { break } } } catch { return BeanSearchOutcome(status: .indexUnavailable, beans: []) } guard !ids.isEmpty else { return BeanSearchOutcome(status: .noMatchesInIndex, beans: []) } let profiles = await store.profiles(for: ids) guard !profiles.isEmpty else { return BeanSearchOutcome(status: .indexStale, beans: []) } return BeanSearchOutcome(status: .matchesFound, beans: profiles.map(Self.hit)) }
The first half of that method, up through collecting ids, is retrieval. noMatchesInIndex means the query ran and the bean genuinely is not in the corpus.
IndexUnavailable means the query never ran at all, or Spotlight itself threw partway through.
IndexStale is the one a two-outcome design has no room for, Spotlight returned ids, but hydration found nothing for them, covered next under synthesis. That gap exists because the donated index and the in-memory store are two stores kept in sync by hand rather than one.
Spotlight can also ask the app to refresh what it holds, through a delegate, which is what keeps retrieval from drifting too far from the source of truth over time.
final class BeanIndexDelegate: NSObject, CSSearchableIndexDelegate { let store: BeanProfileStore func searchableIndex( _ index: CSSearchableIndex, reindexSearchableItemsWithIdentifiers identifiers: [String], acknowledgementHandler ack: @escaping () -> Void ) { Task { try? await BeanIndexer().donate(await store.profiles(for: identifiers)) ack() } } func searchableIndex( _ index: CSSearchableIndex, reindexAllSearchableItemsWithAcknowledgementHandler ack: @escaping () -> Void ) { Task { try? await BeanIndexer().donate(await store.allProfiles()) ack() } } }
Spotlight calls this off the main thread onschedule. The delegate exists so the system can ask for a re-donation without the app polling to check whether its index is still fresh.
Synthesis
Synthesis is the second half of that same method, the part that turns bare ids into something the model can reason about and answer with.
@Generable struct BeanHit { var name: String var island: String var subregion: String var processing: String var flavors: String var acidity: String var body: String var roastRecommendation: String? var mokaPotSuitability: String var cuppingScore: Double? var dataSource: String } @Generable struct BeanSearchOutcome { var status: BeanSearchStatus var beans: [BeanHit] } static func hit(for profile: BeanProfile) -> BeanHit { BeanHit( name: profile.name, island: profile.island.label, subregion: profile.subregion, processing: profile.processingMethod.label, flavors: profile.flavorNotes.map(\.label).joined(separator: ", "), acidity: profile.acidity.label, body: profile.body.label, roastRecommendation: profile.roastRecommendation?.label, mokaPotSuitability: profile.mokaPotSuitability.label, cuppingScore: profile.cuppingScore, dataSource: profile.dataSource.label ) }
ids from retrieval -> BeanProfileStore.profiles(for: ids), hydrated directly, no delegate callback -> empty means indexStale, the two stores disagreed -> BeanSearchOutcome(status: .matchesFound, beans: profiles.map(Self.hit)) -> model reasons over named BeanHit fields -> response.content, cited by bean name
Ranking is already settled by the time synthesis runs. Spotlight's token match decided what came back during retrieval, so synthesis here is mostly hydration, turning bare ids into full, typed records with fields the model can reason over by name.
Why this beats hand rolling a vector store on device
An embedding based RAG pipeline needs a model to embed with, storage for the vectors, and a similarity search over them, three things you would have to ship yourself, none of which Foundation Models provides.
Core Spotlight already runs on the device, already does full-text token matching, and if the app already donates content for system-wide search, most of the ingestion work above is already done regardless of which retrieval path gets built on top of it.
The trade costs real capability, semantic similarity, replaced by token and prefix matching plus whatever relevance scoring Spotlight applies during retrieval. For a bounded reference corpus like this one, where fruity and Gayo and washed are the actual vocabulary people search with, that trade is a good one. It would look different over long, unstructured documents where meaning genuinely diverges from wording.
What's next
SpotlightSearchTool on iOS 27 keeps the same ingest then retrieve shape but folds retrieval and part of synthesis into the tool itself, adds a model-generated query in place of hand-building
spotlightQuery(for:), and opens a CustomStage for scoring hits before the model sees them during synthesis. That is a different enough tool contract, built on a different enough set of types, GuidanceProfile, CoreSpotlightSource, SearchReply.