Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

- Renamed package from `react-native-apple-intelligence` to `react-native-foundation-models`.
- `streamResponse` callback now emits chunks instead of the full response.
- `LanguageModelSessionOptions` and `UseLanguageModelConfig` are now type aliases
for a union that allows `instructions` or `transcript`, not both. An
`interface` that `extends` either type no longer compiles. Use an
intersection (`type Props = LanguageModelSessionOptions & { ... }`) instead.

## [0.1.0] - 2025-09-18

Expand Down
57 changes: 52 additions & 5 deletions docs/docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,12 @@ sidebar_position: 3
Creates a new LanguageModelSession instance. Throws an error if Apple Intelligence is not available.

```typescript
constructor(config?: LanguageModelSessionConfig)
constructor(config?: LanguageModelSessionOptions)
```

**Parameters**:
- `config.instructions?: string` - System instructions defining AI behavior
- `config.transcript?: SerializedTranscript` - A transcript saved from an earlier session with `session.transcript`. The new session continues that conversation and keeps its instructions. Cannot be combined with `instructions`: TypeScript rejects it, and at runtime it throws `INVALID_SESSION_OPTIONS`. A transcript that cannot be read throws `INVALID_TRANSCRIPT`
- `config.tools?: ToolDefinition[]` - Array of tools the AI can invoke
- `config.useCase?: 'general' | 'contentTagging'` - Configures the system model use case
- `config.guardrails?: 'default' | 'permissiveContentTransformations'` - Configures Foundation Models guardrails
Expand Down Expand Up @@ -103,6 +104,17 @@ tokenCount(prompt: string): Promise<number>

**Availability**: iOS 26.4 or later. On earlier versions the returned promise rejects with an `UNSUPPORTED_PLATFORM` error.

#### `prewarm(promptPrefix?)`

Asks the system to load the model resources for this session before the first request, so the first response can start sooner. Call it when a request is likely soon, such as when a chat screen opens.

```typescript
prewarm(promptPrefix?: string): void
```

**Parameters**:
- `promptPrefix?: string` - The expected start of the next prompt, when known

### Instance Properties

#### `wasContextReset`
Expand All @@ -113,6 +125,23 @@ Boolean flag indicating whether the session's context was automatically summariz
readonly wasContextReset: boolean
```

#### `transcript`

The conversation so far, including the instructions. Each read returns the current state. After a context overflow the session is replaced by a summarized one, and `transcript` reads the replacement.

```typescript
readonly transcript: SerializedTranscript
```

```typescript
await storage.set('chat', session.transcript);

const saved = (await storage.get('chat')) as SerializedTranscript;
const restored = new LanguageModelSession({ transcript: saved, tools });
```

Tools are not stored in the transcript. Pass them again to the new session. A transcript that cannot be encoded throws `TRANSCRIPT_ENCODING_ERROR`.

## Functions

### `checkFoundationModelsAvailability()`
Expand Down Expand Up @@ -155,6 +184,7 @@ function useLanguageModel(config?: UseLanguageModelConfig): UseLanguageModelRetu

**Parameters**:
- `config.instructions?: string` - System instructions for the AI
- `config.transcript?: SerializedTranscript` - A saved transcript to continue. Cannot be combined with `instructions`
- `config.tools?: ToolDefinition[]` - Tools the AI can use
- `config.onResponse?: (response: string) => void` - Callback for responses
- `config.onError?: (error: AppleAIError) => void` - Callback for errors
Expand Down Expand Up @@ -263,17 +293,31 @@ type DeepPartial<T> = T extends string
: T;
```

### `LanguageModelSessionConfig`
### `LanguageModelSessionOptions`

```typescript
interface LanguageModelSessionConfig {
instructions?: string;
type LanguageModelSessionOptions = {
tools?: ToolDefinition[];
useCase?: 'general' | 'contentTagging';
guardrails?: 'default' | 'permissiveContentTransformations';
}
} & (
| { instructions?: string; transcript?: never }
| { transcript: SerializedTranscript; instructions?: never }
);
```

### `SerializedTranscript`

A session transcript in Apple's `Transcript` JSON format, typed as a branded string.

```typescript
type SerializedTranscript = string & { readonly [brand]: 'SerializedTranscript' };
```

The format belongs to Apple and carries a version (`"version":"1.1"` on iOS 27). The only promise is that a value read from `session.transcript` restores through `new LanguageModelSession({ transcript })`. Do not build or edit one by hand. A value read back from storage needs a cast: `stored as SerializedTranscript`.

The decoder rejects versions, entry roles, and segment types it does not know. On iOS 27 it rejects every version other than `1.1`. A transcript that holds iOS 27-only content, such as reasoning entries or attachment segments, is therefore not expected to restore on iOS 26. Restoring on iOS 26 was not tested. Treat `INVALID_TRANSCRIPT` as a normal outcome after an OS update, and start a new session when it occurs.

