@paradoc/ai-tools API

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. To start using it, see Use another framework.

npm install @paradoc/ai-tools

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 Write an adapter and the Adapters reference.

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. Use another framework has a full example.

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:

Model output

The adapters use these helpers to bound the copy of a result that goes to the model. An adapter for another framework uses them the same way.

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, FillTargetSchema and FillItemStateSchema (the targets in a get_fill_state result), and the ToolDefinitions type.

Configuration

Every execute function and every adapter accepts ParadocToolsConfig:

paradocTools({
  defaultRegistryUrl: "https://public.paradoc.dev",
  fetch: customFetchWithAuth,
  approvedOrigins: ["https://public.paradoc.dev"],
  maxOutputBytes: 200_000,
})

approvedOrigins matches complete origins, including scheme and port. allowLocalDevelopment permits loopback and private hosts; plain HTTP remains limited to local hosts.

Every adapter combines the framework's abort signal with signal and context.signal, returns the complete result to application code, and bounds the model-facing copy with maxOutputBytes.