@anythingai/teleprompt 0.2.0 → 0.3.0

package/dist/testing.d.ts

@@ -1,26 +1,7 @@
-import { P as PromptContext, a as PromptSection } from './types--sRnfw6Q.js';
+import { P as PromptContext, a as PromptSection } from './types-ow-XbrO7.js';
 
-/**
- * Create a minimal PromptContext for testing.
- * All fields have sensible defaults that can be overridden.
- *
- * @example
- * ```ts
- * const ctx = mockContext({ flags: { myFlag: true } });
- * const output = mySection.render(ctx);
- * ```
- */
-declare function mockContext<TFlags extends Record<string, boolean> = Record<string, boolean>, TVars extends Record<string, unknown> = Record<string, unknown>>(overrides?: Partial<PromptContext<TFlags, TVars>>): PromptContext<TFlags, TVars>;
-/**
- * Render a single section in isolation with a mock context.
- * Respects the section's `when` guard — returns `null` if excluded.
- *
- * @example
- * ```ts
- * const output = renderSection(mySection, { flags: { enabled: true } });
- * expect(output).toContain('expected text');
- * ```
- */
-declare function renderSection<TCtx extends PromptContext<Record<string, boolean>, Record<string, unknown>>>(section: PromptSection<TCtx>, contextOverrides?: Partial<TCtx>): string | null;
+declare function mockContext<TFlags extends Record<string, boolean> = Record<string, boolean>, TVars extends object = Record<string, unknown>>(overrides?: Partial<PromptContext<TFlags, TVars>>): PromptContext<TFlags, TVars>;
+/** Renders a section in isolation. Returns `null` if excluded by `when` guard. */
+declare function renderSection<TCtx extends PromptContext>(section: PromptSection<TCtx>, contextOverrides?: Partial<TCtx>): string | null;
 
 export { mockContext, renderSection };

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/testing.ts"],"sourcesContent":["import type { PromptContext, PromptSection } from './types';\n\n/**\n * Create a minimal PromptContext for testing.\n * All fields have sensible defaults that can be overridden.\n *\n * @example\n * ```ts\n * const ctx = mockContext({ flags: { myFlag: true } });\n * const output = mySection.render(ctx);\n * ```\n */\nexport function mockContext<\n  TFlags extends Record<string, boolean> = Record<string, boolean>,\n  TVars extends Record<string, unknown> = Record<string, unknown>,\n>(overrides?: Partial<PromptContext<TFlags, TVars>>): PromptContext<TFlags, TVars> {\n  return {\n    flags: {} as TFlags,\n    vars: {} as TVars,\n    ...overrides,\n  };\n}\n\n/**\n * Render a single section in isolation with a mock context.\n * Respects the section's `when` guard — returns `null` if excluded.\n *\n * @example\n * ```ts\n * const output = renderSection(mySection, { flags: { enabled: true } });\n * expect(output).toContain('expected text');\n * ```\n */\nexport function renderSection<\n  TCtx extends PromptContext<Record<string, boolean>, Record<string, unknown>>,\n>(section: PromptSection<TCtx>, contextOverrides?: Partial<TCtx>): string | null {\n  const ctx = mockContext(contextOverrides) as TCtx;\n  if (section.when && !section.when(ctx)) {\n    return null;\n  }\n  return section.render(ctx);\n}\n"],"mappings":";AAYO,SAAS,YAGd,WAAiF;AACjF,SAAO;AAAA,IACL,OAAO,CAAC;AAAA,IACR,MAAM,CAAC;AAAA,IACP,GAAG;AAAA,EACL;AACF;AAYO,SAAS,cAEd,SAA8B,kBAAiD;AAC/E,QAAM,MAAM,YAAY,gBAAgB;AACxC,MAAI,QAAQ,QAAQ,CAAC,QAAQ,KAAK,GAAG,GAAG;AACtC,WAAO;AAAA,EACT;AACA,SAAO,QAAQ,OAAO,GAAG;AAC3B;","names":[]}
+{"version":3,"sources":["../src/testing.ts"],"sourcesContent":["import type { PromptContext, PromptSection } from './types';\n\nexport function mockContext<\n  TFlags extends Record<string, boolean> = Record<string, boolean>,\n  TVars extends object = Record<string, unknown>,\n>(overrides?: Partial<PromptContext<TFlags, TVars>>): PromptContext<TFlags, TVars> {\n  return {\n    flags: {} as TFlags,\n    vars: {} as TVars,\n    ...overrides,\n  };\n}\n\n/** Renders a section in isolation. Returns `null` if excluded by `when` guard. */\nexport function renderSection<TCtx extends PromptContext>(\n  section: PromptSection<TCtx>,\n  contextOverrides?: Partial<TCtx>,\n): string | null {\n  const ctx = mockContext(contextOverrides) as TCtx;\n  if (section.when && !section.when(ctx)) {\n    return null;\n  }\n  return section.render(ctx);\n}\n"],"mappings":";AAEO,SAAS,YAGd,WAAiF;AACjF,SAAO;AAAA,IACL,OAAO,CAAC;AAAA,IACR,MAAM,CAAC;AAAA,IACP,GAAG;AAAA,EACL;AACF;AAGO,SAAS,cACd,SACA,kBACe;AACf,QAAM,MAAM,YAAY,gBAAgB;AACxC,MAAI,QAAQ,QAAQ,CAAC,QAAQ,KAAK,GAAG,GAAG;AACtC,WAAO;AAAA,EACT;AACA,SAAO,QAAQ,OAAO,GAAG;AAC3B;","names":[]}

