ai-templating

@sesamecare-oss/ai-templating loads prompts and skills for Typescript services from:

• local files under private/prompts and private/skills
• Langfuse prompts, partials, and skills

It compiles prompts with Handlebars, registers a shared helper set, supports Langfuse production variants, and exposes a small TemplateManager API for service code.

Common Use Case

The normal pattern is:

1. Create a Langfuse client
2. Construct a TemplateManager
3. Load templates during service startup
4. Render prompts by name inside request or workflow code

import path from 'node:path';

import { TemplateManager } from '@sesamecare-oss/ai-templating';

export async function start(app: AgentApp) {
  const templates = new TemplateManager(app, {
    langfuse: app.locals.langfuse,
    rootDir: path.join(process.cwd(), 'private'),
  });

  await templates.loadTemplates();
  app.locals.templates = templates;
}

Later, render a prompt:

const { messages, config, metadata } = await app.locals.templates.render(
  'patient/base-prompt',
  {
    patientName: 'Ada Lovelace',
    appointmentDate: '2026-03-21T14:00:00.000Z',
  },
  {
    conversation: priorMessages,
  },
  {
    conversationUuid: '7d1a227d-bf49-4fcb-9db0-04f7c767d0b0',
  },
);

render() returns:

• messages: the final AI SDK ModelMessage[]
• config: model config attached to the prompt when present
• metadata.langfusePrompt: the serialized Langfuse prompt tag for tracing

Requirements

TemplateManager expects a service-style app object whose locals include:

• logger from @openapi-typescript-infra/service

The Langfuse client is passed explicitly in TemplateManagerOptions.langfuse.

Missing templates or skills throw ServiceError with status 400.

Directory Layout

rootDir is the directory that contains prompts/ and skills/.

By default the package looks for:

• <rootDir>/prompts
• <rootDir>/skills

Example:

const templates = new TemplateManager(app, {
  langfuse,
  rootDir: '/srv/service/private',
});

Typical local layout:

private/
  prompts/
    patient/
      base-prompt.yaml
      base-prompt.hbs
    shared/
      header.partial.hbs
  skills/
    patient/
      triage.yaml

Prompt and skill names are derived from paths relative to the configured rootDir:

• private/prompts/patient/base-prompt.yaml -> patient/base-prompt
• private/prompts/shared/header.partial.hbs -> partial shared/header
• private/skills/patient/triage.yaml -> skill patient_triage

Local Prompt Example

private/prompts/patient/base-prompt.yaml

messages:
  - role: system
    content:
      $ref: ./base-prompt.hbs
config:
  model: gpt-4.1
  temperature: 0
  topK: 0
  topP: 1

private/prompts/patient/base-prompt.hbs

{{> shared/header}}

You are helping {{patientName}}.
The appointment is scheduled for {{formatDate appointmentDate}}.

private/prompts/shared/header.partial.hbs

Be direct, accurate, and concise.

Local Skill Example

private/skills/patient/triage.yaml

description: Decide which patient support workflow should be used.
detail: |
  Use this skill when the user is asking to schedule, reschedule, cancel,
  or clarify an appointment-related request.
tools:
  - appointments_search
  - appointments_reschedule

Load skills by name:

const [triageSkill] = app.locals.templates.getSkills(['patient_triage']);

Conditional tool binding

Any tools entry may be an object with a name and optional include / exclude rules instead of a bare string. Rules are @sesamecare-oss/rule-evaluator expressions evaluated against the same context used to render the skill detail (the consumer should always provide the active flow at the top level). This lets one skill be shared by several prompts/flows while exposing different tools to each:

description: Everything about prescriptions at Sesame.
tools:
  - request_location
  - name: suggest_providers_for_service
    include: flow == "patient-generic"
  - name: create_support_ticket
    include: flow == "support-agent"
  - name: alert
    exclude: flow == "customer-support"

