# 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 } } ```