# @x12i/assistant-functions

> Folder-based JSON-returning AI assistants — callable as simple functions with a router and test()

Latest version **1.2.0** (published 2026-07-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install @x12i/assistant-functions
pnpm add @x12i/assistant-functions
yarn add @x12i/assistant-functions
bun add @x12i/assistant-functions
```

Provides the command `assistant-functions`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2026-07-23 |
| First published | 2026-07-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 1 |
| Unpacked size | 65.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |
| Keywords | assistant, ai, json, funcx, x12i |

## Links

- npm: https://www.npmjs.com/package/@x12i/assistant-functions
- npm.io page: https://npm.io/package/@x12i/assistant-functions

## Dependencies (1)

- [@x12i/funcx](https://npm.io/package/@x12i/funcx.md) ^4.10.4

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 1.2.0 (latest) — 2026-07-23
- 1.1.1 — 2026-07-23
- 1.1.0 — 2026-07-23

## README

# `@x12i/assistant-functions`

Folder-based **assistant functions**: load instructions + knowledge from disk (or in-code config), call an LLM via FuncX `askJson`, and return **parsed JSON**.

Consumes (and scaffolds) this layout (default root **`.assistants-functions`**):

```text
.assistants-functions/
  README.md
  create-data/
    .assistant.json          # hidden model/config (preferred)
    instructions.md
    knowledge/
      data-fixtures.md
      hard-rules.md
      knowx.md
  generate-metadata/
    .assistant.json
    instructions.md
    knowledge/
      …
```

Optional root registry: `.assistants.json` (preferred) or `assistants.json`.
Legacy plain `assistant.json` is still read if present; **`.assistant.json` wins** when both exist.

**Root resolution** (CLI and when `rootDir` is omitted):

1. Explicit `--root` / `rootDir` / request body
2. `ASSISTANTS_ROOT` env
3. Existing `.assistants-functions` (default name)
4. Existing legacy `ai-assistants` (still supported)
5. Otherwise default path `.assistants-functions`

## Install

```bash
npm install @x12i/assistant-functions
```

Requires Node ≥ 20 and an OpenRouter / FuncX-compatible LLM key (`OPENROUTER_API_KEY`).

## Config merge

1. Registry defaults (`.assistants.json` / `assistants.json`)
2. Registry entry for that assistant name
3. Per-folder `.assistant.json` / `assistant.json` — **last wins**

`.assistant.json` example:

```json
{
  "description": "Create synthetic data records as JSON",
  "model": "cheap/default",
  "temperature": 0.1,
  "maxTokens": 2048,
  "testPrompt": { "count": 1 }
}
```

## API

```ts
import {
  createAssistantRouter,
  createAssistantFunction,
  stringifyPrompt,
} from "@x12i/assistant-functions";

// Omit rootDir to use .assistants-functions (or ASSISTANTS_ROOT / legacy ai-assistants)
const router = await createAssistantRouter({
  rootDir: "./.assistants-functions",
  config: { defaults: { model: "cheap/default" } }, // optional; file wins on overlap
});

router.list(); // ["create-data", "generate-metadata"]
await router.run("create-data", { count: 2 });
await router.test("create-data"); // boolean

const fn = createAssistantFunction(router, "create-data");
await fn({ count: 2 });
```

`stringifyPrompt(input)`: strings as-is; `null`/`undefined` → `""`; otherwise `JSON.stringify` (never `[object Object]`).

## CLI

```bash
assistant-functions init --name create-data
# default root ./.assistants-functions — writes .assistants.json, README.md, and create-data/ with:
#   instructions.md, knowledge/overview.md (empty), .assistant.json
#   (.assistant.json includes model, temperature, maxTokens, testPrompt: {})

assistant-functions list
assistant-functions run create-data --prompt '{"count":1}'
assistant-functions test create-data

# Explicit root still works (incl. legacy ai-assistants):
assistant-functions list --root ./ai-assistants
```

## Scripts

```bash
npm run build
npm test
```

Fixture used by tests: [`fixtures/ai-assistants`](fixtures/ai-assistants).

---
_Source: https://npm.io/package/@x12i/assistant-functions · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._