Add RAG and embeddings

Retrieval-augmented generation (RAG) adds selected source material to a model request. It is most useful when answers must depend on private, domain-specific, or frequently changing knowledge.

source -> chunk -> embed -> app-owned vector store
query  -> embed -> retrieve -> filter -> inject context -> agent

Stability by language

Language	Current contract
TypeScript	Embeddings plus chunkText(), embedRetrievalDocuments(), Retriever, VectorStore, ranking, retrieval, and context-message helpers are stable.
Python	embed(), embed_many(), and multimodal embedding helpers are stable. Python does not currently expose the same portable retrieval helper layer, so chunking, vector storage, retrieval, ranking, and context construction remain application-owned.

Provider support is capability-dependent. Choose an embedding-capable model and run an authenticated check for the exact model before shipping.

TypeScript retrieval flow

The SDK defines the portable document and store contracts; your adapter supplies persistence and tenant filtering:

import {
  chunkText,
  createRetrievalContextMessage,
  embedRetrievalDocuments,
  retrieveContext,
  runAgent,
  user,
  type Retriever,
  type VectorStore
} from "@zhivex-ai/sdk";

const documents = chunkText(policyText, {
  idPrefix: "refund-policy",
  metadata: { source: "refund-policy.md", tenantId }
});

const embedded = await embedRetrievalDocuments({
  model: embeddingModel,
  documents
});

const vectorStore: VectorStore = appVectorStore.forTenant(tenantId);
await vectorStore.upsert(embedded);

const retriever: Retriever = appRetriever.forTenant(tenantId);
const context = await retrieveContext({
  retriever,
  query: question,
  topK: 4
});

const result = await runAgent(agent, {
  userId,
  messages: [
    createRetrievalContextMessage(context, {
      title: "Use only this retrieved policy context."
    }),
    user(question)
  ]
});

console.log(result.outputText);

VectorStore is intentionally an interface. Implement upsert() and query() with your application database or vector service. The SDK core does not import PostgreSQL, pgvector, Supabase, or a vendor-specific vector client.

For a complete credential-free implementation, run the repository’s RAG agent example. It includes a deterministic embedding model and in-memory store.

Python embeddings

Python provides the embedding primitive used by an application-owned retrieval pipeline:

import asyncio
import os

from zhivex_ai import create_gemini, embed_many


async def main() -> None:
    provider = create_gemini(api_key=os.environ["GOOGLE_API_KEY"])
    result = await embed_many(
        model=provider.embedding_model("gemini-embedding-001"),
        values=[
            "Refunds require a receipt.",
            "Enterprise refunds require manual review.",
        ],
    )

    print(len(result.embeddings), len(result.embeddings[0]))


asyncio.run(main())

Persist the returned vectors with their source identity, tenant, document revision, and embedding-model identity. At query time, embed with a compatible model, apply tenant and authorization filters inside the query, and construct the final model message in application code.

Some providers support multimodal embeddings through native or portable content helpers. That does not mean every provider or model accepts images or files. Check the current provider contract before selecting an ingestion format.

What the application owns

SDK responsibility	Application responsibility
Portable embedding calls and normalized vectors	Credentials, allowed models, quota, and routing
TypeScript document and retrieval contracts	Database schema, vector index, driver, migrations, and backups
TypeScript chunking, similarity, ranking, and context formatting	Authentication, tenant filters, access-control predicates, and row-level security
Context injection helper	Source approval, redaction, prompt-injection controls, and citation UX
Normalized provider errors	Retry policy, ingestion jobs, dead-letter handling, and reindexing

Never accept a client-provided tenant id as authorization. Resolve the authenticated tenant first and bind the vector query to that scope on the server.

Keep retrieval inspectable

Store enough metadata to explain every answer:

• stable document and chunk ids;
• source URI or application record id;
• document revision and ingestion timestamp;
• tenant or workspace scope;
• embedding provider, model, and vector dimension;
• retrieval score and rank;
• the redacted context actually sent to the model.

Do not silently mix vectors created by incompatible models or dimensions. Reindex into a new namespace when changing the embedding model, and keep the old index available until validation and rollback windows close.

RAG is not conversation memory

Conversation memory carries recent messages or summaries between agent runs. RAG retrieves long-term semantic documents for the current request. Keep both explicit: do not turn a shared vector store into a hidden global prompt.

Retrieve only the smallest relevant context, label untrusted source text, and instruct tools and agents not to follow instructions found inside retrieved documents. For sensitive systems, validate source authorization again when materializing a result—not only when indexing it.

Validate quality and operations

Measure retrieval separately from answer quality:

1. verify that the correct source appears in top-k results;
2. test cross-tenant isolation and deleted-document behavior;
3. evaluate whether the answer is supported by the retrieved context;
4. test empty, conflicting, stale, and adversarial documents;
5. run a live embedding smoke for the exact provider and model;
6. record latency, token use, index version, and retrieval identifiers.

Continue with Observability and evaluations for regression datasets and safe traces, and Production architecture for identity, storage, and retention boundaries.

Full references

• TypeScript RAG guide
• TypeScript embeddings example
• Python embeddings example
• Python provider matrix