### Installation and Setup

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/tools/mcp-server/README.md

Instructions on how to install and set up the Edge Veda MCP Server, including one-liner installation, integration with Claude Code and Claude Desktop, and building from source.

```APIDOC
## Installation

### One-liner (npx)

No install needed -- npx fetches and runs the latest version:

```bash
npx @edge-veda/mcp-server
```

### Add to Claude Code

```bash
claude mcp add edge-veda -- npx @edge-veda/mcp-server
```

### Add to Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "edge-veda": {
      "command": "npx",
      "args": ["@edge-veda/mcp-server"]
    }
  }
}
```

### From Source (contributors)

```bash
git clone https://github.com/ramanujammv1988/edge-veda.git
cd edge-veda/tools/mcp-server
npm install
npm run build
```
```

--------------------------------

### Quick Start Commands

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/examples/document_qa/README.md

Commands to clone the repository, install dependencies, and run the Flutter application.

```bash
git clone https://github.com/ramanujammv1988/edge-veda.git
cd edge-veda/examples/document_qa
flutter pub get
flutter run
```

--------------------------------

### Flutter Project Setup and Dependencies

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/examples/intent_engine/README.md

Instructions for setting up the Flutter project, including cloning the repository, installing dependencies, and building necessary components like the XCFramework.

```bash
git clone https://github.com/anthropics/edge-veda.git
cd edge-veda/examples/intent_engine
flutter pub get
cd ../../ios && ./build_xcframework.sh && cd -
```

--------------------------------

### Development Setup and Commands for Edge Veda

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/CONTRIBUTING.md

This section details the initial setup and common development commands for the Edge Veda project. It includes cloning the repository, running the example app, executing tests, and performing code analysis.

```bash
# Clone
git clone https://github.com/<your-username>/edge-veda.git
cd edge-veda

# Run the example app (macOS)
cd flutter/example
flutter run -d macos

# Run tests
cd flutter
flutter test

# Run analyzer
flutter analyze
```

--------------------------------

### Installation and Configuration

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/README.md

Setup instructions for adding the Edge-Veda dependency to a Flutter project and configuring the iOS environment for native engine support.

```yaml
dependencies:
  edge_veda: ^2.4.1
```

```ruby
platform :ios, '13.0'
```

```bash
./scripts/build-ios.sh --clean --release
```

--------------------------------

### Complete Example Usage

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/doc/API.md

A comprehensive example demonstrating the full lifecycle of using the Edge Veda SDK, from initialization to generation and cleanup.

```APIDOC
## Complete Example Usage

### Description
This example illustrates the complete workflow of using the Edge Veda SDK, including initializing the model manager, downloading a model, initializing Edge Veda, generating text, streaming tokens, checking memory usage, and cleaning up resources.

### Code Example
```dart
import 'package:edge_veda/edge_veda.dart';

Future<void> main() async {
  // Initialize model manager
  final modelManager = ModelManager();

  // Download model with progress tracking
  modelManager.downloadProgress.listen((progress) {
    print('Download: ${progress.progressPercent}%');
  });

  final modelPath = await modelManager.downloadModel(
    ModelRegistry.llama32_1b,
  );

  // Initialize Edge Veda
  final edgeVeda = EdgeVeda();
  await edgeVeda.init(EdgeVedaConfig(
    modelPath: modelPath,
    useGpu: true,
  ));

  // Generate text
  final response = await edgeVeda.generate(
    'What is artificial intelligence?',
    options: const GenerateOptions(
      maxTokens: 200,
      temperature: 0.7,
    ),
  );

  print(response.text);
  print('Speed: ${response.tokensPerSecond} tokens/sec');

  // Stream tokens
  final stream = edgeVeda.generateStream('Tell me a joke');
  await for (final chunk in stream) {
    if (!chunk.isFinal) {
      print(chunk.token);
    }
  }

  // Check memory usage
  print('Memory: ${edgeVeda.getMemoryUsageMb()} MB');

  // Cleanup
  await edgeVeda.dispose();
  modelManager.dispose();
}
```
```

--------------------------------

### Install Application Bundle Components - CMake

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/example/linux/CMakeLists.txt

Configures the installation process for the application bundle, including cleaning the build directory, installing the executable, data files, libraries, and Flutter assets.

```cmake
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)

set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/linux/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)

set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Run Soak Test Application

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/CONTRIBUTING.md

Commands to build and launch the example application on macOS or iOS for soak testing purposes.

```bash
# macOS
cd flutter/example && flutter run -d macos

# iOS (physical device only — no simulator)
cd flutter/example && flutter run --release
```

