ollama-bridge

High-performance Node.js bindings for Ollama integration.

Installation

From NPM

npm install ollama-bridge

From Source (Development)

# Clone and build Rust library first
git clone https://github.com/aumbriac/ollama-bridge.git
cd ollama-bridge
cargo build --release

# Install Node.js bindings
cd bindings/node
npm install
npm run build

Quick Start

Automatic Setup (Recommended)

import { OllamaClient, ChatMessage } from 'ollama-bridge';

async function main() {
    // Create client with auto-install enabled
    // This will automatically install and start Ollama if needed!
    const client = new OllamaClient({
        autoInstall: true,
        autoStart: true
    });
    
    // Chat example - Ollama will be set up automatically
    const messages = [
        ChatMessage.system('You are a helpful assistant.'),
        ChatMessage.user('What is the capital of France?')
    ];
    
    const response = await client.chat('llama3:latest', messages);
    console.log(response.content);
}

main();

Manual Setup

import { OllamaClient, ChatMessage } from 'ollama-bridge';

async function main() {
    const client = new OllamaClient();
    
    // Check if Ollama is running
    if (!client.healthCheck()) {
        console.log('Please start Ollama: ollama serve');
        return;
    }
    
    const response = await client.chat('llama3:latest', messages);
    console.log(response.content);
}

main();

API Reference

OllamaClient

interface OllamaConfig {
    baseUrl?: string;      // Default: http://localhost:11434
    autoStart?: boolean;   // Auto-start Ollama if not running (default: true)
    autoInstall?: boolean; // Auto-install Ollama if not found (default: false)
}

class OllamaClient {
    // New config-based constructor (recommended)
    constructor(config?: OllamaConfig)
    
    // Backward-compatible constructors
    constructor(baseUrl?: string)
    constructor()
    
    // Chat with a model
    chat(model: string, messages: ChatMessage[]): Promise<ChatResponse>
    
    // Generate text
    generate(model: string, prompt: string): Promise<GenerateResponse>
    
    // Check if Ollama is running
    healthCheck(): boolean
}

Configuration Examples

// Automatic setup - installs and starts Ollama if needed
const client = new OllamaClient({
    autoInstall: true,
    autoStart: true
});

// Custom URL with auto-start only
const client = new OllamaClient({
    baseUrl: 'http://remote-ollama:11434',
    autoStart: true,
    autoInstall: false
});

// Manual setup - no automation
const client = new OllamaClient({
    autoStart: false,
    autoInstall: false
});

// Backward compatible - same as default
const client = new OllamaClient();
const client = new OllamaClient('http://localhost:11434');

ChatMessage Helpers

// Create messages easily
ChatMessage.user('Hello!')                     // User message
ChatMessage.system('You are helpful.')         // System message
ChatMessage.assistant('How can I help?')       // Assistant message

// With images
ChatMessage.user('What is this?', ['base64_image'])

Types

interface ChatMessage {
    role: 'user' | 'assistant' | 'system';
    content: string;
    images?: string[];
}

interface ChatResponse {
    content: string;
}

interface GenerateResponse {
    response: string;
}

Examples

See the examples/node directory for complete examples.

Local Development

Using in Another Project

# Method 1: npm link (best for development)
cd bindings/node
npm link
cd /your/project
npm link ollama-bridge

# Method 2: Direct install
cd /your/project
npm install /path/to/ollama-bridge/bindings/node

# Method 3: Pack and install
cd bindings/node
npm pack  # Creates ollama-bridge-0.1.0.tgz
cd /your/project
npm install /path/to/ollama-bridge-0.1.0.tgz

Building

npm run build  # Build everything
tsc           # Just TypeScript
node-gyp rebuild  # Just native module

Testing

npm test

License

MIT OR Apache-2.0