expo-ai-core 1.0.0 → 1.0.1

package/README.md

@@ -1,162 +1,445 @@
-# expo-ai-core ⚡
+# expo-ai-core
 
-> Add AI (ChatGPT-style chat, streaming, voice) to your Expo app in **5 lines of code**
+> Production-ready AI for Expo and React Native, built for chat, streaming, voice, tools, memory, plugins, agents, and custom providers.
 
----
+`expo-ai-core` is a TypeScript-first AI SDK for Expo apps. It is designed to stay Expo Go compatible, avoid Node-only APIs, and give you a small but capable surface for shipping AI features in production.
 
-## 🚀 Why this exists
+Version 1.0.1 refreshes the model registry, provider catalogs, and documentation so the package is easier to adopt, easier to extend, and clearer to maintain.
 
-Building AI features in Expo is painful:
+## What is new in 1.0.1
 
-- Too much boilerplate
-- No streaming support
-- Voice is messy
-- UI takes forever
+- Updated model catalog ordering by release series and popularity.
+- Registry-backed provider discovery with runtime registration.
+- Lazy provider loading so unused providers do not inflate bundles.
+- Stable root exports for hooks, UI, providers, registry helpers, tools, plugins, memory, and agents.
+- More detailed documentation for config, model discovery, custom providers, and Expo-native voice support.
 
-**expo-ai-core fixes all of that.**
+## Why use expo-ai-core
 
----
+- Expo Go compatible
+- Client-side only networking using `fetch`
+- Strong TypeScript types and autocomplete-friendly APIs
+- Built-in support for chat, streaming, voice, tools, memory, plugins, and agents
+- Provider architecture inspired by the Vercel AI SDK pattern, but tailored for Expo and React Native
+- Backward compatible with existing `useAIChat` integrations
 
-## ⚡ Quick Demo
+## Install
+
+Core package:
+
+```bash
+npm install expo-ai-core
+```
+
+Recommended Expo-native peers for the full experience:
+
+```bash
+npm install expo-speech expo-av @react-native-async-storage/async-storage
+```
+
+Optional UX helpers:
+
+```bash
+npm install expo-clipboard expo-haptics
+```
+
+If you use a package manager with strict peer handling, install the optional packages up front so copy actions and haptics work without extra setup.
+
+## Quick start
 
 ```tsx
 import { AIChatView, useAIChat } from "expo-ai-core";
 
 export default function Screen() {
   const chat = useAIChat({
+    apiKey: process.env.EXPO_PUBLIC_OPENAI_API_KEY as string,
     provider: "openai",
-    apiKey: "YOUR_API_KEY",
+    model: "gpt-4o-mini",
   });
 
-  return <AIChatView {...chat} />;
+  return <AIChatView {...chat} title="Assistant" subtitle="Expo AI Core" />;
 }
 ```
 
-👉 That’s it. You now have a working AI chat UI.
+Send a message manually:
 
----
+```tsx
+await chat.sendMessage("Summarize this screen for me.");
+```
 
-## ✨ Features
+## Getting started with configuration
+
+You can set app-wide defaults once and let every hook inherit them:
+
+```tsx
+import { configureAI } from "expo-ai-core";
 
-- 🧠 **AI Chat Hook** → `useAIChat`
-- ⚡ **Streaming Responses** (real-time typing effect)
-- 🎤 **Voice Input + TTS**
-- 🔌 **Multi-Provider Support**
-  - OpenAI
-  - Google Gemini
+configureAI({
+  defaultProvider: "openai",
+  defaultModel: "gpt-4o-mini",
+  debug: false,
+  themeMode: "system",
+});
+```
 
-- 💬 **Prebuilt UI Components**
-- 💾 **Offline Cache + Persistence**
-- ⚙️ **Zero Backend Required**
-- 📦 **Tiny & Tree-shakable**
+`configureAI()` currently controls these defaults:
 
----
+- `defaultProvider`
+- `defaultModel`
+- `debug`
+- `themeMode`
 
-## 📦 Installation
+Those values are merged with per-hook overrides when you call `useAIChat()`.
 