--------------------------------

### Target Installation and Testing

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/core/CMakeLists.txt

Defines the installation rules for shared and static libraries and configures the testing environment if enabled. It ensures that headers are installed and test hooks are compiled into the targets when building the test suite.

```cmake
if(EDGE_VEDA_BUILD_SHARED)
    install(TARGETS edge_veda
        LIBRARY DESTINATION lib
        ARCHIVE DESTINATION lib
        RUNTIME DESTINATION bin
        FRAMEWORK DESTINATION lib
    )
endif()

if(EDGE_VEDA_BUILD_TESTS)
    enable_testing()
    if(TARGET edge_veda_static)
        target_compile_definitions(edge_veda_static PRIVATE EDGE_VEDA_TEST_HOOKS)
    endif()
    add_subdirectory(tests)
endif()
```

--------------------------------

### Install Dependencies (Flutter)

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/examples/voice_journal/README.md

Installs the necessary Flutter dependencies for the Voice Journal application. This is a standard step before running any Flutter project.

```bash
flutter pub get
```

--------------------------------

### Initialize Flutter Project and Dependencies

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/QUICKSTART.md

Commands to create a new Flutter project, add the Edge Veda dependency, and install native CocoaPods.

```bash
flutter create my_ai_app
cd my_ai_app
flutter pub get
cd ios && pod install && cd ..
```

```yaml
dependencies:
  flutter:
    sdk: flutter
  edge_veda: ^2.4.2
```

```ruby
platform :ios, '13.0'
```

--------------------------------

### Home Assistant Connector Configuration (Dart)

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/examples/intent_engine/README.md

Example code demonstrating how to configure the Home Assistant connector in Dart. This includes setting up the base URL and authentication token for interacting with a Home Assistant instance.

```dart
final ha = HomeAssistantConnector(
  baseUrl: 'http://homeassistant.local:8123',
  bearerToken: 'your-long-lived-access-token',
);
```

--------------------------------

### Install Edge-Veda MCP Plugin

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/README.md

Command to install the Edge-Veda MCP plugin using Claude Code to automate environment setup and project scaffolding.

```bash
claude mcp add edge-veda -- npx @edge-veda/mcp-server
```

--------------------------------

### Complete Edge Veda Example (Dart)

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/doc/API.md

A comprehensive example demonstrating the full lifecycle of using Edge Veda. It covers initialization, model downloading with progress tracking, text generation, streaming tokens, checking memory usage, and resource cleanup.

```dart
import 'package:edge_veda/edge_veda.dart';

Future<void> main() async {
  // Initialize model manager
  final modelManager = ModelManager();

  // Download model with progress tracking
  modelManager.downloadProgress.listen((progress) {
    print('Download: ${progress.progressPercent}%');
  });

  final modelPath = await modelManager.downloadModel(
    ModelRegistry.llama32_1b,
  );

  // Initialize Edge Veda
  final edgeVeda = EdgeVeda();
  await edgeVeda.init(EdgeVedaConfig(
    modelPath: modelPath,
    useGpu: true,
  ));

  // Generate text
  final response = await edgeVeda.generate(
    'What is artificial intelligence?',
    options: const GenerateOptions(
      maxTokens: 200,
      temperature: 0.7,
    ),
  );

  print(response.text);
  print('Speed: ${response.tokensPerSecond} tokens/sec');

  // Stream tokens
  final stream = edgeVeda.generateStream('Tell me a joke');
  await for (final chunk in stream) {
    if (!chunk.isFinal) {
      print(chunk.token);
    }
  }

  // Check memory usage
  print('Memory: ${edgeVeda.getMemoryUsageMb()} MB');

  // Cleanup
  await edgeVeda.dispose();
  modelManager.dispose();
}
```

--------------------------------

### Build and Run iOS XCFramework Demo

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/BENCHMARKS.md

This script builds the XCFramework for iOS in release mode and then navigates to the Flutter example directory to run the demo app on a connected device.

```bash
# Build XCFramework
./scripts/build-ios.sh --clean --release

# Run demo app on device
cd flutter/example && flutter run --release
```

--------------------------------

### Zero-Config Setup with Claude MCP

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/README.md

This bash command demonstrates how to use the Claude MCP plugin to add the Edge-Veda project to your environment. It automates setup tasks like environment checks, project scaffolding, model selection, and deployment, simplifying the development process.

```bash
claude mcp add edge-veda -- npx @edge-veda/mcp-server@0.2.0
```

--------------------------------

