AI Vectors Plugin

The AI Vectors plugin adds embedding storage and semantic search to any FastCMS collection. Store text embeddings, then search by meaning instead of keywords.

Requires: AI Core plugin

Installation

cp -r ai_vectors/ plugins/ai_vectors/
# Also install ai_core if you haven't already
cp -r ai_core/ plugins/ai_core/

Optional: install numpy for faster similarity search (~10x):

pip install numpy

Without numpy, a pure-Python fallback is used (works fine for up to ~50k vectors).

How It Works

1. You send text to the /embed endpoint
2. AI Vectors calls the configured AI provider to generate an embedding vector
3. The embedding is stored in data/vectors.db (a separate SQLite file)
4. When you search, your query is also embedded, then compared against stored vectors using cosine similarity

The vector database is completely isolated from your main FastCMS database — clean separation.

API Endpoints

All endpoints are mounted at /api/v1/plugins/ai/vectors/.

POST /ai/vectors/embed

Store an embedding for a piece of text.

curl -X POST http://localhost:8000/api/v1/plugins/ai/vectors/embed \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "articles",
    "record_id": "abc123",
    "field": "content",
    "text": "FastCMS is an open-source Backend-as-a-Service built with FastAPI.",
    "metadata": {"source": "readme.md"}
  }'

Response:

{
  "id": "emb-uuid",
  "dimensions": 1536
}

POST /ai/vectors/search

Search for semantically similar content.

curl -X POST http://localhost:8000/api/v1/plugins/ai/vectors/search \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "articles",
    "query": "how to set up a backend quickly",
    "limit": 5,
    "threshold": 0.3
  }'

Response:

{
  "results": [
    {
      "record_id": "abc123",
      "field": "content",
      "text": "FastCMS is an open-source Backend-as-a-Service...",
      "score": 0.8742,
      "metadata": {"source": "readme.md"}
    }
  ],
  "query": "how to set up a backend quickly",
  "collection": "articles"
}

DELETE /ai/vectors/collection/{name}

Delete all embeddings for a collection.

curl -X DELETE http://localhost:8000/api/v1/plugins/ai/vectors/collection/articles

GET /ai/vectors/stats

Get vector store statistics.

{
  "total_embeddings": 1542,
  "collections": {
    "articles": 500,
    "docs": 1042
  },
  "has_numpy": true
}

Use Cases

• Semantic search — Find content by meaning, not just keywords
• Recommendation engine — Find similar articles/products
• Deduplication — Detect near-duplicate content
• Classification — Compare against known categories

Storage

Embeddings are stored in data/vectors.db, separate from the main application database. This file can be safely deleted to reset all embeddings — they can be regenerated from your source data.

Each embedding is stored as a binary blob (float32 array) with metadata:

Dependencies

• Required: AI Core plugin
• Optional: numpy (faster similarity search)