@valv/core

The database-agnostic core of valv: the query grammar an LLM emits, the validator that checks it against your schema and policy, the policy injector, the shared SQL emitter, and the tool layer.

Most users install an adapter, not this package directly — @valv/clickhouse or @valv/prisma wrap core with introspection and a dialect. See the root README for the full guide. Reach for @valv/core directly only to build a custom adapter.

What this package exports

| Area | Exports | |---|---| | Orchestration | Valv (instantiated by adapters via createValv) | | Query grammar | QuerySchema; types Query, Expr, SelectItem | | Write grammar | InsertSchema, UpdateSchema, DeleteSchema; types Insert, Update, Delete, InjectedMutation | | Policy | PolicyFn, PolicyResult, FieldPolicy, DefaultContext | | Emission | emit, emitInsert/emitUpdate/emitDelete, the Dialect interface, BASE_FUNCTIONS, FnDef, ArgSpec | | Output shape | resultSchema, ResultColumn | | Tool formats | anthropic, openai, gemini formatters; NeutralTool, ToolToggle | | Adapter contract | ValvAdapter, SchemaMap, CompiledQuery, BoundParam, MutationResult | | Errors | ValidationError, PolicyViolationError; serializeResult |

Building an adapter

Everything above the database is shared, so a new adapter is three methods plus a small dialect. The shared emit does clause assembly, parenthesisation, and parameter ordering — your dialect only says how to quote identifiers and render placeholders.

import type { ValvAdapter, SchemaMap, Query, CompiledQuery, FnDef, Dialect } from "@valv/core"
import { emit, BASE_FUNCTIONS } from "@valv/core"

const myDialect: Dialect = {
  quoteId: (id) => `"${id.replace(/"/g, '""')}"`,
  placeholder: (i) => `$${i + 1}`,
  // functions: { ...dialect-specific aggregates }
}

class MyAdapter implements ValvAdapter {
  async introspect(): Promise<SchemaMap> {
    // describe your tables → resources, fields (with coarse `type` + `nativeType`), relations
  }
  compile(query: Query, catalog: SchemaMap): CompiledQuery {
    return emit(query, catalog, myDialect)
  }
  async execute(sql: string, params?: unknown[]): Promise<unknown[]> {
    // run the parameterized statement, return rows
  }
  functions(): Record<string, FnDef> {
    return { ...BASE_FUNCTIONS, ...myDialect.functions }
  }
  // Optional — implement to support writes. The mutation is already validated
  // and policy-injected; emit it with emitInsert/emitUpdate/emitDelete and run it.
  // mutate?(m: InjectedMutation, catalog: SchemaMap): Promise<MutationResult>
}

Validation and policy injection never reach the adapter — security stays in core. A Dialect can also declare extra functions (FnDef: argument signature, return type, render), which become callable in the query grammar and are surfaced to the model through the query tool's enum. Writes are optional: implement mutate (the mutation arrives already validated and policy-injected) to opt in, or omit it for a read-only adapter.

Type-safe resource names

InferResources derives resource names from a typed client, so a misspelled policy key is a compile error:

import type { InferResources } from "@valv/core"
const valv = await createValv<typeof prisma, Ctx>(prisma)  // policy keys autocomplete

License

MIT