Alpha Tools

Provider-agnostic tool SDK with a first-class adapter for the Vercel AI SDK. Define tools once, then expose them to AI providers through thin adapters (alpha-tools/ai today; alpha-tools/openai, alpha-tools/google, etc. later).

Features

• Single entrypoint: createTools wraps your tools and returns one AI SDK tool: execute_js.
• Vendor-neutral core: keep using your Tool definitions when you add new providers.
• Implicit returns: last expression is auto-returned (Jupyter-style) to reduce prompt noise.
• Built-in docs: getToolDoc(toolFn) lives in the execution scope for lazy, per-tool help.
• CDP-ready context: Network, Page, Runtime, and client are injected for implementations.

Install

npm install alpha-tools ai

• ai is a peer dependency (you own the version).
• zod ships with this package because AI SDK tools use it at runtime.

Quick start (AI SDK)

import { generateText } from 'ai';
import type { Tool, ToolContext } from 'alpha-tools';
import { createTools } from 'alpha-tools/ai';

const tools: Tool[] = [
  {
    name: 'getWeather',
    description: 'Get the weather in a location',
    parameters: [{ name: 'location', type: 'string', description: 'City', required: true }],
    output: { type: 'object', description: 'Weather info' },
    implementation: async ({ location }, ctx) => {
      // ctx.Network / ctx.Page / ctx.Runtime / ctx.client are available
      return { location, temperature: 72, condition: 'Sunny' };
    },
  },
];

const cdpContext: ToolContext = { Network, Page, Runtime, client };
const aiTools = createTools(tools, cdpContext); // -> { execute_js }

const result = await generateText({
  model: 'openai/gpt-4o',
  prompt: 'Weather in SF?',
  tools: aiTools,
});

Using existing AI SDK tools

If you already have native AI SDK tools, you can bring them in unchanged:

import { tool } from 'ai';
import { createTools } from 'alpha-tools/ai';

const nativeTools = {
  ping: tool({
    description: 'Ping the server',
    inputSchema: z.object({}),
    async execute() {
      return 'pong';
    },
  }),
};

const aiTools = createTools(nativeTools); // context optional when using native tools

API

createTools(tools: Tool[], context: ToolContext): Record<string, any>;
createTools(tools: Record<string, any>, context?: ToolContext): Record<string, any>;
createTools({ tools, context }: { tools: Tool[] | Record<string, any>; context?: ToolContext }): Record<string, any>;

• Always returns { execute_js } in AI SDK format.
• Tool[] path requires a CDP-style ToolContext so your implementations can call Network/Page/Runtime/client.
• Native AI SDK tools skip context; they are wrapped and injected for JS execution.

Tool shape (vendor-neutral)

type Tool = {
  name: string;
  description: string;
  parameters: ToolParameter[];
  output: ToolOutput;
  implementation: (params: Record<string, any>, context: ToolContext) => Promise<any>;
};

See types.ts for the complete schema.

Package structure

• types.ts — Core type definitions (Tool, ToolParameter, ToolOutput, ToolContext, etc.)
• builder.ts — ToolEnvironmentBuilder injects tools + CDP domains; exposes execute(code)
• documentation.ts — generateDocumentation and generateToolList for prompt-time docs
• ai-sdk/adapter.ts — toAISDKTool, toAISDKTools, and the user-facing createTools
• Subpath exports:
  • alpha-tools — generic SDK
  • alpha-tools/ai — Vercel AI SDK adapter

Adding other providers

Follow the AI SDK adapter pattern:

1. Create a folder for the provider (e.g., openai/adapter.ts or anthropic/adapter.ts).
2. Import the generic Tool / ToolEnvironmentBuilder.
3. Map between the provider’s tool format and the generic SDK, or wrap execute_js into the provider’s tool contract.

The core SDK (types.ts, builder.ts, documentation.ts, index.ts) stays stable and provider-neutral.

Development

npm run build   # compile to dist/ with types
npm run clean   # remove dist/

npm pack/publish uses prepare to build automatically. README.md is what GitHub and npm will display.