semantic-embed/README.md

A TypeScript SDK for embedding generation

# Semantic Embed SDK

A fast and lightweight TypeScript/JavaScript sdk for generating text embeddings based on FastAPI and other python tools.

## 📦 Overview

The **Semantic Embed SDK** is a TypeScript library designed to interface with the **Semantic Embed API** for generating text embeddings. With this SDK, developers can easily create and manage embeddings for their applications and work with semantic models powered by FastAPI. Whether you're building a recommendation system, semantic search, or performing content similarity analysis, **Semantic Embed** is your go-to tool for text embeddings.

---

## 🚀 Features

- **TypeScript Ready**: Fully written in TypeScript for type safety and developer-friendly experience.
- **FastAPI Integration**: Seamless integration with the Semantic Embed API built on FastAPI for optimal performance.
- **Easy-to-use API**: Simple and clean API design to get started with embedding generation effortlessly.
- **Environment Config**: Supports `.env` configuration for API keys and other environment variables.
- **Support for Custom Models**: Flexibility to work with different embedding models and configurations such as all-MiniLM-L6-v2 (384 dimensions), all-MiniLM-L12-v2 (384 dimensions), all-mpnet-base-v2 (768 dimensions) and finally e5-large-v2 (1024 dimensions).

---

## ⚡ Quick Start

Follow these steps to integrate the **Semantic Embed SDK** into your project:

### 1. Install the SDK

You can install the SDK via PNPM:

```bash
pnpm install semantic-embed
```

using Npm:

```bash
npm add semantic-embed
```

Or using Yarn:

```bash
yarn add semantic-embed
```

### 2. Setup API Key

Make sure you have an API key to access the **Semantic Embed API**, get one at [semantic-embed.uanelacomo.com](https://semantic-embed.uanelacomo.com). You can set it up in a `.env` file at the root of your project:

```plaintext
SEMANTIC_EMBED_API_KEY=your-api-key-here
```

### 3. Using the SDK

After installation, you can easily use the SDK to generate embeddings for your content.

#### Example Usage:

```typescript
import SemanticEmbed from "semantic-embed";

const semanticEmbed = new SemanticEmbed("your-api-key-if-not-in-env");

// Example text to generate embeddings
const text = "Semantic embedding is the future of search!";

async function generateEmbedding() {
  try {
    const embedding = await semanticEmbed.generateEmbedding(text);
    console.log("Generated Embedding: ", embedding);
  } catch (error) {
    console.error("Error generating embedding: ", error);
  }
}

generateEmbedding();
```

---

## 🔧 API

### `generateEmbedding(text: string): Promise<number[]>`

Generates a semantic embedding for the provided text.

**Arguments**:

- `text` (string): The text content for which you want to generate an embedding.

**Returns**:

- `Promise`: A promise that resolves to the generated embedding data.

## 🛠️ Development

To contribute or build the SDK from source:

### 1. Clone the Repository

```bash
git clone https://github.com/uanela/semantic-embed-sdk.git
cd semantic-embed
```

### 2. Install Dependencies

```bash
pnpm install
```

### 3. Build the Project

```bash
pnpm run build
```

### 4. Run in Development Mode

```bash
pnpm run dev
```

---

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 📫 Contact

For any issues or questions, please open an issue or contact [Uanela Como](mailto:uanelaluiswayne@gmail.com).