Neomage

Multi-provider AI agent engine for Flutter. Robust API clients for Gemini (including Gemini Live bidirectional voice streaming), OpenAI, Anthropic, DeepSeek, Qwen, and Ollama with tool execution, skills, multi-agent swarms, and MCP.

Part of the Open Neom ecosystem.

Features

• Multi-provider — Gemini, OpenAI, Anthropic, DeepSeek, Qwen, Ollama. One interface, any backend.
• Swarm Orchestration (Multi-Agent Swarm) — High-performance concurrent multi-agent scheduler (SwarmOrchestrator) using a DAG (DependencyGraph) with DFS cycle-detection, topological sorting, work-stealing scheduling, and inter-agent direct/broadcast MessageBus.
• Offline Sovereignty & Local AI — Run local GGUF models (e.g. Llama 3.2, Qwen 2.5 Coder) in-process via LocalLlamaProvider, native offline voice synthesis (Piper/VITS via Sherpa ONNX in isolates), and deterministic JS execution using an isolated QuickJS JsSandboxTool.
• IDE Bridge & Editor Integration — WebSocket JSON-RPC edit bridge to VS Code, JetBrains (IntelliJ, PyCharm, etc.), and terminal editors to perform split diffs, diagnostic extraction, atomic edits, and remote file navigation.
• Gemini Live Realtime Voice — Pure-Dart client (GeminiRealtimeClient) for Gemini's bidirectional voice WebSocket API, streaming audio natively with PCM 16-bit 16 kHz input / 24 kHz output.
• Agentic tool system — 31 built-in tools (Bash, FileRead/Write/Edit, Grep, Glob, WebSearch, Agent, etc.) with automatic multi-turn execution loop.
• Streaming — Real-time SSE parsing with typed stream events (TextDelta, ToolUseStart, ThinkingDelta, etc.).
• Skills framework — 283 loadable markdown skills across 40+ categories (architecture, testing, debugging, agents, security, etc.).
• Personality system — 12 modular personality modules (Identity, Cognition, Tools, Agency, Memory, etc.) assembled into a dynamic system prompt with environment context.
• MCP client — Model Context Protocol support for extending capabilities with external tool servers.
• Bash security — Advanced command validation with 23+ security checks (injection detection, IFS validation, quote-obfuscated flags, process substitution blocks, and locale hacks).
• Advanced Context Compaction — Three-phase pipeline including in-memory Microcompaction, reactively-triggered Auto-Compaction, and dual-direction cache-friendly Partial Compaction preserving LLM Prompt Caching.
• Retry with backoff — Configurable exponential backoff with 529/rate-limit awareness.
• Cross-platform — macOS, Linux, Windows, Web, iOS, Android.

Installation

dependencies:
  neomage: ^1.0.0

import 'package:neomage/neomage.dart';

Quick Start

1. Configure a provider

import 'package:neomage/neomage.dart';

// Use any OpenAI-compatible provider
final provider = ApiProvider(
  apiKey: 'your-api-key',
  baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
  model: 'gemini-2.5-flash',
);

2. Send messages

final message = Message.user('Explain the builder pattern in Dart');
final response = await provider.complete(messages: [message]);
print(response.textContent);

3. Stream responses

final stream = provider.stream(messages: [message]);
await for (final event in stream) {
  if (event is TextDelta) {
    stdout.write(event.text);
  }
}

4. Use the tool system

// Define tools
final tools = [
  ToolDefinition(
    name: 'read_file',
    description: 'Read contents of a file',
    inputSchema: {
      'type': 'object',
      'properties': {
        'path': {'type': 'string', 'description': 'File path to read'},
      },
      'required': ['path'],
    },
  ),
];

// The query engine handles the agentic loop automatically
final engine = QueryEngine(provider: provider, tools: tools);
final result = await engine.query(
  messages: [Message.user('Read the pubspec.yaml file')],
);

5. Validate bash commands

final result = bashCommandIsSafe('ls -la');
// result.isPassthrough → safe

final risky = bashCommandIsSafe('rm -rf / --no-preserve-root');
// risky.isAsk → needs user confirmation

6. Build system prompts with personality

// Load personality modules (call once at startup)
await NeomageSystemPrompt.load();

// Build a context-aware system prompt
final systemPrompt = NeomageSystemPrompt.build(
  model: 'gemini-2.5-flash',
  workingDirectory: '/home/user/project',
  gitBranch: 'feature/auth',
  projectLanguage: 'dart',
  projectFramework: 'flutter',
  loadedSkills: [codingSkill, testingSkill],
);

Supported Providers

Provider	Default Model	Endpoint
Gemini	gemini-2.5-flash	generativelanguage.googleapis.com
OpenAI	gpt-4o	api.openai.com
Anthropic	claude-sonnet-4	api.anthropic.com
DeepSeek	deepseek-chat	api.deepseek.com
Qwen	qwen-plus	dashscope.aliyuncs.com
Ollama	llama3.1	localhost:11434 (local)

Architecture

lib/
├── core/
│   ├── agent/          # System prompt builder, personality loader
│   └── platform/       # Cross-platform abstraction (dart:io stubs for web)
├── data/
│   ├── api/            # ApiProvider, AnthropicClient, OpenAiShim, SSE streaming
│   ├── auth/           # API key + provider config (secure storage)
│   ├── engine/         # QueryEngine — agentic conversation loop
│   ├── tools/          # 31 tools: Bash, FileRead/Write/Edit, Grep, Glob, Agent...
│   ├── compact/        # Context compaction (summarization strategies)
│   ├── services/       # Ollama, MCP, analytics, voice, git, sessions
│   └── commands/       # 24+ slash commands
├── domain/models/      # Message, ContentBlock, ToolDefinition, Permissions, IDs
├── state/              # Sint controllers and reactive state
└── utils/              # 25+ utility modules (config, telemetry, git, etc.)

Example App

The example/ directory contains a full AI coding assistant app built with neomage — demonstrates multi-provider chat, tool execution, skills system, MCP integration, and more.

cd example
flutter pub get
flutter run -d macos   # or: -d chrome, -d linux, -d windows

Features: streaming chat, Ollama local models, settings, onboarding, command palette, vim mode, dark/light theme, session browser, MCP panel.

Testing

flutter test

The test suite covers domain models, API error classification, bash security validation, SSE parsing, retry logic, tool definitions, and system prompt assembly.

Acknowledgements

Neomage is built on the shoulders of giants. We gratefully acknowledge the following projects and organizations whose work, APIs, and open-source contributions made this possible:

• Anthropic — For the Claude API and for open-sourcing Claude Code, whose tool system architecture, system prompt design, agentic loop patterns, and permission model served as the primary reference architecture for Neomage's engine.
• Google — For the Gemini API and the Flutter framework, which powers Neomage's cross-platform capabilities across macOS, Linux, Windows, Web, iOS, and Android.
• OpenAI — For establishing the chat completions API standard that became the lingua franca for AI providers, enabling Neomage's multi-provider compatibility via the OpenAI-compatible shim.
• Qwen (Alibaba Cloud) — For the Qwen model family and DashScope API, expanding Neomage's reach to additional high-quality models.
• Ollama — For making local model inference accessible and enabling Neomage's offline-first capabilities.

License

Apache License — see LICENSE.

Built by the Open Neom community.