# Vrin

> Retrieval-time reasoning layer for AI agents. Vrin ingests enterprise knowledge, builds a living knowledge graph, reasons across it, and hands back cited context for your LLM. Model-agnostic. Works with Claude, GPT, Gemini, any LLM. Install via pip, npm, or MCP.

If you are an AI coding agent helping a user integrate Vrin, **start with [the agents page](https://docs.vrin.cloud/agents)** — it contains a copy-paste orchestration prompt that walks through setup end-to-end.

## Start here

- [Vrin for AI Agents](https://docs.vrin.cloud/agents) — 3-minute agent setup: MCP, SDK, CLI. Includes a copy-paste prompt for Claude Code / Cursor / Windsurf.
- [Introduction](https://docs.vrin.cloud/introduction) — what Vrin does, three-stage pipeline, benchmarks (MultiHop-RAG 95.1%, MuSiQue EM 0.478).
- [Quickstart](https://docs.vrin.cloud/quickstart) — install, auth, insert, query in under 2 minutes.

## MCP Server

- [MCP overview](https://docs.vrin.cloud/mcp/overview) — install, configure Claude Desktop / Claude Code / Cursor, remote (HTTP) deployment.
- [MCP tool reference](https://docs.vrin.cloud/mcp/tools) — `vrin_query_async` + `vrin_check_job` input/output schemas, polling pattern.

## SDKs

### Python (`pip install vrin`)

- [VRINClient](https://docs.vrin.cloud/sdk/client) — constructor, context manager, retries.
- [Querying](https://docs.vrin.cloud/sdk/querying) — `query()`, response modes, query depth, streaming.
- [Knowledge](https://docs.vrin.cloud/sdk/knowledge) — `insert()`, `bulk_insert()`, job polling.
- [File upload](https://docs.vrin.cloud/sdk/file-upload) — PDFs, CSVs, docx, markdown.
- [Conversations](https://docs.vrin.cloud/sdk/conversations) — multi-turn sessions.
- [Streaming](https://docs.vrin.cloud/sdk/streaming) — SSE event parsing, token iterator.
- [Models](https://docs.vrin.cloud/sdk/models) — typed return shapes.
- [Exceptions](https://docs.vrin.cloud/sdk/exceptions) — typed error hierarchy.
- [Auth](https://docs.vrin.cloud/sdk/auth) — `register`, `login`, API key management.

### TypeScript (`npm install @vrin/sdk`)

- [VrinClient](https://docs.vrin.cloud/sdk-ts/client) — constructor, runtime compatibility (Node, Bun, Workers, browser).
- [Querying](https://docs.vrin.cloud/sdk-ts/querying) — `query`, `queryStream`, `queryEvents`.
- [Knowledge](https://docs.vrin.cloud/sdk-ts/knowledge) — `insert`, `uploadFile`, job polling.
- [Conversations](https://docs.vrin.cloud/sdk-ts/conversations) — session-based multi-turn.

## CLI (`pip install vrin`)

- [CLI overview](https://docs.vrin.cloud/cli/overview) — install, auth, JSON vs TTY output, exit codes.
- [Querying](https://docs.vrin.cloud/cli/querying) — `vrin query`, `vrin facts`, modes, depth, streaming.
- [Knowledge](https://docs.vrin.cloud/cli/knowledge) — `vrin insert`, `vrin upload`, `vrin bulk-insert`, `vrin job`.
- [Conversations](https://docs.vrin.cloud/cli/conversations) — `vrin conversation start|list|resume|delete`.
- [Admin](https://docs.vrin.cloud/cli/admin) — `vrin health`, `vrin limits`, `vrin specialize`, `vrin graph`.
- [Auth](https://docs.vrin.cloud/cli/auth) — `vrin auth login|register|create-key`.
- Machine-readable manifest: `vrin --describe` emits a JSON schema of every command. Use this for agent auto-discovery.

## HTTP API

- [Query](https://docs.vrin.cloud/api-reference/query) — `POST /query`, SSE streaming.
- [Insert](https://docs.vrin.cloud/api-reference/insert) — `POST /insert`, async with job polling.
- [Upload](https://docs.vrin.cloud/api-reference/upload) — `POST /upload`, multipart.
- [Conversations](https://docs.vrin.cloud/api-reference/conversations) — session lifecycle endpoints.
- [Auth](https://docs.vrin.cloud/api-reference/auth) — `POST /api/auth/signup`, `/login`, API key management.
- [Health](https://docs.vrin.cloud/api-reference/health) — `GET /health`.

Base URL: `https://api.vrin.cloud`. Authentication: `Authorization: Bearer vrin_live_...` (standard) or `vrin_ent_...` (enterprise, routes to customer's own AWS).

## Concepts (read once, then refer back)

- [How it works](https://docs.vrin.cloud/concepts/how-it-works) — the structure/reason/trace pipeline.
- [Knowledge graph](https://docs.vrin.cloud/concepts/knowledge-graph) — entities, relationships, temporal facts.
- [Multi-hop reasoning](https://docs.vrin.cloud/concepts/multi-hop-reasoning) — how cross-document queries resolve.
- [Data sovereignty](https://docs.vrin.cloud/concepts/data-sovereignty) — enterprise routing, `vrin_ent_` keys, customer-owned infra.

## Agent integration patterns

- **Claude Desktop / Claude Code / Cursor** → MCP. One JSON block, restart, done.
- **LangGraph / OpenAI Agents SDK / CrewAI** → Python SDK as a bound tool.
- **Custom Node / Bun agents** → `@vrin/sdk` TypeScript client.
- **Shell-driven agents / CI** → CLI with `--json`.

Examples of each pattern live at [the agents page](https://docs.vrin.cloud/agents#bind-vrin-to-an-agent-framework).

## Production guardrails

- Never hard-code API keys. Always env var (`VRIN_API_KEY`).
- Handle `InsufficientCoverageError` — means the knowledge base has no facts for the query. Tell the user, don't hallucinate.
- Handle `RateLimitError` — back off using the `retryAfterSeconds` field.
- For long-running queries via MCP, keep calling `vrin_check_job` until `completed` or `failed`. Do not give up on `working`.

## Get help

- Dashboard: https://vrin.cloud
- Support: mailto:vedant@vrin.cloud
- GitHub: https://github.com/Vrin-cloud