brainy/examples/browser-server-search/README.md

Brainy Browser-Server Search Example

This example demonstrates how to use Brainy in a browser, call a server-hosted version for search, store the results locally, and then perform further searches against the local instance.

Overview

The solution consists of:

1. A BrainyServerSearch class that handles the connection to the server and local storage
2. An HTML interface for testing the functionality
3. Server-side setup using the Brainy cloud wrapper

This approach allows you to:

• Search a server-hosted Brainy instance from a browser
• Store the search results in a local Brainy instance
• Perform further searches against the local instance without needing to query the server again
• Add data to both local and server instances

How It Works

1. The browser creates a local Brainy instance
2. It connects to the server-hosted Brainy instance using WebSocket
3. When a search is performed:
   • The query is sent to the server
   • The server returns the search results
   • The results are stored in the local Brainy instance
   • The results are displayed to the user
4. Subsequent searches can be performed against the local instance
5. A combined search mode first checks the local instance and then queries the server only if needed

Setup Instructions

Server Setup

1. Set up the Brainy cloud wrapper:

# Clone the repository if you haven't already
git clone https://github.com/soulcraft/brainy.git
cd brainy/cloud-wrapper

# Install dependencies
npm install --legacy-peer-deps

# Configure the server
cp .env.example .env
# Edit .env to configure your environment

# Build and start the server
npm run build
npm run start

2. Note the WebSocket URL of your server (e.g., wss://your-server.com/ws or ws://localhost:3000/ws for local development)

Client Setup

1. Copy the example files to your project:

cp -r examples/browser-server-search your-project/

2. Include the Brainy library in your project:

npm install @soulcraft/brainy --legacy-peer-deps

3. Open the HTML file in a browser or serve it using a local server:

# Using a simple HTTP server
cd your-project
npx http-server

4. Navigate to http://localhost:8080/browser-server-search/ in your browser

5. Enter the WebSocket URL of your server and start using the example

Usage

Using the HTML Interface

1. Enter the WebSocket URL of your Brainy server
2. Click "Connect" to establish a connection
3. Enter a search query and click one of the search buttons:
   • "Search Server" - Search the server and store results locally
   • "Search Local" - Search only the local instance
   • "Search Combined" - Search local first, then server if needed
4. To add data, enter text in the "Add Data" field and click "Add to Both"

Using the BrainyServerSearch Class in Your Code

import { BrainyServerSearch } from './index.js';

// Create a new instance
const brainySearch = new BrainyServerSearch('wss://your-brainy-server.com/ws');

// Initialize and connect
await brainySearch.init();

// Search the server and store results locally
const serverResults = await brainySearch.searchServer('machine learning', 5);

// Search the local instance
const localResults = await brainySearch.searchLocal('machine learning', 5);

// Perform a combined search
const combinedResults = await brainySearch.searchCombined('neural networks', 5);

// Add data to both local and server
const id = await brainySearch.add('Deep learning is a subset of machine learning', {
  noun: 'Concept',
  category: 'AI',
  tags: ['deep learning', 'neural networks']
});

// Close the connection when done
await brainySearch.close();

API Reference

BrainyServerSearch Class

Constructor

const brainySearch = new BrainyServerSearch(serverUrl);

• serverUrl (string): WebSocket URL of the Brainy server

Methods

• init(): Initialize the local Brainy instance and connect to the server
• searchServer(query, limit = 10): Search the server-hosted Brainy instance, store results locally, and return them
• searchLocal(query, limit = 10): Search the local Brainy instance
• searchCombined(query, limit = 10): Search both server and local instances, combine results, and store server results locally
• add(data, metadata = {}): Add data to both local and server instances
• close(): Close the connection to the server

Advanced Configuration

Custom Embedding Function

You can customize the embedding function used by the local Brainy instance:

import { createSimpleEmbeddingFunction } from '@soulcraft/brainy';

// In your code, before calling init():
brainySearch.setEmbeddingFunction(createSimpleEmbeddingFunction());

Persistent Storage

To enable persistent storage for the local Brainy instance:

// In your code, before calling init():
brainySearch.setStorageOptions({
  requestPersistentStorage: true
});

Troubleshooting

Connection Issues

• Ensure the server is running and accessible
• Check that the WebSocket URL is correct
• Verify that your browser supports WebSockets
• Check for CORS issues if the server is on a different domain

Search Issues

• Ensure the server has data to search
• Check that the query is not empty
• Verify that the server is properly configured for search

License

MIT