package/dist/types-ow-XbrO7.d.cts

@@ -0,0 +1,12 @@
+interface PromptContext<TFlags extends Record<string, boolean> = Record<string, boolean>, TVars extends object = Record<string, unknown>> {
+    flags: TFlags;
+    vars: TVars;
+}
+interface PromptSection<TCtx extends PromptContext = PromptContext> {
+    id: string;
+    /** Return `false` to exclude this section from the output. */
+    when?: (ctx: TCtx) => boolean;
+    render: (ctx: TCtx) => string;
+}
+
+export type { PromptContext as P, PromptSection as a };

package/dist/types-ow-XbrO7.d.ts

@@ -0,0 +1,12 @@
+interface PromptContext<TFlags extends Record<string, boolean> = Record<string, boolean>, TVars extends object = Record<string, unknown>> {
+    flags: TFlags;
+    vars: TVars;
+}
+interface PromptSection<TCtx extends PromptContext = PromptContext> {
+    id: string;
+    /** Return `false` to exclude this section from the output. */
+    when?: (ctx: TCtx) => boolean;
+    render: (ctx: TCtx) => string;
+}
+
+export type { PromptContext as P, PromptSection as a };

package/llms.txt

@@ -0,0 +1,183 @@
+# teleprompt
+
+Composable, section-based LLM system prompts. Published as `@anythingai/teleprompt`.
+
+## Core Concepts
+
+**Section** — a named unit of prompt content with an id and a render function. Return a string to include, `null` to exclude.
+
+**PromptBuilder** — composes sections in order. Supports groups, mutual exclusion, forking, and removal.
+
+**PromptContext** — typed object with `flags` (booleans) and `vars` (arbitrary data) passed to every section's render function.
+
+## Idiomatic Usage
+
+### Define a context type for your application
+
+```ts
+import { type PromptContext } from "@anythingai/teleprompt";
+
+type Flags = { webSearchEnabled: boolean; verbose: boolean };
+type Vars = { userName: string; tasks: Task[] };
+type Ctx = PromptContext<Flags, Vars>;
+```
+
+### Create sections with the `section()` helper
+
+```ts
+import { section } from "@anythingai/teleprompt";
+
+// Static — no context needed, works in any builder
+const guidelines = section("guidelines", () => `Be concise and direct.`);
+
+// Dynamic — reads from context
+const identity = section("identity", (ctx: Ctx) =>
+  `You are ${ctx.vars.userName}'s assistant.`
+);
+
+// Conditional — return null to exclude
+const webSearch = section("web-search", (ctx: Ctx) => {
+  if (!ctx.flags.webSearchEnabled) return null;
+  return "You have access to web search.";
+});
+```
+
+### Compose with PromptBuilder
+
+```ts
+import { PromptBuilder } from "@anythingai/teleprompt";
+
+const builder = new PromptBuilder<Ctx>()
+  .use(identity)
+  .use(guidelines)
+  .use(webSearch)
+  .group("tools", (b) => b.use(bashTool).use(gitTool))
+  .useOneOf(hasTasks, noTasks);
+
+const prompt = builder.build(ctx);
+const xmlPrompt = builder.build(ctx, { format: "xml" });
+```
+
+### Fork for variants
+
+```ts
+const base = new PromptBuilder<Ctx>().use(identity).use(guidelines).use(tone);
+
+const supportAgent = base.fork().use(escalationPolicy);
+const codeAgent = base.fork().without(tone).use(codingRules);
+```
+
+## Patterns and Rationale
+
+### Use null returns for conditional sections, not the `when` guard
+
+The `section()` helper colocates the condition with the content it guards, making sections self-contained and easier to reason about. The `when` field exists on the raw PromptSection interface for programmatic use cases, but `section()` with null returns is the standard path because it keeps each section's logic in one place.
+
+```ts
+// Preferred — condition and content together
+const verbose = section("verbose", (ctx: Ctx) => {
+  if (!ctx.flags.verbose) return null;
+  return "Show detailed explanations.";
+});
+
+// Avoid — splits the condition from the content it controls
+const verbose: PromptSection<Ctx> = {
+  id: "verbose",
+  when: (ctx) => ctx.flags.verbose,
+  render: () => "Show detailed explanations.",
+};
+```
+
+### Keep sections small and focused
+
+Each section should own one concern. This makes sections independently reusable across builder variants (via `fork`, `without`, `use`) and gives `buildWithMeta` meaningful granularity — you can see exactly which capabilities were included or excluded. A monolithic section that concatenates everything defeats both of these.
+
+```ts
+// Preferred — each concern is a composable unit
+const identity = section("identity", (ctx: Ctx) => `You are ${ctx.vars.userName}'s assistant.`);
+const guidelines = section("guidelines", () => "# Guidelines\n- Be concise.");
+const webSearch = section("web-search", (ctx: Ctx) => {
+  if (!ctx.flags.webSearchEnabled) return null;
+  return "You can search the web.";
+});
+```
+
+### Return null rather than empty string for absent content
+
+Returning `null` from `section()` signals intentional exclusion — the section is tracked as "excluded" in `buildWithMeta`, which is useful for debugging and observability. An empty string is ambiguous (is it a bug or intentional?) and still occupies a slot in the output.
+
+```ts
+// Preferred — null signals intentional absence, tracked in metadata
+const tools = section("tools", (ctx: Ctx) => {
+  if (!ctx.flags.webSearchEnabled) return null;
+  return "You can search the web.";
+});
+
+// Avoid — empty string is ambiguous and not tracked as excluded
+const tools = section("tools", (ctx: Ctx) =>
+  ctx.flags.webSearchEnabled ? "You can search the web." : ""
+);
+```
+
+### Let the builder handle composition
+
+The builder manages section ordering, format wrapping (text vs XML), joining, and metadata tracking. Calling `render` directly on sections bypasses all of this — you lose format support, metadata, and the ability to fork or modify the composition.
+
+```ts
+// Preferred — builder handles joining, format, and metadata
+const prompt = new PromptBuilder<Ctx>().use(identity).use(guidelines).build(ctx);
+
+// Avoid — bypasses composition, forking, and metadata tracking
+const prompt = identity.render(ctx) + "\n\n" + guidelines.render(ctx);
+```
+
+## API Reference
+
+### `section(id, render)`
+
+Creates a PromptSection. `render` receives context, returns `string | null`.
+
+### `PromptBuilder<TCtx>`
+
+- `.use(section)` — append or replace by id
+- `.useOneOf(...sections)` — first non-empty render wins
+- `.group(id, configure)` — named group (XML wrapper in xml format, transparent in text)
+- `.without(id | section)` — remove by id, searches recursively
+- `.has(id | section)` — check existence
+- `.ids()` — list all section ids
+- `.fork()` — independent deep copy
+- `.build(ctx)` — render to string (text format)
+- `.build(ctx, { format: "xml" })` — render with XML tags
+- `.buildWithMeta(ctx)` — returns `{ prompt, included, excluded }`
+
+### `PromptContext<TFlags, TVars>`
+
+```ts
+interface PromptContext<
+  TFlags extends Record<string, boolean>,
+  TVars extends object,
+> {
+  flags: TFlags;
+  vars: TVars;
+}
+```
+
+Both type parameters default to open records, so `new PromptBuilder()` works without a type argument for simple cases.
+
+## Testing
+
+```ts
+import { mockContext, renderSection } from "@anythingai/teleprompt/testing";
+
+// Render a single section in isolation
+const output = renderSection(webSearch, { flags: { webSearchEnabled: true } });
+
+// Assert on builder metadata
+const { included, excluded } = builder.buildWithMeta(ctx);
+```
+
+## Output Formats
+
+**text** (default) — sections joined with `\n\n`, groups are transparent.
+
+**xml** — each section wrapped in `<id>...</id>`, groups wrap children in `<id>...</id>`. Recommended for Claude and Gemini which handle XML-structured prompts well.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anythingai/teleprompt",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Composable, declarative prompt builder for LLM system prompts",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -29,19 +29,12 @@
       }
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
-  "scripts": {
-    "build": "tsup",
-    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm publint && pnpm attw",
-    "lint": "biome check .",
-    "lint:fix": "biome check --write .",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "publint": "publint",
-    "attw": "attw --pack . --profile node16",
-    "prepublishOnly": "pnpm check && pnpm build"
-  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "llms.txt"
+  ],
   "keywords": [
     "prompt",
     "llm",
@@ -56,13 +49,9 @@
     "type": "git",
     "url": "https://github.com/Create-Inc/teleprompt.git"
   },
-  "packageManager": "pnpm@10.30.0+sha512.2b5753de015d480eeb88f5b5b61e0051f05b4301808a82ec8b840c9d2adf7748eb352c83f5c1593ca703ff1017295bc3fdd3119abb9686efc96b9fcb18200937",
   "engines": {
     "node": ">=20"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": ["@biomejs/biome", "esbuild"]
-  },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.0",
     "@biomejs/biome": "^1.9.0",
@@ -71,5 +60,16 @@
     "tsx": "^4.21.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm publint && pnpm attw",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "publint": "publint",
+    "attw": "attw --pack . --profile node16"
   }
-}
+}

package/dist/types--sRnfw6Q.d.cts

@@ -1,34 +0,0 @@
-/**
- * The context passed to every section's `when` and `render` functions.
- *
- * @typeParam TFlags - Shape of the boolean flags object
- * @typeParam TVars - Shape of the runtime variables object
- */
-interface PromptContext<TFlags extends Record<string, boolean> = Record<string, boolean>, TVars extends Record<string, unknown> = Record<string, unknown>> {
-    /** Boolean flags that control which sections are included and how they render */
-    flags: TFlags;
-    /** Runtime data sections can read from (model, mode, integrations, etc.) */
-    vars: TVars;
-}
-/**
- * A single composable unit of prompt content.
- *
- * @typeParam TCtx - The prompt context type this section operates on
- */
-interface PromptSection<TCtx extends PromptContext = PromptContext> {
-    /** Unique identifier. Used by `use()`, `without()`, and `buildWithMeta()`. */
-    id: string;
-    /**
-     * Guard function. Return `false` to exclude this section from the output.
-     * If omitted, the section is always included.
-     */
-    when?: (ctx: TCtx) => boolean;
-    /**
-     * Render the section content. Receives the full prompt context.
-     * Return an empty string to include nothing (different from `when: false`
-     * which removes the section entirely including any separator).
-     */
-    render: (ctx: TCtx) => string;
-}
-
-export type { PromptContext as P, PromptSection as a };

package/dist/types--sRnfw6Q.d.ts

@@ -1,34 +0,0 @@
-/**
- * The context passed to every section's `when` and `render` functions.
- *
- * @typeParam TFlags - Shape of the boolean flags object
- * @typeParam TVars - Shape of the runtime variables object
- */
-interface PromptContext<TFlags extends Record<string, boolean> = Record<string, boolean>, TVars extends Record<string, unknown> = Record<string, unknown>> {
-    /** Boolean flags that control which sections are included and how they render */
-    flags: TFlags;
-    /** Runtime data sections can read from (model, mode, integrations, etc.) */
-    vars: TVars;
-}
-/**
- * A single composable unit of prompt content.
- *
- * @typeParam TCtx - The prompt context type this section operates on
- */
-interface PromptSection<TCtx extends PromptContext = PromptContext> {
-    /** Unique identifier. Used by `use()`, `without()`, and `buildWithMeta()`. */
-    id: string;
-    /**
-     * Guard function. Return `false` to exclude this section from the output.
-     * If omitted, the section is always included.
-     */
-    when?: (ctx: TCtx) => boolean;
-    /**
-     * Render the section content. Receives the full prompt context.
-     * Return an empty string to include nothing (different from `when: false`
-     * which removes the section entirely including any separator).
-     */
-    render: (ctx: TCtx) => string;
-}
-
-export type { PromptContext as P, PromptSection as a };