An entry with an include rule is bound only when the rule is truthy; an entry with an exclude rule is dropped when the rule is truthy (even if another entry included it — exclusion wins). Resolve the binding with:

import { resolveSkillTools } from '@sesamecare-oss/ai-templating';

const tools = resolveSkillTools(skill.tools, { flow: 'patient-generic' });

The context is a RuleContext — { flow: string } & Record<string, unknown>: flow (the active prompt/flow) is required as the shared-skill discriminator; everything else is caller-defined.

Binding Skills to Prompts

A prompt yaml may declare the skills that should be active for conversations using that prompt with a top-level skills list (Langfuse prompts use config.skills). Names may be given in path form (patient/triage) or store form (patient_triage):

skills:
  - patient/triage
messages:
  - role: system
    content:
      $ref: ./base-prompt.hbs

Skill entries support the same include/exclude rules as tool bindings, so one prompt config can gate skills by context:

skills:
  - patient/triage
  - name: patient/refill
    include: flow == "patient-generic"

Resolve them with getPromptSkills, passing the same conversationUuid you pass to render so weighted variants agree. When any entry carries a rule, options.context (a RuleContext) is required — a missing context throws rather than silently resolving rules against nothing:

const skills = await app.locals.templates.getPromptSkills('patient/base-prompt', {
  conversationUuid,
  context: { flow: 'patient-generic', options },
});

Langfuse Conventions

The package treats certain Langfuse prompt names specially.

Standard prompts

Use the prompt name directly, for example:

• patient/base-prompt

Production labels control which Langfuse version is loaded:

• production
• production-canary
• production-whatever

If multiple production labels exist for the same prompt name, they are grouped and selected deterministically per conversationUuid. Variant weights come from config.promptWeight.

Partials

Name partial prompts with either:

• partial:shared/header
• partial/shared/header

These become Handlebars partials named shared/header.

Skills

Name skill prompts with either:

• skill:patient/triage
• skill/patient/triage

For Langfuse skills:

• prompt text becomes detail (kept as a raw Handlebars template; consumers render it with the live conversation context, including flow)
• config.description is required
• config.tools is optional: an array of tool names and/or { name, include?, exclude? } rule entries (see "Conditional tool binding")
• config.composable is optional; true marks the skill as composable

Public API

The main API surface is intentionally small:

new TemplateManager(app, options)

Construct the manager. options supports:

• langfuse
• rootDir

await templates.loadTemplates()

Loads local templates, local skills, Langfuse inventory, partials, and production prompts into memory.

await templates.render(name, data, placeholders?, options?)

Renders a template by name.

Options:

• promptVersion: force a specific Langfuse version
• conversationUuid: stable seed for weighted variant selection

templates.getSkills(names)

Returns skill specs in the requested order.

await templates.getPromptSkills(name, options?)

Returns the skill specs bound to a prompt (top-level skills in a filesystem prompt yaml, config.skills in Langfuse). Accepts the same options as render; pass the same conversationUuid so weighted variants agree.

resolveSkillTools(tools, context)

Resolves a skill's tool binding (tool names and/or rule entries) against a rendering context (RuleContext). The generic form, resolveRuleGatedNames, resolves any RuleGatedName[] — it also powers prompt→skill bindings.

await templates.getAndCacheTemplate(name, version?, label?)

Fetches a Langfuse template directly and stores it in the in-memory cache.

await templates.reloadFromLangfuse(update?)

Refreshes templates, skills, or partials from Langfuse.

• with promptName, it reloads only the affected prompt when possible
• without promptName, it falls back to a full reload

Built-in Helpers

The package registers:

• the helper set from handlebars-helpers
• howLongAgo(date)
• formatDate(date, format?)
• formatCents(cents)
• eq(a, b)

These are available to both filesystem prompts and Langfuse prompts.

Notes

• Node >=22 is required.
• The package is designed for service environments built on @openapi-typescript-infra/service.
• TemplateManager.iterateAllPrompts(langfuse) is exported if you need raw Langfuse prompt inventory iteration.