Knowledge Base (RAG)

The Knowledge Base API is the developer surface of Pulse Cortex, the knowledge engine. It lets you ground an agent's answers in your own documents instead of relying on whatever the model already knows. Ingest text, a file, or a URL; link it to one or more agents; and opt in to retrieval on any chat call — Cortex finds the most relevant passages and injects them, with a citation on each, before the agent answers.

This is retrieval-augmented generation done as a compiler: nothing is fine-tuned, no model weights change. Each chat call retrieves fresh, relevant chunks at request time, so updating a source updates every future answer immediately.

How it works

Embeddings run through the same provider abstraction used across PulseLABS — OpenAI's text-embedding-3-small when an OpenAI key is configured, or Ollama's nomic-embed-text for fully local setups. Both produce 768-dimensional vectors, so retrieval works identically regardless of which provider is active.

1. Compile — any format (PDF, DOCX, XLSX, PPTX, CSV, HTML, or a URL) is normalized to markdown and chunked along its real heading structure; every chunk keeps its section path and an LLM one-liner situating it in the document.
2. Embed — each chunk is embedded once at ingestion and stored alongside a full-text index, so both semantic and keyword search are always available.
3. Retrieve — at chat time the query runs hybrid full-text + vector search, fused with Reciprocal Rank Fusion and reranked, returning the top-K passages with source, section, and similarity.
4. Inject — the matches are added to the agent's context as numbered citations [1]..[K]; the agent cites them inline, or says the knowledge base doesn't cover the question instead of guessing.

Ingesting a Knowledge Source

Send raw text — a doc page, a support FAQ, a pricing sheet, transcript, whatever your agent should know. PulseLABS chunks and embeds it server-side; there's no separate upload-then-process step.

{
  "id": "kns_xxx",
  "chunkCount": 14
}

curl -X POST https://api.pulse-labs.fr/v1/knowledge-sources \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pricing FAQ",
    "description": "Internal pricing rules and edge cases",
    "content": "Annual plans get a 20% discount. Refunds are issued within 14 days of purchase...",
    "agentIds": ["agent_xxx"]
  }'

{
  "sources": [
    {
      "id": "kns_xxx",
      "name": "Pricing FAQ",
      "description": "Internal pricing rules and edge cases",
      "createdAt": "2026-06-20T10:00:00Z",
      "_count": { "chunks": 14 },
      "agents": [{ "id": "agent_xxx", "name": "Victoria Chen" }]
    }
  ]
}

{
  "source": {
    "id": "kns_xxx",
    "name": "Pricing FAQ",
    "agents": [{ "id": "agent_xxx", "name": "Victoria Chen" }],
    "_count": { "chunks": 14 }
  }
}

// 204 No Content

Linking Sources to Agents

A source only feeds an agent's answers once it's linked. Link it at ingestion time via agentIds, or link/unlink afterwards with these endpoints.

{
  "agent": {
    "id": "agent_xxx",
    "knowledgeSources": [{ "id": "kns_xxx", "name": "Pricing FAQ" }]
  }
}

// 204 No Content

Retrieving During Chat

Retrieval is opt-in per call — pass knowledge.enabled: true on a normal Agent Chat request. PulseLABS embeds the user's message, finds the top-K matching chunks across the agent's linked sources, and injects them as high-priority context before generating the response.

Request fields:

"knowledge": {
  "enabled": true,   // default false
  "topK": 5          // chunks to retrieve, 1–20, default 5
}

The response includes a knowledgeUsed array so you can cite or surface which passages informed the answer:

"knowledgeUsed": [
  {
    "sourceId": "kns_xxx",
    "sourceName": "Pricing FAQ",
    "chunkPreview": "Annual plans get a 20% discount. Refunds are issued within 14 days...",
    "similarity": 0.91
  }
]

curl -X POST https://api.pulse-labs.fr/v1/agents/agent_xxx/chat \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Do annual plans get a discount?",
    "knowledge": { "enabled": true, "topK": 5 }
  }'