# smartbotic-vectorapi

A general-purpose, client-agnostic **REST API in front of [`smartbotic-database`](https://git.smartbotics.ai/fszontagh/smartbotic-database)** for storing data from automation workflows. It stores **RAG embedding vectors** (with cosine similarity search) and **arbitrary JSON documents**, organized into **projects** (isolated namespaces) and protected by **API keys with per-project grants**.

n8n workflows are the primary client, but any HTTP client can use it. A React admin console ships alongside.

- **Multi-project** — collections live in isolated project namespaces, addressed as a URL path segment (`/api/v1/projects/{project}/...`), like MySQL databases.
- **Multi-key auth** — each API key is granted access to one or more projects (or all, `*`); `admin` keys manage projects and keys. Bearer-token for the API; cookie session for the web UI.
- **RAG** — store a precomputed vector, or send text and have it embedded via OpenAI; then run cosine similarity search.
- **JSON CRUD** — full create/read/update/patch/delete with filtered find.
- **Dynamic config** — only a minimal bootstrap `config.json` on disk; everything else (keys, OpenAI settings, CORS, etc.) lives in the database and **hot-reloads** without a restart.
- **Self-describing** — `GET /openapi.json` (OpenAPI 3.1), `GET /llms.txt` (agent-friendly summary), and a rendered docs page at `/docs`.

## Architecture

```
  n8n / clients ──HTTP+Bearer──┐
                               ▼
  admin browser ──cookie──▶ smartbotic-vectorapi ──gRPC──▶ smartbotic-database
                               │  (libsmartbotic-db-client)
                               └──HTTPS──▶ api.openai.com/v1/embeddings
```

The server is C++20 (cpp-httplib, OpenSSL). Project multi-tenancy is threaded at the gateway boundary via `qualify(project, collection)`; authorization (key → project grants) is the API's own layer. The web UI is React 19 + Vite + TypeScript + TailwindCSS + Monaco, served by the same binary (same-origin) or via the Vite dev proxy.

| Component | Path |
|---|---|
| Server | `src/` → `smartbotic-vectorapi` binary |
| Web UI | `webui/` (React) → built assets |
| API spec | `api/openapi.json`, `api/llms.txt` |
| Packaging | `packaging/` (Debian `.deb`, systemd, Docker) |
| Design + plans | `docs/superpowers/specs/`, `docs/superpowers/plans/` |
| API reference | `docs/api.md` |

## Install (Debian 13 / trixie)

The packages are published to the smartbotics apt repository.

```bash
# one-time repo setup (see /data/smartbotics-deb-repo for credentials)
curl -fsSL https://repository.smartbotics.ai/add-repo.sh | sudo bash -s -- --user <user> --password <pass>

sudo apt update
sudo apt install smartbotic-vectorapi smartbotic-vectorapi-webui
```

On first start the service generates an **admin API key** and logs it **once**:

```bash
journalctl -u smartbotic-vectorapi | grep "Generated initial admin API key"
```

Optionally seed secrets before first boot in `/etc/smartbotic-vectorapi/vectorapi.env`:

```ini
SMARTBOTIC_VECTORAPI_KEY=<your-admin-key>     # seed the admin key instead of auto-generating
OPENAI_API_KEY=sk-...                          # enables text→embedding generation for RAG
```

The service listens on `:8080` (configurable). The web console is at `http://<host>:8080/`; the rendered API docs are at `/docs`.

## Build from source

Requires: `cmake`, `ninja`, `g++` (C++20), `pkg-config`, `libsmartbotic-db-client-dev (>= 2.3.0)`, `nlohmann-json3-dev`, `libspdlog-dev`, `libssl-dev`, `libsystemd-dev`, and `nodejs`/`npm` (for the web UI). cpp-httplib is fetched via CMake.

```bash
# backend + web UI
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DBUILD_WEBUI=ON -S .
cmake --build build -j"$(nproc)"

# run the tests (needs a running smartbotic-database on localhost:9004 for the integration tests)
cmake -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_WEBUI=OFF -S . && cmake --build build && ctest --test-dir build

# run locally (point --webui-dir at the built assets)
SMARTBOTIC_VECTORAPI_KEY=dev ./build/src/smartbotic-vectorapi \
  --config config/config.json --share-dir "$PWD/api" --webui-dir "$PWD/build/webui/dist"
```

The web UI alone:

```bash
cd webui && npm install && npm run dev      # dev server on :3000, proxies /api + /ui to :8080
cd webui && npm run build                   # production build → dist/
```

## Packaging

```bash
./packaging/build.sh --local                 # native .debs for the current system → dist/local/
./packaging/build.sh                          # Debian-13 .debs via Docker → dist/debian13/
./packaging/build.sh --repo --suite trixie --sync   # build + publish to repository.smartbotics.ai
```

Produces two packages: `smartbotic-vectorapi` (server + systemd unit + config + `openapi.json`/`llms.txt` + rendered `/docs`) and `smartbotic-vectorapi-webui` (the built admin console).

## Quick API tour

```bash
KEY=<admin-key>; BASE=http://localhost:8080

# create a project + a vector collection (OpenAI text-embedding-3-small = 1536 dims)
curl -s -X POST $BASE/api/v1/projects -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"name":"acme"}'
curl -s -X POST $BASE/api/v1/projects/acme/collections -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"memories","kind":"vector","vector_dimension":1536,"embedding_model":"text-embedding-3-small"}'

# store a RAG item from text (embedded server-side) and search it
curl -s -X POST $BASE/api/v1/projects/acme/collections/memories/vectors -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"text":"the user prefers dark mode","metadata":{"src":"n8n"}}'
curl -s -X POST $BASE/api/v1/projects/acme/collections/memories/search -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"query_text":"dark mode","top_k":5}'
```

Full reference: [`docs/api.md`](docs/api.md), the live `/docs` page, and `GET /openapi.json`.

## License

Proprietary — Smartbotics AI.