### Build and Run macOS Static Library Demo

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/BENCHMARKS.md

This script builds the static library for macOS in release mode. It then proceeds to build the Flutter macOS example app and opens the resulting application bundle.

```bash
# Build static library
./scripts/build-macos.sh --clean --release

# Run demo app (release mode for benchmarking)
cd flutter/example && flutter build macos --release
open build/macos/Build/Products/Release/edge_veda_example.app
```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits format. These demonstrate how to structure messages for new features, bug fixes, and documentation updates, including referencing issues.

```text
feat(android): add NDK cross-compilation for arm64

Refs #12

docs: add getting started guide for new contributors

fix(macos): correct memory estimation using os_proc_available_memory

Refs #3
```

--------------------------------

### Configure Scheduler with Adaptive Budget

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/README.md

Sets up the Scheduler with an adaptive budget profile, automatically calibrating to the device's performance. It then registers workloads with specified priorities and starts the scheduler. Includes a listener for budget violation events.

```dart
final scheduler = Scheduler(telemetry: TelemetryService());
scheduler.setBudget(EdgeVedaBudget.adaptive(BudgetProfile.balanced));
scheduler.registerWorkload(WorkloadId.vision, priority: WorkloadPriority.high);
scheduler.registerWorkload(WorkloadId.text, priority: WorkloadPriority.low);
scheduler.registerWorkload(WorkloadId.stt, priority: WorkloadPriority.low);
scheduler.start();
scheduler.onBudgetViolation.listen((v) {
  print('${v.constraint}: ${v.currentValue} > ${v.budgetValue}');
});
```

--------------------------------

### CMake: Project Setup and C++ Standard Configuration

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/core/CMakeLists.txt

Initializes the CMake project, sets the C++ standard to C++17, and enables export of compile commands for IDE integration. It also includes basic platform detection for iOS, Android, and macOS.

```cmake
cmake_minimum_required(VERSION 3.15)
project(edge_veda VERSION 1.0.0 LANGUAGES CXX C)

# Set C++ standard
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

# Export compile commands for IDE support
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

# Platform detection
if(CMAKE_SYSTEM_NAME STREQUAL "iOS")
    set(IOS TRUE)
elseif(CMAKE_SYSTEM_NAME STREQUAL "Android")
    set(ANDROID TRUE)
elseif(CMAKE_SYSTEM_NAME STREQUAL "Darwin")
    set(MACOS TRUE)
endif()
```

--------------------------------

### Edge Veda SDK Usage in Dart

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/example/README.md

Example of initializing the Edge Veda SDK, downloading a model, setting up the inference engine, generating text, monitoring memory, and cleaning up resources. This demonstrates core SDK functionality for text generation.

```dart
import 'package:edge_veda/edge_veda.dart';

// Initialize SDK
final edgeVeda = EdgeVeda();
final modelManager = ModelManager();

// Download model (with progress tracking)
final modelPath = await modelManager.downloadModel(ModelRegistry.llama32_1b);

// Initialize inference engine
await edgeVeda.init(EdgeVedaConfig(
  modelPath: modelPath,
  useGpu: true,
  numThreads: 4,
  contextLength: 2048,
));

// Generate text
final response = await edgeVeda.generate(
  'Your prompt here',
  options: GenerateOptions(
    maxTokens: 256,
    temperature: 0.7,
  ),
);

print(response.text);

// Monitor memory
final stats = await edgeVeda.getMemoryStats();
print('Memory: ${stats.currentBytes / (1024 * 1024)} MB');

// Cleanup
edgeVeda.dispose();
```

--------------------------------

### Configure Scheduler with Static Budget

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/README.md

Configures the Scheduler with explicit static budget values for P95 latency, battery drain, and maximum thermal level. It then registers workloads and starts the scheduler, with a listener for budget violations.

```dart
scheduler.setBudget(const EdgeVedaBudget(
  p95LatencyMs: 3000,
  batteryDrainPerTenMinutes: 5.0,
  maxThermalLevel: 2,
));
scheduler.registerWorkload(WorkloadId.vision, priority: WorkloadPriority.high);
scheduler.registerWorkload(WorkloadId.text, priority: WorkloadPriority.low);
scheduler.registerWorkload(WorkloadId.stt, priority: WorkloadPriority.low);
scheduler.start();
scheduler.onBudgetViolation.listen((v) {
  print('${v.constraint}: ${v.currentValue} > ${v.budgetValue}');
});
```

--------------------------------

### Configure Project and Executable Name - CMake

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/example/linux/CMakeLists.txt

