bilberrydb/README.md

TypeScript/JavaScript SDK for BilberryDB vector search API

# BilberryDB - Image Search

Developer SDK for creating image search engines with BilberryDB.

## What it does

This library helps you find images that look similar to a given image. Just provide an image path, and it will return the most similar images from your database.

## Installation

```bash
npm install bilberrydb
```

## Getting API Keys

You need API keys to use BilberryDB:

1. Visit **www.bilberrydb.com**
2. Go to **API Key** section
3. Click **Create New API Key**
4. Enter API Key Name (like "My image search project")
5. Click **Create Key**

## Setup

1. Create a `.env` file in your project root:

```env
BILBERRY_API_KEY=your_api_key_here
BILBERRY_API_ID=your_registered_email_here
```

2. Replace `your_api_key_here` with your actual API key
3. Replace `your_registered_email_here` with the email you used to register

## Usage

```javascript
import * as bilberrydb from 'bilberrydb';
import dotenv from 'dotenv';

dotenv.config();

async function searchSimilarImages() {
    try {
        // Check if API keys exist
        if (!process.env.BILBERRY_API_KEY || !process.env.BILBERRY_API_ID) {
            throw new Error('Missing API keys in .env file');
        }
        
        // Connect to BilberryDB
        const client = bilberrydb.init({
            api_key: process.env.BILBERRY_API_KEY,
            api_id: process.env.BILBERRY_API_ID
        });
        
        // Search for similar images
        const vec = client.get_vec();
        const results = await vec.search("path/to/your/image.jpg", { 
            top_k: 5  // Get top 5 similar images
        });
        
        // Show results
        console.log(`Found ${results.length} similar images:`);
        
        results.forEach((result, index) => {
            const filename = result.filename || result.file_name || `item_${result.id}`;
            console.log(`${index + 1}. Image: ${filename}`);
            console.log(`   Similarity: ${result.similarity_score.toFixed(3)}`);
            console.log(`   File Type: ${result.file_type}`);
        });
        
    } catch (error) {
        console.error(`Search failed: ${error.message}`);
    }
}

// Run the search
searchSimilarImages();
```

## How to use

1. Replace `"path/to/your/image.jpg"` with the actual path to your image
2. Change `top_k: 5` to get more or fewer results
3. Run your script: `node your-script.js`

## What you get back

Each result includes:
- **filename**: Name of the similar image
- **similarity_score**: How similar it is (higher = more similar)
- **file_type**: Type of image file (jpg, png, etc.)
- **id**: Unique ID of the image

## Common issues

**"Missing API keys"**: Make sure your `.env` file has the correct API key and API ID.

**"Search failed"**: Check that:
- Your image path is correct
- Your API keys are valid
- You have internet connection

## Requirements

- Node.js 14 or higher
- Valid BilberryDB account and API keys

## License

Check the bilberrydb package license for details.