### `ToolDefinition`

```typescript
Expand Down Expand Up @@ -328,6 +372,9 @@ class AppleAIError extends Error {
- `TIMEOUT` - The request timed out (iOS 27+)
- `TOKEN_COUNT_ERROR` - Token counting failed
- `INVALID_GENERATION_OPTIONS` - A `GenerationOptions` value is invalid. `details.field` names the field
- `INVALID_SESSION_OPTIONS` - The session options combine `instructions` and `transcript`
- `INVALID_TRANSCRIPT` - The `transcript` option cannot be decoded. It is not valid JSON, not a transcript, or holds a version or content this OS does not know
- `TRANSCRIPT_ENCODING_ERROR` - `session.transcript` could not encode the conversation

The same failure has the same code on iOS 26 and iOS 27.

Expand Down
80 changes: 77 additions & 3 deletions example/app/index.tsx
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
import { useCallback, useState } from 'react'
import { StyleSheet, Switch } from 'react-native'
import { StyleSheet, Switch, TouchableOpacity } from 'react-native'
import {
createTool,
type GenerationOptions,
getFoundationModelsContextSize,
LanguageModelSession,
type SerializedTranscript,
} from 'react-native-foundation-models'
import { z } from 'zod'
import { Text, useThemeColor, View } from '@/components/Themed'
Expand Down Expand Up @@ -44,13 +45,17 @@ const weatherTool = createTool({
}
},
})
const session = new LanguageModelSession({
const initialSession = new LanguageModelSession({
instructions: 'You are a helpful assistant',
tools: [weatherTool],
})
initialSession.prewarm()
const contextSize = getFoundationModelsContextSize()

export default function IndexScreen() {
const [session, setSession] = useState(initialSession)
const [savedTranscript, setSavedTranscript] = useState<SerializedTranscript>()
const [transcriptStatus, setTranscriptStatus] = useState('No transcript saved')
const [result, setResult] = useState('')
const [loading, setLoading] = useState(false)
const [tokenMetrics, setTokenMetrics] = useState<TokenMetrics>()
Expand All @@ -60,6 +65,7 @@ export default function IndexScreen() {
const mutedColor = useThemeColor({}, 'muted')
const borderColor = useThemeColor({}, 'border')
const cardColor = useThemeColor({}, 'card')
const tintColor = useThemeColor({}, 'tint')

const handleSubmit = useCallback(
async (prompt: string) => {
Expand Down Expand Up @@ -87,9 +93,36 @@ export default function IndexScreen() {
setLoading(false)
}
},
[greedy, capTokens],
[session, greedy, capTokens],
)

const saveTranscript = () => {
try {
const transcript = session.transcript
setSavedTranscript(transcript)
setTranscriptStatus(`Transcript saved (${transcript.length} chars)`)
} catch (error) {
setTranscriptStatus(`Save failed: ${(error as Error).message}`)
}
}

const restoreTranscript = () => {
if (!savedTranscript) {
return
}
try {
const restored = new LanguageModelSession({
transcript: savedTranscript,
tools: [weatherTool],
})
restored.prewarm()
setSession(restored)
setTranscriptStatus('Restored into a new session')
} catch (error) {
setTranscriptStatus(`Restore failed: ${(error as Error).message}`)
}
}

return (
<WeatherDemo
title="Foundation Models"
Expand Down Expand Up @@ -124,6 +157,35 @@ export default function IndexScreen() {
/>
</View>
</View>
<View style={[styles.card, { borderColor, backgroundColor: cardColor }]}>
<Text style={[styles.cardLabel, { color: mutedColor }]}>TRANSCRIPT</Text>
<View style={styles.buttons}>
<TouchableOpacity
testID="save-transcript"
accessibilityRole="button"
disabled={loading}
onPress={saveTranscript}
style={[styles.chip, { borderColor: tintColor, opacity: loading ? 0.4 : 1 }]}
>
<Text style={{ color: tintColor }}>Save transcript</Text>
</TouchableOpacity>
<TouchableOpacity
testID="restore-transcript"
accessibilityRole="button"
disabled={loading || !savedTranscript}
onPress={restoreTranscript}
style={[
styles.chip,
{ borderColor: tintColor, opacity: loading || !savedTranscript ? 0.4 : 1 },
]}
>
<Text style={{ color: tintColor }}>Restore</Text>
</TouchableOpacity>
</View>
<Text testID="transcript-status" style={{ color: mutedColor }}>
{transcriptStatus}
</Text>
</View>
</WeatherDemo>
)
}
Expand All @@ -150,4 +212,16 @@ const styles = StyleSheet.create({
rowLabel: {
fontSize: 15,
},
buttons: {
flexDirection: 'row',
gap: 8,
paddingVertical: 6,
backgroundColor: 'transparent',
},
chip: {
borderWidth: 1,
borderRadius: 16,
paddingHorizontal: 12,
paddingVertical: 6,
},
})
22 changes: 22 additions & 0 deletions package/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,25 @@ The schema must have `z.object` at the root and follows the same rules as tool a

The hooks return text only. Call `session.respond` or `session.streamResponse` directly for structured output.

### Saving and restoring a conversation

`session.transcript` holds the conversation so far, including the instructions. Store it, then pass it to a new session to continue the conversation later.

```typescript
import { LanguageModelSession, type SerializedTranscript } from 'react-native-foundation-models';

