@paradoc/ai-tools

Last updated on

@paradoc/ai-tools is the contract every Paradoc AI adapter wraps. It has the ten tool definitions, their Zod input and output schemas, an execute function per tool, and a registry client. It has no AI framework dependency.

Use it directly to call the tools from your own code, or to build an adapter for a framework without one.

Installation

npm install @paradoc/ai-tools

Requires Node.js 22.13 or newer.

Tool definitions

toolDefinitions maps each tool name to its definition:

import { toolDefinitions } from "@paradoc/ai-tools"

const { name, description, input_schema, output_schema, execute } = toolDefinitions.render

operationNames lists the ten names in order: get_registry, get_artifact, inspect_artifact, validate_artifact, validate_input, fill, get_fill_state, update_fill, render, extract. The OperationName type is their union.

An adapter maps each definition to its framework's tool type. See the AI SDK, TanStack AI, and Mastra adapters.

Execute functions

Each tool has an execute function. They take the tool's snake_case input and an optional ParadocToolsConfig:

The execute functions do not throw for tool failures. They return a result with an error object (code, message, and optional path and retryable).

An artifact read from a URL or a registry must carry the current dated $schema. An inline artifact may omit it, but one it declares must be current. Otherwise the error code is missing-version, outdated-version, or unknown-version, and the message names the current version and paradoc migrate. See loading rules.

The execute functions parse their input with the tool's Zod schema. Pass the snake_case field names shown on each tool page.

import { executeFill, executeGetFillState, executeRender } from "@paradoc/ai-tools"

const source = {
  source: "registry",
  registry_url: "https://public.paradoc.dev",
  artifact_name: "pet-addendum",
} as const

const draft = await executeFill({
  ...source,
  data: {
    fields: { petName: "Buddy", species: "dog", weight: 45, isVaccinated: true },
    parties: {
      tenant: { id: "tenant-0", name: "Jane Doe" },
      landlord: { id: "landlord-0", name: "Acme Properties LLC", legalName: "Acme Properties LLC" },
    },
  },
})
if (!draft.accepted) throw new Error(draft.error?.message)

const state = await executeGetFillState({
  ...source,
  data: draft.data,
  evaluation_context: draft.evaluation_context,
})

const rendered = await executeRender({
  ...source,
  data: draft.data,
  evaluation_context: draft.evaluation_context,
  layer: "markdown",
})

Resolving a source

resolveSource(input, config?) loads the artifact for a source. It returns a ResolvedSource: { artifact, base_url?, artifact_url? }. The tools use it internally; use it when an adapter needs the artifact itself.

Request context

createToolExecutionContext(options?) makes a ToolExecutionContext that caches registry responses and carries an abort signal for one request or tool turn. Pass it as config.context. Options are signal and maxCacheEntries (default 32).

import { createToolExecutionContext, executeGetArtifact } from "@paradoc/ai-tools"

const context = createToolExecutionContext({ signal: request.signal })

const result = await executeGetArtifact(
  { registry_url: "https://public.paradoc.dev", artifact_name: "pet-addendum" },
  { context },
)

Create a new context for each request. The package never shares a cache between requests, so cached data cannot cross users or credentials.

Registry client

These helpers fetch from a Paradoc registry with the same URL and size checks the tools use:

Schemas and types

The package exports every input and output schema, such as FillInputSchema and FillOutputSchema, and the types inferred from them, such as FillInput and FillOutput. It also exports SourceSchema (the source union), SourceOperationSchema, ToolErrorSchema, ValidationIssueSchema, and the ToolDefinitions type.