Sets the minimum CMake version, project name, and the executable's on-disk name. It also configures modern CMake behaviors and installation paths for libraries.

```cmake
cmake_minimum_required(VERSION 3.13)
project(runner LANGUAGES CXX)
set(BINARY_NAME "edge_veda_example")
set(APPLICATION_ID "com.edgeveda.edge_veda_example")
cmake_policy(SET CMP0063 NEW)
set(CMAKE_INSTALL_RPATH "$ORIGIN/lib")
```

--------------------------------

### Compute Budget Contracts with Scheduler

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/README.md

This code demonstrates how to configure and manage compute budget contracts using the Scheduler. It includes setting adaptive budgets, registering workloads with priorities, starting the scheduler, listening for budget violations, and inspecting measured baselines and resolved budgets.

```dart
final scheduler = Scheduler(telemetry: TelemetryService());

// Auto-calibrates to this device's actual performance
scheduler.setBudget(EdgeVedaBudget.adaptive(BudgetProfile.balanced));
scheduler.registerWorkload(WorkloadId.vision, priority: WorkloadPriority.high);
scheduler.start();

// React to violations
scheduler.onBudgetViolation.listen((v) {
  print('${v.constraint}: ${v.currentValue} > ${v.budgetValue}');
});

// After warm-up (~40s), inspect measured baseline
final baseline = scheduler.measuredBaseline;
final resolved = scheduler.resolvedBudget;
```

--------------------------------

### Confidence Scoring and Cloud Handoff with EdgeVeda

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/README.md

This example illustrates how to enable confidence tracking during text generation with EdgeVeda. It demonstrates setting a confidence threshold and checking if the model's response requires a fallback to a cloud API due to low confidence.

```dart
// Enable confidence tracking — zero overhead when disabled
final response = await edgeVeda.generate(
  'Explain quantum computing',
  options: GenerateOptions(confidenceThreshold: 0.3),
);

print('Confidence: ${response.avgConfidence}');

if (response.needsCloudHandoff) {
  // Model is uncertain — route to cloud API
  print('Low confidence, falling back to cloud');
}
```

--------------------------------

### Implement On-device Text-to-Speech

Source: https://context7.com/ramanujammv1988/edge-veda/llms.txt

Demonstrates how to initialize the TtsService, list available voices, and handle speech events such as word boundaries. It also shows how to control playback and configure speech parameters like rate and pitch.

```dart
import 'package:edge_veda/edge_veda.dart';

final tts = TtsService();

// List available voices
final voices = await tts.availableVoices();
for (final voice in voices) {
  print('${voice.name} (${voice.language}) - quality: ${voice.quality}');
}

// Select a voice
final englishVoice = voices.firstWhere(
  (v) => v.language.startsWith('en'),
  orElse: () => voices.first,
);

// Listen for word boundaries (for text highlighting)
tts.events.listen((event) {
  switch (event.type) {
    case TtsEventType.start:
      print('Started speaking');
      break;
    case TtsEventType.wordBoundary:
      print('Speaking word: "${event.word}" at position ${event.wordStart}');
      break;
    case TtsEventType.finish:
      print('Finished speaking');
      break;
    case TtsEventType.cancel:
      print('Speech cancelled');
      break;
  }
});

// Speak text (blocks until finished)
await tts.speak(
  'Hello from on-device AI! This is Edge Veda text-to-speech.',
  voiceId: englishVoice.id,
  rate: 0.5,  // 0.0 to 1.0
  pitch: 1.0, // 0.5 to 2.0
  volume: 1.0,
);

// Control playback
await tts.pause();
await tts.resume();
await tts.stop();
```

--------------------------------

### SDK Configuration and Options

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/doc/API.md

Configuration structures for initializing the SDK and defining generation parameters.

```APIDOC
## POST /config

### Description
Initializes the Edge Veda SDK with specific hardware and performance constraints.

### Request Body
- **modelPath** (String) - Required - Path to GGUF model file
- **numThreads** (int) - Optional - CPU threads for inference (default: 4)
- **contextLength** (int) - Optional - Max context window (default: 2048)
- **useGpu** (bool) - Optional - Enable GPU acceleration (default: true)
- **maxMemoryMb** (int) - Optional - Memory limit (default: 1536)

---

## POST /generate/options

### Description
Defines parameters for text generation such as temperature, token limits, and sampling strategies.

### Request Body
- **systemPrompt** (String) - Optional - System context
- **maxTokens** (int) - Optional - Max tokens to generate (default: 512)
- **temperature** (double) - Optional - Creativity level (0.0-1.0)
- **jsonMode** (bool) - Optional - Force JSON output (default: false)
```

