# Embedd HUB

Embedd HUB is a local-first Laravel workbench for exploring text embeddings. It lets users generate vectors, search similar stored phrases, and compare phrase proximity with Ollama and PostgreSQL vector storage.

## Features

- Generate embeddings for words, phrases, or multiline text.
- Store vectors in PostgreSQL with vector indexes when using pgvector.
- Search existing embeddings by semantic similarity.
- Compare multiple phrases with a pairwise similarity matrix and ranked pairs.
- Pick embedding models from the live Ollama `/api/tags` response.
- Show clear Ollama online/offline status before running embedding actions.
- Track per-user usage on the dashboard.

## Stack

- Laravel 13
- Livewire 4 single-file components
- Flux UI 2
- Laravel AI SDK
- PostgreSQL with vector storage
- Ollama for local embedding generation
- Tailwind CSS 4 and Vite
- Pest 4

## Requirements

- PHP 8.4
- Composer
- Node.js and npm
- PostgreSQL 18 or another PostgreSQL version with vector extension support
- Ollama running locally or on a reachable host

## Setup

Install PHP and JavaScript dependencies:

```bash
composer install
npm install
```

Create the environment file and app key:

```bash
cp .env.example .env
php artisan key:generate
```

Configure PostgreSQL in `.env`:

```dotenv
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=embedd_hub
DB_USERNAME=postgres
DB_PASSWORD=
```

Configure Ollama:

```dotenv
OLLAMA_URL=http://localhost:11434
OLLAMA_EMBEDDINGS_DIMENSIONS=768
```

The dimensions must match the embedding model you plan to use. Set this before running migrations so the vector column is created with the correct size.

Run migrations and build assets:

```bash
php artisan migrate
npm run build
```

## Ollama

Start Ollama and pull at least one embedding-capable model:

```bash
ollama serve
ollama pull nomic-embed-text
```

Embedd HUB does not use a configured default model. The tool pages call the Ollama API and list the models returned from `/api/tags`. If Ollama cannot return that model list, embedding actions are disabled and the UI shows an offline status.

## Development

For Laravel Herd, the app is available at:

```text
https://embedd-hub.test
```

Common commands:

```bash
npm run dev
php artisan test --compact
vendor/bin/pint --dirty --format agent
```

## Project Map

- `app/Services/EmbeddingWorkbench.php` - embedding generation, search, comparison, and Ollama model discovery.
- `app/Concerns/InteractsWithEmbeddingWorkbench.php` - shared Livewire state for model selection and availability.
- `resources/views/pages/embeddings` - the Embed, Search, and Compare pages.
- `resources/views/dashboard.blade.php` - usage dashboard.
- `database/migrations/*embedding*` - vector storage and usage event tables.
- `public/favicon.svg` - source SVG favicon asset. It is intentionally not referenced in templates.

## Testing

Run the full suite:

```bash
php artisan test --compact
```

Run only embedding tool tests:

```bash
php artisan test --compact tests/Feature/EmbeddingToolsTest.php
```