neomage 1.0.0

Agnostic AI agent engine for Flutter. API clients for AI Providers and Ollama with tool execution, skills and MCP.

Neomage

Multi-provider AI agent engine for Flutter. API clients for Gemini, OpenAI, Anthropic, DeepSeek, Qwen, and Ollama with tool execution, skills, and MCP.

Part of the Open Neom ecosystem.

Features

• Multi-provider — Gemini, OpenAI, Anthropic, DeepSeek, Qwen, Ollama. One interface, any backend.
• 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 — Command validation with 20+ security checks (injection detection, IFS validation, obfuscated flags, etc.).
• Context compaction — Automatic conversation summarization to stay within token limits.
• 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's tool system architecture, system prompt design, and agentic loop patterns are inspired by OpenClaw (Claude Code by Anthropic). The tool descriptions, permission model, and query engine design follow patterns established by the OpenClaw/OpenClaude codebase. We are grateful to the Anthropic team for open-sourcing Claude Code, which served as the reference architecture for building a multi-provider agentic engine in Flutter.

License

Apache License — see LICENSE.

Built by the Open Neom community.