> ## Documentation Index
> Fetch the complete documentation index at: https://docs.geekhub.mx/llms.txt
> Use this file to discover all available pages before exploring further.

# Vector stores

> Colecciones de vectores gestionadas: sube texto, chunkeamos y embed'eamos por ti; consulta con top-k semántico. Sin Pinecone.

Vector stores es RAG-as-a-service: creas una colección, subes texto, y Geek Hub se encarga de chunking + embedding + almacenamiento en pgvector con índice HNSW. Consulta con top-k por similitud coseno.

Cuándo usar esto en vez de tu propio pgvector/Pinecone:

* Prototipo de RAG en horas, no días
* Uno menos servicio que operar
* Cost inline en cada operación (mismo tokenización que /v1/embeddings)
* Aisla por org via RLS de Supabase

Cuándo NO:

* Más de \~1M chunks — el índice HNSW empieza a costar RAM en Postgres
* Metadata filtering complejo (hybrid search, reranking) — usa una DB dedicada
* Ya tienes pipeline de embeddings — no ganas nada

## Crear colección

```bash theme={null}
curl -X POST https://api.geekhub.mx/v1/vector-stores \
  -H "Authorization: Bearer ghub_sk_live_TU_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "docs-producto",
    "model": "openai/text-embedding-3-small"
  }'
```

Devuelve el `id` del store, que usarás en las siguientes llamadas.

## Subir texto

```bash theme={null}
curl -X POST https://api.geekhub.mx/v1/vector-stores/$STORE_ID/files \
  -H "Authorization: Bearer ghub_sk_live_TU_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "faq.md",
    "text": "…contenido completo del documento…",
    "chunk_tokens": 512,
    "overlap_tokens": 64,
    "metadata": { "source": "notion", "version": "v2" }
  }'
```

El gateway:

1. Split del texto en chunks de \~512 tokens con 64 de overlap
2. Embed todos los chunks (batch al proveedor)
3. Insert en pgvector con tu `metadata`
4. Cobra los `input_tokens` del embedding

Response:

```json theme={null}
{
  "id": "file_uuid",
  "store_id": "store_uuid",
  "filename": "faq.md",
  "chunk_count": 24,
  "input_tokens": 12480,
  "created_at": "2026-07-06T18:03:12Z"
}
```

## Consultar top-k

```bash theme={null}
curl -X POST https://api.geekhub.mx/v1/vector-stores/$STORE_ID/query \
  -H "Authorization: Bearer ghub_sk_live_TU_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cómo genero mi API key",
    "top_k": 5
  }'
```

Response:

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "chunk_uuid",
      "file_id": "file_uuid",
      "chunk_index": 3,
      "content": "Para generar una API key, ve a /dashboard/keys …",
      "metadata": { "source": "notion", "version": "v2" },
      "similarity": 0.83
    }
  ],
  "usage": { "prompt_tokens": 7 }
}
```

`similarity` va de 1 (idéntico) a -1 (opuesto). En la práctica útil > 0.7.

## Otros endpoints

* `GET /v1/vector-stores` — lista todos los stores de tu org
* `GET /v1/vector-stores/:id` — detalle + files
* `DELETE /v1/vector-stores/:id` — borra store + cascade a files y chunks

## Costos

* Embedding de upload y query: tokens × precio del modelo del store
* Almacenamiento: gratis en v1 (subject a change si empieza a costar)
* Query: solo el embedding de la query (no del corpus almacenado)

## Roadmap

* Upload de PDF/DOCX con parsing server-side
* Hybrid search (BM25 + vectors)
* Metadata filtering con `filter: { key: value }`
* Chunking configurable por semantic boundaries (usando LLM)