flutter_mind logo

flutter_mind

Any AI. One interface.

pub version pub likes pub points license

⚠️ Local model support is moving. LocalEngine, LocalConfig, and LocalEngineEvent are deprecated in flutter_mind and will be removed in v1.0.0. Use flutter_mind_local instead — same API, one import, no other changes needed. See the Local Model (Offline) section for the full migration guide.

Why flutter_mind?

Most AI packages for Flutter just wrap the API — you still have to write the prompts, handle errors, manage tokens, and figure out streaming yourself.

flutter_mind does more:

  • 🔌 One API for all providers — same interface for cloud and local models
  • 💬 Multi-turn chat — conversation history with automatic token trimming
  • ⚡ Streaming — typing-effect UI out of the box
  • 🧠 Thinking models — built-in support for reasoning budgets
  • 🛡️ Safe by default — input validation, retry logic, and clear error messages
  • 🎯 Zero Firebase required — API key for cloud, or fully offline with no key at all

Supported Providers

Provider Status Models
Google Gemini ✅ v1 Flash 2.5, Pro 2.5, Flash-Lite, and more
Local Model (offline) ⚠️ Deprecated — moved to flutter_mind_local Any .gguf — Qwen, Llama, Gemma, Phi, Mistral, and more
OpenAI 🔜 v2 GPT-4o, GPT-4o Mini
Anthropic Claude 🔜 v2 Sonnet, Opus, Haiku
Grok 🔜 v2 —
DeepSeek 🔜 v2 —

Installation

dependencies:
  flutter_mind: ^0.3.0

flutter pub get

Quick Start

import 'package:flutter_mind/flutter_mind.dart';

void main() {
  FlutterMind.init(
    engine: GeminiEngine(apiKey: 'YOUR_GEMINI_API_KEY'),
  );
  runApp(MyApp());
}

// Anywhere in your app — no imports, no passing around
final response = await FlutterMind.send(userMessage: 'suggest a game');
print(response.text);

Three lines in main(). Done.

Getting Your API Key

Google Gemini — Free tier available

  1. Go to aistudio.google.com/apikey
  2. Sign in with your Google account
  3. Click Create API Key — no credit card required

OpenAI (coming in v2)

  1. Go to platform.openai.com → API Keys → Create new secret key

Anthropic Claude (coming in v2)

  1. Go to console.anthropic.com → API Keys → Create Key

Local Model — No API key needed ✅

No account, no key, no internet required. Just a .gguf model file on the device. Now powered by flutter_mind_local — see the Local Model (Offline) section for the migration guide.

Usage

Send a message

final response = await FlutterMind.send(userMessage: 'what is Flutter?');

print(response.text);          // the response text
print(response.totalTokens);   // total tokens used
print(response.inputTokens);   // tokens in your message
print(response.outputTokens);  // tokens in the response

Streaming — typing effect UI

FlutterMind.stream(userMessage: 'tell me a story').listen((chunk) {
  setState(() => text += chunk); // text appears word by word
});

Multi-turn chat — conversation with memory

final history = <ChatMessage>[];

// First turn
final r1 = await FlutterMind.send(
  userMessage: 'my name is Osama',
  history: history,
);
history.add(ChatMessage.user('my name is Osama'));
history.add(ChatMessage.model(r1.text));

// Second turn — model remembers the name
final r2 = await FlutterMind.send(
  userMessage: 'what is my name?',
  history: history,
  maxHistoryMessages: 20, // oldest turns are dropped automatically
);
print(r2.text); // "Your name is Osama"

Engine configuration

Set your defaults once — every call uses them automatically:

FlutterMind.init(
  engine: GeminiEngine(
    apiKey: 'YOUR_KEY',
    config: GeminiConfig(
      model: GeminiModel.flash25,
      systemPrompt: Prompt(role: 'game suggestion assistant'),
      temperature: 0.8,
      maxOutputTokens: 500,
    ),
  ),
);

Prompt engineering

Control how the model behaves with the Prompt class — from one field to full expert config.

Tier 1 — Minimal

GeminiConfig(
  systemPrompt: Prompt(role: 'game suggestion assistant'),
)

Tier 2 — Standard

Prompt(
  role: 'game assistant',
  format: ResponseFormat.numberedList,
  maxItems: 3,
  language: ResponseLanguage.auto, // detects Arabic vs English per message
  constraints: ['mobile only', 'no violent games'],
)

Tier 3 — Advanced