--------------------------------

### Telemetry Trace Data Structure

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/CONTRIBUTING.md

Example of the JSONL format used for per-frame telemetry exported from the soak test.

```json
{
  "frame_id": 42,
  "ts_ms": 1771894145239,
  "stage": "total_inference",
  "value": 1523.0,
  "mode": "managed",
  "prompt_tokens": 80,
  "generated_tokens": 54
}
```

--------------------------------

### Dart: Function Calling with Tools using ToolRegistry

Source: https://context7.com/ramanujammv1988/edge-veda/llms.txt

Demonstrates how to define tools with JSON Schema parameters and use them in a chat session for multi-round tool chains. It includes setting up a ToolRegistry, creating a ChatSession with tools, and handling tool calls within the session.

```dart
import 'package:edge_veda/edge_veda.dart';

// Define tools with JSON Schema parameters
final tools = ToolRegistry([
  ToolDefinition(
    name: 'get_weather',
    description: 'Get current weather for a location',
    parameters: {
      'type': 'object',
      'properties': {
        'location': {'type': 'string', 'description': 'City name'},
        'unit': {'type': 'string', 'enum': ['celsius', 'fahrenheit']},
      },
      'required': ['location'],
    },
  ),
  ToolDefinition(
    name: 'search_web',
    description: 'Search the web for information',
    parameters: {
      'type': 'object',
      'properties': {
        'query': {'type': 'string', 'description': 'Search query'},
      },
      'required': ['query'],
    },
  ),
]);

// Create session with tools (Qwen3 recommended for tool calling)
final session = ChatSession(
  edgeVeda: edgeVeda,
  tools: tools,
  templateFormat: ChatTemplateFormat.qwen3,
);

// Send message with tool handling
final response = await session.sendWithTools(
  'What is the weather in Tokyo and New York?',
  maxToolRounds: 3,
  onToolCall: (toolCall) async {
    print('Tool called: ${toolCall.name}');
    print('Arguments: ${toolCall.arguments}');

    if (toolCall.name == 'get_weather') {
      // Execute the tool and return result
      final weather = await fetchWeather(toolCall.arguments['location']);
      return ToolResult.success(
        toolCallId: toolCall.id,
        data: {'temperature': 22, 'condition': 'sunny'},
      );
    }
    return ToolResult.failure(
      toolCallId: toolCall.id,
      error: 'Unknown tool',
    );
  },
);

print('Final response: ${response.content}');

```

--------------------------------

### Initialization and Error Handling

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/doc/API.md

Demonstrates how to initialize the Edge Veda SDK and handle potential initialization errors.

```APIDOC
## Initialization and Error Handling

### Description
Initializes the Edge Veda SDK with a given configuration and includes error handling for `InitializationException`.

### Method
`edgeVeda.init(config)`

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **config** (EdgeVedaConfig) - Required - The configuration object for Edge Veda.

### Request Example
```dart
try {
  await edgeVeda.init(config);
} on InitializationException catch (e) {
  print('Init failed: ${e.message}');
  if (e.details != null) {
    print('Details: ${e.details}');
  }
}
```

### Response
#### Success Response (200)
Initializes the SDK.

#### Response Example
None (void return type)
```

--------------------------------

### Tool: edge_veda_check_environment

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/tools/mcp-server/README.md

Verifies that all development prerequisites such as Flutter SDK, Xcode, CocoaPods, and connected iOS devices are installed and configured correctly.

```APIDOC
## POST /edge_veda_check_environment

### Description
Verify dev prerequisites are installed.

### Method
POST

### Endpoint
`/edge_veda_check_environment`

### Parameters
#### Path Parameters
(none)

#### Query Parameters
(none)

#### Request Body
(none)

### Request Example
(none)

### Response
#### Success Response (200)
- **report** (string) - A pass/fail report indicating the status of the development environment.

#### Response Example
```json
{
  "report": "All prerequisites met."
}
```
```

--------------------------------

### Initialize EdgeVeda SDK

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/doc/API.md

Initializes the Edge Veda SDK with the provided configuration. This method must be called before any other SDK operations. It handles model loading and setup.

```dart
await edgeVeda.init(EdgeVedaConfig(
  modelPath: '/path/to/model.gguf',
  useGpu: true,
));
```

--------------------------------

### Get Memory Usage in EdgeVeda

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/doc/API.md

