@x12i/assistant-functions

@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):

.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

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:

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

API

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

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

npm run build
npm test

Fixture used by tests: fixtures/ai-assistants.