@inconvoai/node-ai-sdk

Reusable backend tools that connect the Inconvo Node client to the Vercel AI SDK. The package exports a single helper, inconvoTools, which returns the three tool definitions commonly used to chat with the Inconvo data analyst from server-side routes.

Installation

npm install @inconvoai/node-ai-sdk @inconvoai/node ai zod

@inconvoai/node and ai are peer dependencies because most apps already have them installed. Make sure the Inconvo client can read its required environment variables (for example INCONVO_API_KEY) in your runtime.

Usage

import { streamText } from "ai";
import { inconvoTools } from "@inconvoai/node-ai-sdk";

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: /* your model */,
    messages,
    tools: {
      ...inconvoTools({
        userContext: () => ({ organisationId: 1 }),
      }),
    },
  });

  return result.toAIStreamResponse();
}

Options

| Option | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | inconvo | Optional custom Inconvo client. Defaults to new Inconvo() which reads its configuration from env vars. | | userContext | A plain object, a promise, or a callback (sync or async) that resolves to the user context passed to inconvo.conversations.create. Use it to to scope the conversation to a specific context. | | messageDescription | Optional override for the message_data_analyst tool description. Defaults to the same text used in assistant-ui-inconvo. | | stringifyResponse | Optional serializer for the analyst replies. Defaults to JSON.stringify (falling back to identity strings). |

Returned tools

• get_data_summary
• start_data_analyst_conversation
• message_data_analyst

You can spread them straight into the tools object accepted by the Vercel AI SDK.

If your context never changes, you can provide it directly (or as a promise):

const tools = inconvoTools({
  userContext: Promise.resolve({ organisationId: 1 }),
});

Development

npm test
npm run typecheck
npm run build

The build step emits both ESM (dist/index.mjs) and CJS (dist/index.cjs) bundles plus type declarations.

Release Workflow

• Follow Conventional Commits in main so semantic-release can determine the next version.
• After merging the desired changes into main, trigger the Release workflow in GitHub via workflow_dispatch.
• The workflow runs tests, type checks, builds the package, and executes semantic-release, which updates the changelog, tags the commit, and publishes to npm using the repository NPM_TOKEN.