# VectorAI Full Technical Specification for Autonomous Agents & LLMs
> Canonical Base URL: https://vector.acadmyai.com
> Full OpenAPI Specification: https://vector.acadmyai.com/v1/openapi.json
> Python SDK: vectorai-sdk (v1.1.0)
> TypeScript SDK: @vectorai-sdk/sdk (v1.0.1)

## 1. Overview & Architecture
VectorAI is a Zero-Trust Vector Engine and RAG Gateway.
Features:
1. In-process Presidio PII tokenization (zero-knowledge masking).
2. Wire-speed prompt injection firewall stripping adversarial payloads before vector embedding.
3. Decoupled Vector Storage: PostgreSQL pgvector, Qdrant cluster, or In-Memory RAM.
4. BYOK Multi-Model Embedding Router: Google Gemini (text-embedding-004), OpenAI (text-embedding-3-small/large), Cohere (embed-english-v3.0), Voyage AI, and HuggingFace serverless (BAAI/bge-small-en-v1.5).
5. Scoped Integration Profiles: Isolated vector namespaces per application, agent, or bot (e.g., `tradeai`, `launch_sdr`, `grokbot`, `support_copilot`).

## 2. Authentication & Headers
All requests to `/v1/*` must pass:
- Header: `Authorization: Bearer <API_KEY>`
- Valid prefixes:
  - `vec_live_` (Production integration profile key)
  - `sk-lvl1-` (Sandbox / developer test key)
- Missing or invalid key yields `401 Unauthorized` with `{ "detail": "Invalid or missing API key" }`.

## 3. Endpoints & JSON Schemas

### POST /v1/ingest
Ingests, chunks, redacts PII, generates embeddings, and persists vectors.
Request Body Schema:
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "IngestRequest",
  "type": "object",
  "properties": {
    "text": { "type": "string", "description": "Raw text chunk or document." },
    "collection_name": { "type": "string", "default": "default_collection" },
    "metadata": { "type": "object", "additionalProperties": true },
    "pii_redaction": { "type": "boolean", "default": true },
    "threat_action": { "type": "string", "enum": ["block", "sanitize", "monitor"], "default": "sanitize" }
  },
  "required": ["text"]
}
```

### POST /v1/search
Performs vector similarity search against active driver.
Request Body Schema:
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "SearchRequest",
  "type": "object",
  "properties": {
    "query": { "type": "string", "description": "Semantic search query." },
    "collection_name": { "type": "string", "default": "default_collection" },
    "top_k": { "type": "integer", "default": 5, "minimum": 1, "maximum": 100 },
    "filter": { "type": "object", "description": "Metadata key-value filter." },
    "threat_action": { "type": "string", "enum": ["block", "sanitize", "monitor"], "default": "sanitize" }
  },
  "required": ["query"]
}
```

### POST /v1/jobs/batch-ingest
Submits a background batch ingestion job.
Returns `202 Accepted` with `{ "job_id": "job_...", "status": "processing" }`.

### GET /v1/jobs/{job_id}
Returns `{ "job_id": "...", "status": "completed" | "processing" | "failed", "processed_items": 100, "failed_items": 0 }`.

### POST /v1/user/test-db
Tests connectivity and runs CRUD verification against PostgreSQL pgvector or Qdrant cluster.
Request Body:
```json
{
  "provider": "pgvector" | "qdrant" | "memory",
  "url": "postgresql://...",
  "qdrant_url": "https://...",
  "qdrant_api_key": "..."
}
```

### GET /v1/audit
Returns chronological audit log of security threats, PII detections, and vector operations.

## 4. Multi-Platform Bot Integration Patterns

### Pattern A: GrokBot / X (Twitter) Bot
```python
import os
from vectorai import VectorAI

vectorai = VectorAI(api_key=os.environ["VECTORAI_API_KEY"])

def on_tweet_mention(tweet_id: str, author: str, tweet_text: str):
    # 1. Ingest tweet into user-specific or global thread memory
    vectorai.ingest(
        text=tweet_text,
        collection_name="grokbot_mentions",
        metadata={"tweet_id": tweet_id, "author": author},
        threat_action="sanitize"
    )
    
    # 2. Retrieve grounded context from knowledge base
    context = vectorai.search(
        query=tweet_text,
        collection_name="grokbot_knowledge",
        top_k=3
    )
    return context.results
```

### Pattern B: Telegram Bot
```python
from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes
from vectorai import VectorAI

vectorai = VectorAI(api_key="vec_live_YOUR_KEY")

async def ask(update: Update, context: ContextTypes.DEFAULT_TYPE):
    query = " ".join(context.args)
    res = vectorai.search(query=query, collection_name="tg_docs", top_k=2)
    reply = "\n\n".join([f"• {hit.payload.get('text')}" for hit in res.results])
    await update.message.reply_text(reply or "No relevant information found.")

app = ApplicationBuilder().token("TG_BOT_TOKEN").build()
app.add_handler(CommandHandler("ask", ask))
app.run_polling()
```

### Pattern C: Discord Bot
```python
import discord
from discord.ext import commands
from vectorai import VectorAI

bot = commands.Bot(command_prefix="!", intents=discord.Intents.all())
vectorai = VectorAI(api_key="vec_live_YOUR_KEY")

@bot.command()
async def search(ctx, *, query: str):
    hits = vectorai.search(
        query=query,
        collection_name="discord_server_memory",
        filter={"channel_id": {"$eq": str(ctx.channel.id)}},
        top_k=3
    )
    msg = "\n".join([f"> {h.payload.get('text')}" for h in hits.results])
    await ctx.send(msg or "No matches found.")

bot.run("DISCORD_BOT_TOKEN")
```

## 5. Universal Filter Grammar
Filters match against the JSON metadata stored with each vector chunk:
- Exact match: `{"category": "billing"}`
- Equal: `{"tier": {"$eq": "enterprise"}}`
- In array: `{"role": {"$in": ["admin", "dev"]}}`
- Comparison: `{"created_timestamp": {"$gte": 1700000000}}`
- Logical AND: `{"$and": [{"dept": "engineering"}, {"clearance": "L5"}]}`
- Logical OR: `{"$or": [{"is_public": true}, {"owner_id": "usr_123"}]}`

## 6. HTTP Status Codes
- `200 OK`: Request succeeded.
- `202 Accepted`: Asynchronous batch job queued.
- `400 Bad Request`: Invalid request JSON body or missing required field.
- `401 Unauthorized`: Missing or invalid API key.
- `403 Forbidden`: Prompt injection threat detected with `threat_action="block"`.
- `429 Too Many Requests`: Rate limit exceeded (Sandbox 60/min, Pro 120/min, Enterprise 1200/min).
- `500 Internal Server Error`: Vector database connection or embedding generation error.