# graphile-llm
LLM integration plugin for PostGraphile v5 — server-side text-to-vector embedding, resolve-time vector injection, and RAG (Retrieval-Augmented Generation) for pgvector columns using `@agentic-kit/ollama`.
## Table of contents
- [Installation](#installation)
- [Usage](#usage)
- [Features](#features)
- [Plugins](#plugins)
- [Configuration](#configuration)
- [RAG queries](#rag-queries)
- [License](#license)
## Installation
```bash
npm install graphile-llm
```
## Usage
```typescript
import { GraphileLlmPreset } from 'graphile-llm';
const preset = {
extends: [
GraphileLlmPreset({
defaultEmbedder: {
provider: 'ollama',
model: 'nomic-embed-text',
},
}),
],
};
```
The preset bundles all plugins listed below. You can also import each plugin individually (`createLlmModulePlugin`, `createLlmTextSearchPlugin`, `createLlmTextMutationPlugin`, `createLlmRagPlugin`) if you prefer a-la-carte.
## Features
- **Text-based vector search** — adds `text: String` field to `VectorNearbyInput`; clients pass natural language instead of raw float vectors
- **Text mutation fields** — adds `{column}Text: String` companion fields on create/update inputs for vector columns
- **RAG queries** — adds `ragQuery` and `embedText` root query fields; detects `@hasChunks` smart tags for chunk-aware retrieval
- **One metered route** — every embedding and completion is a call on the agentic-server gateway at `AGENTIC_SERVER_URL`, under the request's identity, so each model call is recorded; the gateway owns the upstream provider (Ollama, OpenAI, ...)
- **Per-database configuration** — reads `llm_module` from `constructive_routing_public.api_modules` for per-API provider config
- **Toggleable** — each capability (`enableTextSearch`, `enableTextMutations`, `enableRag`) can be independently enabled or disabled
- **Plugin-conditional** — fields only appear in the schema when the plugin is loaded
## Plugins
| Plugin | Description | Toggle |
|--------|-------------|--------|
| `LlmModulePlugin` | Resolves embedder and chat completer from config; stores on build context | Always included |
| `LlmTextSearchPlugin` | Adds `text: String` to `VectorNearbyInput` with resolve-time embedding | `enableTextSearch` (default: `true`) |
| `LlmTextMutationPlugin` | Adds `{column}Text` companion fields on mutation inputs | `enableTextMutations` (default: `true`) |
| `LlmRagPlugin` | Adds `ragQuery` and `embedText` root query fields | `enableRag` (default: `false`) |
## Configuration
```typescript
GraphileLlmPreset({
// Embedding provider (required for text fields and RAG)
defaultEmbedder: {
provider: 'ollama',
model: 'nomic-embed-text',
},
// Chat completion provider (required for RAG)
defaultChatCompleter: {
provider: 'ollama',
model: 'llama3',
},
// Toggle individual capabilities
enableTextSearch: true, // text field on VectorNearbyInput
enableTextMutations: true, // *Text companion fields on mutations
enableRag: false, // ragQuery + embedText root fields
// RAG defaults (overridable per-query)
ragDefaults: {
contextLimit: 10,
maxTokens: 4000,
minSimilarity: 0.3,
},
})
```
`AGENTIC_SERVER_URL` names the gateway and is required whenever an embedder or chat completer is configured; the schema build fails without it. Providers and models can also come from environment variables (`EMBEDDER_PROVIDER`, `EMBEDDER_MODEL`, `CHAT_PROVIDER`, `CHAT_MODEL`).
## RAG queries
When `enableRag: true` and tables have `@hasChunks` smart tags, the plugin adds:
```graphql
# Full RAG: embed prompt, search chunks, assemble context, call chat LLM
query {
ragQuery(
prompt: "What is machine learning?"
contextLimit: 5
minSimilarity: 0.3
) {
answer
sources { content similarity tableName parentId }
tokensUsed
}
}
# Standalone embedding
query {
embedText(text: "machine learning concepts") {
vector
dimensions
}
}
```