Retrieves the current memory usage of the SDK, either in bytes or megabytes. Also provides a method to check if the memory usage exceeds a configured limit.

```dart
final bytes = edgeVeda.getMemoryUsage();
print('Memory: ${bytes / (1024 * 1024)} MB');
```

```dart
final mb = edgeVeda.getMemoryUsageMb();
```

```dart
if (edgeVeda.isMemoryLimitExceeded()) {
  print('Warning: Memory limit exceeded!');
}
```

--------------------------------

### Download and Import Models

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/QUICKSTART.md

Methods for downloading models from the registry with progress tracking or importing local GGUF files.

```dart
final modelManager = ModelManager();

// Download
final modelPath = await modelManager.downloadModel(ModelRegistry.llama32_1b);
modelManager.downloadProgress.listen((progress) => print('${progress.progressPercent}%'));

// Import
final localPath = await modelManager.importModel(ModelRegistry.llama32_1b, sourcePath: '/path/to/model.gguf');
```

--------------------------------

### Best Practices

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/doc/API.md

Recommended guidelines for effectively and efficiently using the Edge Veda SDK.

```APIDOC
## Best Practices

1.  **Initialize Once**: Create one EdgeVeda instance per session
2.  **Check Initialization**: Always check `isInitialized` before operations
3.  **Handle Errors**: Use try-catch with specific exception types
4.  **Monitor Memory**: Check memory usage on low-end devices
5.  **Dispose Resources**: Always call `dispose()` when done
6.  **Use Streaming**: For better UX in interactive apps
7.  **GPU Acceleration**: Keep `useGpu: true` for best performance
```

--------------------------------

### Build and Test Scripts for Edge Veda

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/CONTRIBUTING.md

These scripts are used to build the Edge Veda project for different platforms and run tests. They include commands for macOS static libraries, iOS XCFrameworks, and running the example application.

```bash
# macOS static library
./scripts/build-macos.sh

# iOS XCFramework
./scripts/build-ios.sh

# Run the example app to verify
cd flutter/example && flutter run -d macos
```

--------------------------------

### Recommend and Validate Models with ModelAdvisor

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/README.md

This snippet demonstrates how to detect the current device profile and retrieve model recommendations based on a specific use case. It also shows how to verify if a model can run on the device before proceeding with configuration.

```dart
final device = await DeviceProfile.detect();
final recommendations = ModelAdvisor.recommend(device, UseCase.chat);

for (final rec in recommendations) {
  print('${rec.model.name}: ${rec.score}/100 (${rec.fit})');
}

if (ModelAdvisor.canRun(model, device)) {
  final config = rec.optimalConfig;
}
```

--------------------------------

### Initialize and Execute Text Inference with Edge Veda

Source: https://context7.com/ramanujammv1988/edge-veda/llms.txt

Demonstrates how to initialize the Edge Veda engine with specific hardware configurations and perform both blocking and streaming text generation. Includes methods for monitoring memory usage and disposing of the engine instance.

```dart
import 'package:edge_veda/edge_veda.dart';

final edgeVeda = EdgeVeda();
await edgeVeda.init(EdgeVedaConfig(
  modelPath: '/path/to/llama-3.2-1b-instruct-q4_k_m.gguf',
  contextLength: 2048,
  numThreads: 4,
  useGpu: true,
  maxMemoryMb: 1536,
));

final response = await edgeVeda.generate(
  'Explain quantum computing in simple terms',
  options: GenerateOptions(
    maxTokens: 256,
    temperature: 0.7,
    topP: 0.9,
  ),
);
print('Response: ${response.text}');

await for (final chunk in edgeVeda.generateStream('Tell me a story')) {
  if (!chunk.isFinal) {
    stdout.write(chunk.token);
  }
}

await edgeVeda.dispose();
```

--------------------------------

### Manage Model Download Status with ModelManager

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/doc/API.md

Provides methods to check if a model is already downloaded, retrieve its local path, get its file size, and delete it. These operations help manage local model storage efficiently.

```dart
final isDownloaded = await modelManager.isModelDownloaded('model-id');
```

```dart
final modelPath = await modelManager.getModelPath('model-id');
```

```dart
final modelSize = await modelManager.getModelSize('model-id');
```

```dart
await modelManager.deleteModel('model-id');
```

--------------------------------

### Build and Run iOS XCFramework

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/example/README.md

Commands to verify the XCFramework build, clean, and rebuild the iOS application. Ensure the XCFramework is present before running the app.

```bash
ls ../ios/Frameworks/EdgeVedaCore.xcframework/ios-arm64/libedge_veda_full.a
```