-```bash
-npm install expo-ai-core
-npm install expo-speech expo-av @react-native-async-storage/async-storage
-```
+## Public API at a glance
 
----
+Root exports include:
 
-## 🔧 Providers
+- `useAIChat`, `useAIVoice`
+- `AIChatView`, `AIInput`, `AIMessageBubble`, `AITypingIndicator`, `MarkdownText`
+- `configureAI`, `getAIConfig`
+- `registerProvider`, `unregisterProvider`, `getProvider`, `getRegisteredProvider`, `getProviderOrThrow`, `getModels`, `listProviders`, `listRegisteredProviders`
+- `createProvider`, `createOpenAIProvider`, `createGeminiProvider`, `createAnthropicProvider`, `createGroqProvider`, `createTogetherProvider`, `createOllamaProvider`
+- `createPlugin`, `collectPluginTools`, `runPluginHandlers`
+- `createAgent`, `runAgent`
+- `parseToolCall`, `executeToolCall`, `mergeTools`, `buildToolResultMessage`
+- `lightTheme`, `darkTheme`, `resolveTheme`
+- `memory`, `tools`, and `utils` helpers
 
-### OpenAI
+## Chat
+
+`useAIChat()` is the main orchestration hook. It handles message state, streaming, retries, regeneration, tool calls, caching, multi-conversation flows, and provider switching.
 
 ```tsx
-useAIChat({
+import { useAIChat } from "expo-ai-core";
+
+const chat = useAIChat({
+  apiKey: process.env.EXPO_PUBLIC_OPENAI_API_KEY as string,
   provider: "openai",
-  apiKey: process.env.EXPO_PUBLIC_OPENAI_API_KEY!,
   model: "gpt-4o-mini",
+  systemPrompt: "You are a concise mobile assistant.",
+  typingSpeed: "normal",
+  haptics: true,
 });
 ```
 
-### Gemini
+Useful options:
+
+- `provider`, `apiKey`, `model`
+- `systemPrompt`
+- `initialMessages`
+- `cacheKey`, `enableCache`
+- `timeoutMs`
+- `tools`, `plugins`, `memory`
+- `typingSpeed`
+- `themeMode`
+- `haptics`
+- `maxToolIterations`
+- `onDebugEvent`
+- `routing: "auto"`
+
+Useful return values:
+
+- `messages`, `input`, `setInput`
+- `sendMessage()`, `isLoading`, `error`
+- `stopGenerating()`, `clearMessages()`
+- `retryLastMessage()`, `retryMessage()`
+- `regenerateResponse()`
+- `copyMessage()`
+- `generateImage()`
+- `createChat()`, `switchChat()`, `deleteChat()`, `setConversationTitle()`
+- `setProvider()`, `setModel()`, `setThemeMode()`
+- `conversations`, `currentConversationId`
+- `debugState`
+
+### Example: provider switching at runtime
 
 ```tsx
-useAIChat({
-  provider: "gemini",
-  apiKey: process.env.EXPO_PUBLIC_GEMINI_API_KEY!,
-  model: "gemini-2.5-flash",
+const chat = useAIChat({
+  apiKey: process.env.EXPO_PUBLIC_OPENAI_API_KEY as string,
+  provider: "openai",
+  model: "gpt-4o-mini",
 });
+
+chat.setProvider("gemini");
+chat.setModel("gemini-3.1-flash");
+```
+
+### Example: streaming and recovery controls
+
+```tsx
+await chat.sendMessage("Draft a release note.");
+
+chat.stopGenerating();
+await chat.retryLastMessage();
+await chat.regenerateResponse();
 ```
 
----
+## Voice
 
