vantura 0.1.0

An AI Agentic Framework for Flutter. Build LLM-powered agents that reason, use tools, remember conversations, and stream responses in real-time. Works with any OpenAI-compatible API.

Vantura

An AI Agentic Framework for Flutter — build LLM-powered agents that reason, use tools, remember conversations, and stream responses in real-time.

---

Features

• 🧠 ReAct Reasoning Loop — Agents autonomously decide when to think, call tools, and respond.
• 🛠️ Extensible Tool System — Create custom tools with type-safe arguments and JSON Schema definitions.
• 🔄 Streaming-First — Token-by-token streaming via SSE for real-time typewriter UIs.
• 💾 Smart Memory — Automatic summarization and pruning keeps the context window within token limits.
• 🤝 Multi-Agent Coordination — AgentCoordinator enables seamless hand-offs between specialist agents.
• ⏹️ Request Cancellation — CancellationToken lets users abort generation mid-flight.
• 📊 Token Usage Tracking — Monitor prompt/completion/total tokens per request.
• 🔔 Error Callbacks — onToolError, onAgentFailure, onWarning hooks for telemetry and resilience.
• 📝 Built-in Markdown Renderer — Zero-dependency Flutter widget for rendering agent responses.
• 🔌 Provider Agnostic — Works with any OpenAI-compatible API (Groq, OpenAI, Ollama, Together, etc.).

---

Installation

Add to your pubspec.yaml:

dependencies:
  vantura:
    path: packages/vantura   # local path (or pub.dev once published)

---

Quick Start

1. Initialize the Client

import 'package:vantura/core/index.dart';

final client = VanturaClient(
  apiKey: 'your-api-key',
  baseUrl: 'https://api.groq.com/openai/v1/chat/completions',
  model: 'llama-3.3-70b-versatile',
);

2. Set Up Memory

// In-memory only
final memory = VanturaMemory(sdkLogger, client);

// With persistence (provide your own VanturaPersistence implementation)
final memory = VanturaMemory(sdkLogger, client, persistence: myPersistence);
await memory.init();

3. Create and Run the Agent

final agent = VanturaAgent(
  name: 'assistant',
  description: 'General-purpose assistant',
  instructions: 'You are a helpful assistant.',
  memory: memory,
  tools: [...getStandardTools(), MyCustomTool()],
  client: client,
  state: VanturaState(),
  onToolError: (tool, error, stack) => print('Tool $tool failed: $error'),
);

// Blocking call
final response = await agent.run('What is 2 + 2?');
print(response.text);
print('Tokens used: ${response.usage?.totalTokens}');

// Streaming (real-time chunks)
final token = CancellationToken();
await for (final chunk in agent.runStreaming('Tell me a story', cancellationToken: token)) {
  if (chunk.textChunk != null) stdout.write(chunk.textChunk);
}

---

Architecture

lib/
├── core/                        # Core SDK engine
│   ├── index.dart               # Barrel export
│   ├── agent_coordinator.dart   # Multi-agent routing & handoffs
│   ├── cancellation_token.dart  # Request cancellation
│   ├── vantura_agent.dart       # Agent reasoning loop + callbacks
│   ├── vantura_client.dart      # HTTP client (retry, rate-limit, SSE)
│   ├── vantura_memory.dart      # Short-term + long-term memory
│   ├── vantura_persistence.dart # Abstract persistence interface
│   ├── vantura_state.dart       # UI state (ChangeNotifier)
│   ├── vantura_tool.dart        # Abstract tool base class
│   ├── schema_helper.dart       # JSON Schema builder
│   └── logger.dart              # Abstract logger
├── markdown/                    # Built-in Markdown renderer
│   ├── markdown.dart            # MarkdownText widget
│   ├── parser.dart              # Markdown → AST
│   ├── nodes.dart               # AST node definitions
│   └── renderer.dart            # AST → Flutter widgets
└── tools/                       # Built-in tools
    ├── index.dart               # getStandardTools() registry
    ├── calculator_tool.dart
    ├── network_connectivity_tool.dart
    ├── device_info_tool.dart
    └── api_test_tool.dart

---

Core Classes

VanturaClient

HTTP client with connection pooling, 3-retry exponential backoff, and automatic HTTP 429 rate-limit handling.

Property	Type	Description
apiKey	String	API key for Bearer auth
baseUrl	String	API endpoint URL
model	String	Default model name
temperature	double?	Sampling temperature
maxCompletionTokens	int?	Max tokens in response

VanturaAgent

The reasoning engine. Runs a ReAct-style loop (configurable max iterations) alternating between LLM calls and tool execution.

Constructor Param	Type	Description
name	String	Agent identity for multi-agent routing
description	String	Agent purpose (used by coordinators)
instructions	String	System prompt
onToolError	Function?	Callback when a tool throws
onAgentFailure	Function?	Callback on critical agent failure
onWarning	Function?	Callback for non-fatal warnings

AgentCoordinator

Manages multiple agents with automatic hand-off via an injected transfer_to_agent tool:

final coordinator = AgentCoordinator([
  invoicingAgent,
  inventoryAgent,
  generalAgent,
]);

// Use exactly like a single agent
await for (final r in coordinator.runStreaming('Create an invoice')) { ... }

VanturaResponse

Field	Type	Description
text	String?	Final complete text (from run())
textChunk	String?	Single streamed token (from runStreaming())
toolCalls	List<Map<String, dynamic>>?	Tool calls executed during this step
usage	TokenUsage?	Prompt / completion / total token counts

VanturaPersistence (Abstract)

Plug in any storage backend. The SDK never imports sqflite, hive, or any database directly.

abstract class VanturaPersistence {
  Future<void> saveMessage(String role, String content, {bool isSummary = false});
  Future<List<Map<String, dynamic>>> loadMessages();
  Future<void> clearMessages();
  Future<void> deleteOldMessages(int limit);
}

---

Creating Custom Tools

class GreetTool extends VanturaTool<GreetArgs> {
  @override String get name => 'greet_user';
  @override String get description => 'Greets a user by name';

  @override
  Map<String, dynamic> get parameters => SchemaHelper.generateSchema({
    'name': SchemaHelper.stringProperty(description: 'The user name'),
  });

  @override GreetArgs parseArgs(Map<String, dynamic> json) => GreetArgs.fromJson(json);

  @override
  Future<String> execute(GreetArgs args) async => 'Hello, ${args.name}!';
}

For destructive operations, override requiresConfirmation => true for human-in-the-loop safety.

---

Built-in Tools

Tool	Name	Description
CalculatorTool	calculator	Basic arithmetic
NetworkConnectivityTool	check_connectivity	Internet connectivity check
DeviceInfoTool	get_device_info	Platform and OS info
ApiTestTool	test_api	HTTP GET/POST requests

Access all via getStandardTools() from package:vantura/tools/index.dart.

---

Markdown Renderer

Zero-dependency Flutter Markdown widget:

import 'package:vantura/markdown/markdown.dart';

MarkdownText('### Hello **World**', isUser: false)

Supports headers, bold, italic, inline code, bullet lists, and horizontal rules.

---

Design Principles

1. No database imports — Persistence is abstracted via VanturaPersistence.
2. Minimal Flutter dependency — Only VanturaState uses ChangeNotifier. Core is pure Dart.
3. Shared HTTP client — Connection pooling via a single http.Client.
4. Streaming-first — runStreaming() yields chunks as they arrive, not after completion.
5. Automatic memory management — Old messages are summarized and pruned.
6. Human-in-the-loop — Tools can require user confirmation before execution.

---

License

This project is licensed under the MIT License — see the LICENSE file for details.