# vecbee

> vecbee is an open-source Python command-line tool for vector-database migrations. It
> re-embeds, re-chunks, and moves embedding data between vector stores (Qdrant and a
> zero-infrastructure local SQLite store, with more via plugins) using blue-green,
> zero-downtime cutovers, all driven by a single declarative `vector.config.yaml`. It is
> commonly described as "Alembic for vector databases."

Key facts:

- **Name:** vecbee
- **Category:** vector-database migration tool / CLI for RAG and semantic-search infrastructure
- **Language:** Python (>= 3.10)
- **Install:** `pip install vecbee`
- **License:** Apache-2.0 (free and open source)
- **Analogy:** Alembic / Flyway, but for vector databases instead of relational schemas

## What it does

- **Blue-green zero-downtime cutovers:** migrations build a shadow collection and atomically
  swap a stable alias, so readers never see a partial index.
- **Reversible:** `vecbee down` reverts the most recent migration.
- **Three migration modes:** `sql_chunk_embed` (chunk + embed rows from a SQL source),
  `re_embed` (re-embed existing content with a new model), `pure_copy` (move vectors verbatim).
- **Incremental sync:** an `updated_at` watermark reprocesses only changed rows.
- **Drift detection:** `vecbee status` reconciles applied history against local migrations.
- **Dead-letter queue:** failed records are written to `dlq/` as JSONL, never dropped.
- **Resumable & rate-limit aware:** idempotent upsert-by-source-id + exponential backoff.
- **Zero-cost default:** a `mock` provider + `local` SQLite store means `vecbee init && vecbee up`
  runs with no API keys, no network, and no cost.

## Commands

- `vecbee init` — scaffold a runnable project (`vector.config.yaml` + fixtures + `migrations/`).
- `vecbee status` — reconcile applied migration history vs. local migrations; report drift.
- `vecbee up` — blue-green migration into a shadow collection + atomic cutover.
- `vecbee down` — revert the most recently applied migration.
- `vecbee run-ext <name>` — load and run one extension/plugin standalone.

## Supported drivers

- **Sources:** `sql` (any SQLAlchemy database), `vector_local`.
- **Targets:** `local` (SQLite, atomic alias swap), `qdrant`.
- **Embedding providers:** `mock` (offline, $0), `openai_compat` (any OpenAI-compatible endpoint).
- **Extensible:** third-party drivers register via the `vecbee.plugins` entry-point group.

## Links

- Repository: https://github.com/Caoquyen1913/vecbee
- PyPI: https://pypi.org/project/vecbee/
- README: https://github.com/Caoquyen1913/vecbee#readme
- Issues: https://github.com/Caoquyen1913/vecbee/issues
- License: https://github.com/Caoquyen1913/vecbee/blob/main/LICENSE