Prompt(
  role: 'mobile game expert for Egyptian users',
  goal: 'suggest games that match the user mood and age',
  constraints: ['mobile only', 'no violent games', 'available in Egypt'],
  format: ResponseFormat.numberedList,
  maxItems: 3,
  language: ResponseLanguage.auto,
  tone: ResponseTone.friendly,
  audience: 'Egyptian teenagers',
  examples: [
    PromptExample(input: 'fun game', output: 'Hollow Knight — platformer'),
    PromptExample(input: 'relaxing', output: 'Stardew Valley — farming sim'),
  ],
)

Tier 4 — Expert

Prompt(
  role: 'game assistant',
  chainOfThought: true,
  chainSteps: ['identify user mood', 'match game genre', 'select 3 games'],
  preventInjection: true,        // resists jailbreak attempts
  responseAnchor: 'Here are your top 3 games:',
  negativePatterns: ['never suggest PC games'],
  compressed: false,             // verbose output for complex reasoning
)

Ready-made presets

// Use directly
GeminiConfig(systemPrompt: AiPreset.chat)
GeminiConfig(systemPrompt: AiPreset.summarizer)
GeminiConfig(systemPrompt: AiPreset.codeHelper)
GeminiConfig(systemPrompt: AiPreset.stepByStep)

// Customize one field
GeminiConfig(
  systemPrompt: AiPreset.chat.copyWith(role: 'Egyptian culture guide'),
)

Stop sequences — pair with the prompt

final prompt = Prompt(
  format: ResponseFormat.numberedList,
  maxItems: 3,
);

GeminiConfig(
  systemPrompt: prompt,
  stopSequences: prompt.stopSequences, // → ['[END]'] — model stops exactly here
)

Per-call config override

Override only what changes for a single call — defaults stay untouched:

// Uses your default config
await FlutterMind.send(userMessage: 'suggest a game');

// Overrides just for this one call
await FlutterMind.send(
  userMessage: 'solve this complex math problem',
  config: GeminiConfig(
    model: GeminiModel.pro25,
    temperature: 0.1,
    thinkingLevel: ThinkingLevel.deep,
  ),
);

Thinking models

Let the model reason before answering — better results on hard problems:

GeminiConfig(
  model: GeminiModel.pro25,
  thinkingLevel: ThinkingLevel.moderate,
)

// Or set an exact token budget
GeminiConfig(
  model: GeminiModel.pro25,
  thinkingLevel: CustomThinkingBudget(tokens: 4000),
)
Level Tokens Best For
ThinkingLevel.none 0 Fastest, cheapest
ThinkingLevel.light 512 Simple reasoning
ThinkingLevel.moderate 2,048 Coding, math
ThinkingLevel.deep 8,192 Complex problems
ThinkingLevel.max 24,576 Hardest problems

Access the model's reasoning in the response:

final response = await FlutterMind.send(
  userMessage: 'explain quantum entanglement simply',
  config: GeminiConfig(
    model: GeminiModel.pro25,
    thinkingLevel: ThinkingLevel.moderate,
  ),
);

print(response.text);         // the answer
print(response.thinkingText); // how it got there (null if not a thinking model)
print(response.hasThinking);  // true / false

Structured JSON output

Force the model to always return valid, parseable JSON:

GeminiConfig(
  model: GeminiModel.flash25,
  responseMimeType: 'application/json',
  responseSchema: {
    'type': 'object',
    'properties': {
      'name':   {'type': 'string'},
      'genre':  {'type': 'string'},
      'rating': {'type': 'number'},
    },
    'required': ['name', 'genre', 'rating'],
  },
)

beforeSend hook — inject runtime context

Enrich every message with user profile, location, or app state before it reaches the AI:

FlutterMind.init(
  engine: GeminiEngine(apiKey: 'YOUR_KEY'),
  beforeSend: (message) async {
    final user = await UserService.getProfile();
    final location = await LocationService.current();
    return 'User: ${user.name}, Location: $location\n\n$message';
  },
);

// User types: "what restaurants are near me?"
// Model receives: "User: Osama, Location: Cairo, Egypt\n\nwhat restaurants are near me?"

Token management

// Accurate count — calls the API, always free
final tokens = await FlutterMind.countTokens(userMessage: longText);
if (tokens > 100000) print('Message too long');

// Rough estimate — instant, no API call
// Note: Arabic text uses 2–3× more tokens than English
final estimate = FlutterMind.estimateTokens(message);

Retry configuration

GeminiEngine(
  apiKey: 'YOUR_KEY',

  // Default — 2 attempts on 429, 500, 503
  retry: RetryConfig(),

  // Custom
  retry: RetryConfig(
    maxAttempts: 5,
    delay: Duration(seconds: 2),
    retryOn: {429, 503},
  ),

  // Disable
  retry: RetryConfig.none,
)

Availability check

if (!await FlutterMind.isAvailable()) {
  showDialog(context, 'AI is currently unavailable. Try again later.');
  return;
}