-## 🎤 Voice (Speech-to-Text + TTS)
+`useAIVoice()` wraps speech input and speech output in a React hook that stays Expo-friendly.
 
 ```tsx
 import { useAIVoice } from "expo-ai-core";
 
-const voice = useAIVoice();
+const voice = useAIVoice({
+  language: "en-US",
+  autoSpeak: true,
+  loop: false,
+  speechRate: 1,
+  speechPitch: 1,
+});
+```
+
+Options:
+
+- `language`
+- `continuous`
+- `interimResults`
+- `autoSpeak`
+- `speechRate`
+- `speechPitch`
+- `loop`
+- `onTranscript`
+- `onVoiceError`
+
+Return values:
+
+- `startListening()`, `stopListening()`
+- `transcript`
+- `isListening`
+- `recordingUri`
+- `error`
+- `speak()`
+- `clearTranscript()`
+
+## UI components
+
+The package includes lightweight UI primitives you can use directly or adapt into your own design system.
+
+- `AIChatView` - full chat screen composition
+- `AIInput` - message input and send control
+- `AIMessageBubble` - message rendering with copy support
+- `AITypingIndicator` - assistant typing state
+- `MarkdownText` - markdown-aware message content renderer
+
+`AIChatView` accepts the full `AIChatReturn` surface, plus optional title, subtitle, custom renderers, and theme overrides.
+
+## Providers
+
+`expo-ai-core` ships with built-in providers and a registry so you can add your own provider without modifying the package internals.
+
+Built-in providers:
+
+- OpenAI
+- Gemini
+- Anthropic
+- Groq
+- Together
+- Ollama
+
+### Provider helpers
+
+Use the built-in creator helpers if you want to assemble providers manually:
 
-await voice.startListening();
-await voice.stopListening();
-await voice.speak("Hello from Expo");
+```tsx
+import {
+  createOpenAIProvider,
+  createGeminiProvider,
+  createAnthropicProvider,
+  createGroqProvider,
+  createTogetherProvider,
+  createOllamaProvider,
+} from "expo-ai-core";
 ```
 
----
+### Registry helpers
+
+```tsx
+import {
+  registerProvider,
+  unregisterProvider,
+  getProvider,
+  getProviderOrThrow,
+  listProviders,
+  getModels,
+} from "expo-ai-core";
+```
+
+`getModels(provider)` returns the curated catalog for that provider. The lists in v1.0.1 are intentionally ordered so the most relevant models appear first.
+
+## Model catalog in v1.0.1
+
+These are the default provider model lists bundled with the package.
+
+### OpenAI
+
+`gpt-5.4`, `gpt-5.4-pro`, `gpt-5.4-mini`, `o3-thinking`, `gpt-4.1`
+
+### Gemini
+
+`gemini-3.1-pro`, `gemini-3.1-flash`, `gemini-3.1-flash-lite`, `gemini-2.5-pro`, `nano-banana-2`
+
+### Anthropic
 
-## 🧩 Components
+`claude-opus-4.6`, `claude-sonnet-4.6`, `claude-haiku-4.5`, `claude-sonnet-4.0`, `claude-mythos-preview`
 
-- `AIChatView` → full chat UI
-- `AIInput` → input box
-- `AIMessageBubble` → messages
-- `AITypingIndicator` → streaming state
+### Groq
 
-All components are:
+`llama-4-maverick`, `llama-4-scout-17b`, `llama-3.3-70b-versatile`, `qwen3-32b`, `gpt-oss-120b`
 
-- Customizable
-- NativeWind-compatible
-- Lightweight
+### Together
 
----
+`Qwen/Qwen3.5-122B`, `Mistral-4-Small`, `meta-llama/Llama-3.3-70B-Instruct-Turbo`, `deepseek-v3.2`, `meta-muse-spark`
 
-## 🧠 How it works
+### Ollama
 
-- Uses `fetch` (no backend needed)
-- Streams tokens in real-time
-- Stores chats via AsyncStorage
-- Works in Expo Go
+`llama4`, `gemma4`, `qwen3`, `mistral-large-2`, `phi-4`
 
----
+If you need a different list, register your own provider or replace the catalog at the app layer.
 
-## ⚠️ Notes
+## Custom providers
 
-- Native speech recognition requires platform support
-- Works best with Expo SDK 50+
-- No Node.js APIs used
+You can register a custom provider and keep the rest of the SDK unchanged.
 