await storage.set('chat', session.transcript);

const saved = (await storage.get('chat')) as SerializedTranscript;
const restored = new LanguageModelSession({ transcript: saved, tools: [weatherTool] });
```

A restored session keeps the instructions from its transcript, so `instructions` and `transcript` cannot be used together. TypeScript rejects the combination, and at runtime it throws `INVALID_SESSION_OPTIONS`. Tools are not stored in the transcript. Pass them again. A transcript that cannot be read throws `INVALID_TRANSCRIPT`.

The transcript JSON format belongs to Apple and carries a version (`"version":"1.1"` on iOS 27). The decoder rejects versions, entry roles, and segment types it does not know. A transcript that holds iOS 27-only content, such as reasoning entries or attachment segments, is therefore not expected to restore on iOS 26 and fails with `INVALID_TRANSCRIPT`. Restoring on iOS 26 was not tested. Treat `INVALID_TRANSCRIPT` as a normal outcome after an OS update, and start a new session when it occurs.

Call `session.prewarm(promptPrefix?)` when a request is likely soon, for example when a chat screen opens. The system then loads the model resources before the first request.

### Using React Hooks

```typescript
Expand Down Expand Up @@ -159,6 +178,7 @@ Core class for managing AI conversations.
```typescript
constructor(config?: {
instructions?: string;
transcript?: SerializedTranscript;
tools?: Tool[];
useCase?: 'general' | 'contentTagging';
guardrails?: 'default' | 'permissiveContentTransformations';
Expand All @@ -170,6 +190,8 @@ The library now creates sessions with an explicit `SystemLanguageModel`, which l
Methods:
- `respond(prompt, options?)` - Generate a complete response and resolve when finished. With `options.schema`, resolve with the parsed object
- `streamResponse(prompt, onChunk, options?)` - Stream the response progressively. With `options.schema`, `onChunk` receives partial objects
- `prewarm(promptPrefix?)` - Load the model resources before the first request
- `transcript` - The conversation so far as a `SerializedTranscript`, to restore with `new LanguageModelSession({ transcript })`

### `useLanguageModel(config)`

Expand Down
15 changes: 10 additions & 5 deletions package/ios/AppleAIErrors.swift
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
import Foundation

public enum AppleAIError: Error, LocalizedError, CustomStringConvertible {
case sessionNotInitialized
case sessionBusy
case modelUnavailable(String)
case toolCallError(Error)
Expand All @@ -18,11 +17,11 @@ public enum AppleAIError: Error, LocalizedError, CustomStringConvertible {
case unsupportedPlatform(String)
case tokenCountError(Error)
case invalidGenerationOptions(String)
case invalidTranscript(String)
case transcriptEncodingError(Error)

public var errorDescription: String? {
switch self {
case .sessionNotInitialized:
return "Language model session is not initialized"
case .sessionBusy:
return "Another language model request is already in progress for this session"
case .modelUnavailable(let reason):
Expand Down Expand Up @@ -55,6 +54,10 @@ public enum AppleAIError: Error, LocalizedError, CustomStringConvertible {
return "Token count failed: \(error.localizedDescription)"
case .invalidGenerationOptions(let details):
return "Invalid generation options: \(details)"
case .invalidTranscript(let details):
return "Invalid transcript: \(details)"
case .transcriptEncodingError(let error):
return "Failed to encode transcript: \(error.localizedDescription)"
}
}

Expand All @@ -64,8 +67,6 @@ public enum AppleAIError: Error, LocalizedError, CustomStringConvertible {

public var code: String {
switch self {
case .sessionNotInitialized:
return "SESSION_NOT_INITIALIZED"
case .sessionBusy:
return "SESSION_BUSY"
case .modelUnavailable:
Expand Down Expand Up @@ -98,6 +99,10 @@ public enum AppleAIError: Error, LocalizedError, CustomStringConvertible {
return "TOKEN_COUNT_ERROR"
case .invalidGenerationOptions:
return "INVALID_GENERATION_OPTIONS"
case .invalidTranscript:
return "INVALID_TRANSCRIPT"
case .transcriptEncodingError:
return "TRANSCRIPT_ENCODING_ERROR"
}
}
}
Expand Down
Loading
Loading