```bash
cd ../../.. && ./scripts/build-ios.sh --clean --release
```

```bash
flutter clean && flutter pub get && flutter run --release
```

--------------------------------

### On-Device Retrieval-Augmented Generation (RAG)

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/README.md

This snippet details the implementation of an on-device RAG pipeline. It covers building a VectorIndex, adding documents and their embeddings, saving the index, and then querying the RAG pipeline to get answers grounded in the provided documents.

```dart
// 1. Build a knowledge base
final index = VectorIndex(dimensions: 768);
final docs = ['Flutter is a UI framework', 'Dart is a language', ...];

for (final doc in docs) {
  final emb = await edgeVeda.embed(doc);
  index.add(doc, emb.embedding, metadata: {'source': 'docs'});
}

// Save index to disk
await index.save(indexPath);

// 2. Query with RAG pipeline
final rag = RagPipeline(
  edgeVeda: edgeVeda,
  index: index,
  config: RagConfig(topK: 3, minScore: 0.5),
);

final answer = await rag.query('What is Flutter?');
print(answer.text);  // Answer grounded in your documents
```

--------------------------------

### Print SDK Configuration Summary (CMake)

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/core/CMakeLists.txt

This snippet uses CMake's message command to print a detailed summary of the Edge Veda SDK's configuration. It displays the SDK version, target platform, build type (shared/static), enabled backends (Metal, Vulkan, CPU), and the availability of integrated libraries like llama.cpp, whisper.cpp, and stable-diffusion.cpp.

```cmake
message(STATUS "")
message(STATUS "Edge Veda SDK Configuration:")
message(STATUS "  Version: ${PROJECT_VERSION}")
message(STATUS "  Platform: ${CMAKE_SYSTEM_NAME}")
message(STATUS "  Build shared: ${EDGE_VEDA_BUILD_SHARED}")
message(STATUS "  Build static: ${EDGE_VEDA_BUILD_STATIC}")
message(STATUS "  Metal backend: ${EDGE_VEDA_ENABLE_METAL}")
message(STATUS "  Vulkan backend: ${EDGE_VEDA_ENABLE_VULKAN}")
message(STATUS "  CPU backend: ${EDGE_VEDA_ENABLE_CPU}")
message(STATUS "  llama.cpp available: ${LLAMA_CPP_AVAILABLE}")
message(STATUS "  whisper.cpp available: ${WHISPER_CPP_AVAILABLE}")
message(STATUS "  stable-diffusion.cpp available: ${SD_CPP_AVAILABLE}")
message(STATUS "")
```

--------------------------------

### Configure Chat Sessions with Model Templates

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/README.md

This snippet shows how to initialize a ChatSession by selecting the appropriate ChatTemplateFormat for different model architectures to ensure correct output formatting.

```dart
// Llama 3.x models
final session = ChatSession(edgeVeda: ev, templateFormat: ChatTemplateFormat.llama3Instruct);

// Qwen3 with tool calling
final session = ChatSession(edgeVeda: ev, templateFormat: ChatTemplateFormat.qwen3);

// Phi 3.5 models
final session = ChatSession(edgeVeda: ev, templateFormat: ChatTemplateFormat.chatML);

// Gemma, TinyLlama, or unknown models
final session = ChatSession(edgeVeda: ev, templateFormat: ChatTemplateFormat.generic);
```

--------------------------------

### Configure stable-diffusion.cpp Integration in CMake

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/core/CMakeLists.txt

This CMake script configures the integration of the stable-diffusion.cpp library for image generation. It ensures that stable-diffusion.cpp uses the existing ggml target from llama.cpp and disables examples and shared libraries. It also enables Metal support for stable-diffusion.cpp on Apple platforms.

```cmake
if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/third_party/stable-diffusion.cpp/CMakeLists.txt")
    set(SD_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
    set(SD_BUILD_SHARED_LIBS OFF CACHE BOOL "" FORCE)
    set(BUILD_SHARED_LIBS OFF CACHE BOOL "" FORCE)
    if(IOS OR MACOS)
        set(SD_METAL ON CACHE BOOL "" FORCE)
    endif()
    add_subdirectory(third_party/stable-diffusion.cpp)
    set(SD_CPP_AVAILABLE TRUE)
else()
    message(WARNING "stable-diffusion.cpp not found in third_party/stable-diffusion.cpp - image generation disabled")
    set(SD_CPP_AVAILABLE FALSE)
endif()
```

--------------------------------

### On-Device LLM Intent Parsing Flow

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/examples/intent_engine/README.md