----
+```tsx
+import { createProvider, registerProvider } from "expo-ai-core";
+
+registerProvider(
+  createProvider({
+    name: "custom",
+    sendMessage: async () => ({
+      content: "Hello from a custom provider",
+    }),
+  }),
+);
+```
+
+If you already have your own network layer, `createProvider()` is the easiest way to normalize it into the `AIProvider` interface.
+
+## Tools
+
+Tools let the model call typed local functions on-device.
+
+```tsx
+const chat = useAIChat({
+  apiKey: process.env.EXPO_PUBLIC_OPENAI_API_KEY as string,
+  tools: {
+    getLocation: async () => ({ lat: 40.7128, lng: -74.006 }),
+    getTime: () => new Date().toISOString(),
+  },
+});
+```
+
+Tool execution is handled through the package helpers and the `tools` option on `useAIChat()`.
+
+## Memory
 
-## 📱 Example App
+`memory` gives you persistence-aware conversation behavior. The bundled strategies support a rolling window and a summary mode.
 
-See `/example` for a full working demo.
+```tsx
+const chat = useAIChat({
+  apiKey: process.env.EXPO_PUBLIC_OPENAI_API_KEY as string,
+  memory: {
+    enabled: true,
+    strategy: "summary",
+    windowSize: 20,
+    maxSummaryLength: 1200,
+  },
+});
+```
 
----
+Recommended use cases:
 
-## 💡 Coming Soon
+- `window` for short lived, recent-context conversations
+- `summary` for longer sessions where you want to compress history
+
+## Plugins
+
+Plugins let you package reusable behavior, tools, and handlers.
+
+```tsx
+import { createPlugin } from "expo-ai-core";
+
+const weatherPlugin = createPlugin({
+  name: "weather",
+  tools: {
+    getWeather: async () => ({ tempC: 24, condition: "clear" }),
+  },
+});
+```
+
+Use plugins when you want to share a feature bundle across screens or products.
+
+## Agents
+
+Agents are useful for multi-step workflows that need a goal, several instructions, and optional tool execution.
+
+```tsx
+import { createAgent } from "expo-ai-core";
+
+const agent = createAgent({
+  goal: "Plan a product launch summary",
+  steps: [
+    { id: "research", instruction: "Summarize the launch context." },
+    { id: "draft", instruction: "Write a short launch brief." },
+  ],
+  provider,
+});
+```
+
+## Themes
+
+The package includes light and dark theme presets plus a small resolver helper.
+
+```tsx
+import { darkTheme, lightTheme, resolveTheme } from "expo-ai-core";
+```
+
+You can also pass partial theme overrides into `AIChatView`, `AIMessageBubble`, and related UI primitives.
+
+## Example app
+
+The local `example` folder contains an Expo integration reference app.
+
+See the demo repository here: https://github.com/ArhanAnsari/expo-ai-core-demo
+
+## Typical import patterns
+
+```tsx
+import {
+  AIChatView,
+  AIMessageBubble,
+  configureAI,
+  createProvider,
+  getModels,
+  registerProvider,
+  useAIChat,
+  useAIVoice,
+} from "expo-ai-core";
+```
 
-- Image generation support
-- Markdown + code block rendering
-- Better voice transcription
-- More providers
+## Troubleshooting
 
----
+- Make sure your provider key is available at runtime, usually through an Expo public environment variable.
+- Install the optional peers if you want clipboard, haptics, speech, or recording features.
+- If a provider is not registered, `useAIChat()` falls back to the built-in lazy loader for that provider name.
+- If you need a model that is not in the bundled catalog, register a custom provider or update the provider list in your app layer.
 
-## ⭐ Support
+## Roadmap
 
-If this helped you:
+- Structured output helpers
+- Attachment and multimodal abstractions
+- Provider capability introspection
+- More agent orchestration utilities
 
-- Star the repo ⭐
-- Share on Twitter/X
-- Build something cool 🚀
+## Contributing
 
----
+1. Fork the repo
+2. Create a feature branch
+3. Add tests and docs
+4. Open a pull request with a clear description and reproduction steps
 
-## 🧑‍💻 Author
+## License
 
-Built by Arhan Ansari
-[Twitter](https://twitter.com/codewitharhan) | [GitHub](https://github.com/ArhanAnsari)
+MIT