Multiple engines in one app

Use FlutterMindClient directly when you need more than one engine:

final chatClient = FlutterMindClient(
  engine: GeminiEngine(
    apiKey: 'YOUR_KEY',
    config: GeminiConfig(
      model: GeminiModel.flash25,
      systemPrompt: Prompt(role: 'friendly chat assistant'),
    ),
  ),
);

final summaryClient = FlutterMindClient(
  engine: GeminiEngine(
    apiKey: 'YOUR_KEY',
    config: GeminiConfig(
      model: GeminiModel.pro25,
      systemPrompt: Prompt(role: 'document summarizer', tone: ResponseTone.concise),
      temperature: 0.1,
    ),
  ),
);

await chatClient.send(userMessage: 'hello');
await summaryClient.send(userMessage: longDocument);

Local Model (Offline)

⚠️ Moved to a dedicated package. LocalEngine, LocalConfig, and LocalEngineEvent are deprecated here and will be removed in v1.0.0. Local/offline inference now lives in flutter_mind_local — same API, one import, no other code changes needed.

dependencies:
  flutter_mind_local: ^0.1.0

import 'package:flutter_mind_local/flutter_mind_local.dart';

final engine = LocalEngine(
  config: LocalConfig(modelPath: '/path/to/model.gguf'),
);

final response = await engine.send(userMessage: 'Hello!');
print(response.text);

engine.dispose(); // free model memory when done

See the flutter_mind_local README for platform setup (Android, iOS, macOS), model recommendations, lifecycle events, conversation history, and the full configuration reference.

Gemini Models

Constant Model ID Status Best For
GeminiModel.flash25 gemini-2.5-flash ✅ Stable General use — recommended default
GeminiModel.flash25Lite gemini-2.5-flash-lite ✅ Stable High volume, lowest cost
GeminiModel.pro25 gemini-2.5-pro ✅ Stable Complex reasoning, analysis
GeminiModel.flash3Preview gemini-3-flash-preview ⚠️ Preview Frontier performance
GeminiModel.flash31Lite gemini-3.1-flash-lite ✅ Stable Fast, affordable, Gemini 3
GeminiModel.pro31Preview gemini-3.1-pro-preview ⚠️ Preview Most powerful available

Use CustomModel for any model not listed:

GeminiConfig(model: CustomModel('gemini-4.0-ultra'))

Error Handling

try {
  final response = await FlutterMind.send(userMessage: message);
  print(response.text);
} on ValidationException catch (e) {
  // Bad input — empty message or exceeds 50,000 characters
  print(e.message);
} on EngineException catch (e) {
  // API error — invalid key, rate limit, network issue
  print(e.message);
  print(e.statusCode); // 401, 429, 500 ...
} on FlutterMindException catch (e) {
  // Any other flutter_mind error
  print(e.message);
}

Common status codes

Code Meaning Fix
400 Bad request or invalid API key Check your key at aistudio.google.com/apikey
401 Unauthorized API key rejected
403 No permission Key may not have access to this model
404 Model not found Check model name or use CustomModel
429 Rate limit Add RetryConfig or upgrade your API plan
500 Server error Temporary — try again

API Key Security

Never hardcode API keys in production apps. Anyone can extract them from your APK or IPA.

// During development — environment variable
GeminiEngine(
  apiKey: const String.fromEnvironment('GEMINI_KEY'),
)

// In production — proxy through your own backend
// Flutter app → Your server → Gemini API
// The key never leaves your server

Use flutter_dotenv for local .env files.

Roadmap

v1 — Current

  • x Google Gemini engine
  • x Local model engine (llama.cpp — offline, no API key)
  • x Send and streaming
  • x Multi-turn conversation history
  • x Thinking model support (ThinkingLevel presets + custom budget)
  • x Structured JSON output
  • x Token management (accurate + estimate)
  • x Retry configuration
  • x Input validation
  • x beforeSend hook
  • x Prompt engineering system (Prompt, AiPreset, few-shot examples, chain of thought)

v1 — In Progress

  • x flutter_mind_local package — local engine as a standalone pub.dev package
  • Remove deprecated LocalEngine, LocalConfig, LocalEngineEvent from flutter_mind

v2 — Coming Soon

  • OpenAI engine
  • Anthropic Claude engine
  • Response parser (JSON → typed Dart objects)
  • True token streaming for local models
  • flutter_mind_vision (image generation)
  • flutter_mind_audio (TTS, STT)

Contributing

Contributions are welcome. To contribute:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/your-feature
  3. Commit your changes with a clear message
  4. Push and open a Pull Request

License

MIT — see LICENSE for details.

Built by Mohamed Osama · Egypt 🇪🇬

Libraries

flutter_mind