Illustrates the workflow of processing user input through an on-device LLM for smart home control. It shows how user commands are translated into tool calls that manipulate the home state.

```text
User Input ("I'm heading to bed")
        |
        v
ChatSession.sendWithTools()
        |
        v
Qwen3-0.6B (on-device LLM)
        |
        v
ToolCall objects (set_light, set_lock, set_tv, ...)
        |
        v
HomeState.applyAction() per tool call
        |
        v
Animated UI updates
```

--------------------------------

### Configure whisper.cpp Integration in CMake

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/core/CMakeLists.txt

This CMake script configures the integration of the whisper.cpp library for Speech-to-Text (STT) functionality. It ensures that whisper.cpp uses the existing ggml target from llama.cpp and disables examples, tests, server, SDL2, FFmpeg, and CoreML to streamline the build. It also ensures shared libraries are disabled.

```cmake
if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/third_party/whisper.cpp/CMakeLists.txt")
    set(WHISPER_USE_SYSTEM_GGML ON CACHE BOOL "" FORCE)
    set(WHISPER_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
    set(WHISPER_BUILD_TESTS OFF CACHE BOOL "" FORCE)
    set(WHISPER_BUILD_SERVER OFF CACHE BOOL "" FORCE)
    set(WHISPER_SDL2 OFF CACHE BOOL "" FORCE)
    set(WHISPER_FFMPEG OFF CACHE BOOL "" FORCE)
    set(WHISPER_COREML OFF CACHE BOOL "" FORCE)
    set(BUILD_SHARED_LIBS OFF CACHE BOOL "" FORCE)
    add_subdirectory(third_party/whisper.cpp)
    set(WHISPER_CPP_AVAILABLE TRUE)
else()
    message(WARNING "whisper.cpp not found in third_party/whisper.cpp - STT support disabled")
    set(WHISPER_CPP_AVAILABLE FALSE)
endif()
```

--------------------------------

### Access Pre-Configured Models in Dart

Source: https://context7.com/ramanujammv1988/edge-veda/llms.txt

This Dart code snippet demonstrates how to access various pre-configured AI models from the ModelRegistry. It includes examples for text, vision, speech, and image generation models, as well as how to retrieve all models or find a specific model by its ID. The code shows how to print model details like name, size, quantization, and capabilities.

```dart
import 'package:edge_veda/edge_veda.dart';

// Text models
final llama = ModelRegistry.llama32_1b;      // 668 MB, general chat
final phi = ModelRegistry.phi35_mini;         // 2.3 GB, complex reasoning
final gemma = ModelRegistry.gemma2_2b;        // 1.6 GB, versatile
final qwen = ModelRegistry.qwen3_06b;         // 397 MB, tool calling
final tiny = ModelRegistry.tinyLlama;         // 669 MB, speed-first

// Vision models
final smolvlm = ModelRegistry.smolvlm2_500m;  // 607 MB, camera analysis
final mmproj = ModelRegistry.smolvlm2_mmproj; // Vision projector

// Speech models
final whisperTiny = ModelRegistry.whisperTiny;  // 77 MB, fast STT
final whisperBase = ModelRegistry.whisperBase;  // 148 MB, quality STT

// Embedding models
final minilm = ModelRegistry.minilmL6;        // 46 MB, RAG/similarity

// Image generation
final sdTurbo = ModelRegistry.sdV21Turbo;     // 2.3 GB, text-to-image

// Get all models
final allModels = ModelRegistry.getAllModels();
final visionModels = ModelRegistry.getVisionModels();
final whisperModels = ModelRegistry.getWhisperModels();

// Find by ID
final model = ModelRegistry.getModelById('llama-3.2-1b-instruct-q4');
if (model != null) {
  print('Name: ${model.name}');
  print('Size: ${model.sizeBytes / (1024 * 1024)} MB');
  print('Quantization: ${model.quantization}');
  print('Capabilities: ${model.capabilities}');
}
```

--------------------------------

### Performance Tips

Source: https://github.com/ramanujammv1988/edge-veda/blob/main/flutter/doc/API.md

Tips for optimizing the performance of AI model inference using the Edge Veda SDK.

```APIDOC
## Performance Tips

- Start with Llama 3.2 1B for best speed/quality balance
- Keep context length ≤ 2048 on mobile devices
- Use streaming for responsive UI
- Monitor memory usage with `getMemoryUsageMb()`
- Enable GPU acceleration (Metal/Vulkan)
- Use appropriate temperature (0.7 for balanced, 0.3 for focused)
```