npm package: @inconvoai/node-ai-sdk
Description: Backend tool helpers for connecting Inconvo to the Vercel AI SDK
Latest version: 1.4.0

# @inconvoai/node-ai-sdk

Reusable backend tools that connect the [Inconvo Node client](https://www.npmjs.com/package/@inconvoai/node) to the [Vercel AI SDK](https://sdk.vercel.ai/docs). 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

```bash
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

```ts
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):

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

## Development

```bash
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](https://www.conventionalcommits.org/) 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`.