@anythingai/teleprompt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Create Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# teleprompt
+
+Compose LLM system prompts from discrete sections instead of monolithic template literals.
+
+Conditional logic, variants, and prompt changes stay co-located with their content. Adding a new flag is one section in one file, not a boolean threaded through 15 function signatures.
+
+```bash
+pnpm add @anythingai/teleprompt
+```
+
+## Quick Start
+
+```ts
+import { PromptBuilder, type PromptContext, type PromptSection } from '@anythingai/teleprompt';
+
+// Define your context shape
+type MyFlags = { webSearchEnabled: boolean };
+type MyVars = { assistantName: string };
+type MyContext = PromptContext<MyFlags, MyVars>;
+
+// Sections are objects with an id and a render function
+const identity: PromptSection<MyContext> = {
+  id: 'identity',
+  render: (ctx) => `You are ${ctx.vars.assistantName}, a helpful AI assistant.`,
+};
+
+// This is a static section with no context dependencies
+const guidelines: PromptSection<MyContext> = {
+  id: 'guidelines',
+  render: () => `# Guidelines
+- Be concise and direct.
+- Cite sources when making factual claims.
+- Ask for clarification when a request is ambiguous.`,
+};
+
+// Conditional logic lives in the section, not threaded through function signatures
+const webSearch: PromptSection<MyContext> = {
+  id: 'web-search',
+  when: (ctx) => ctx.flags.webSearchEnabled,
+  render: () => `You have access to web search. Use it when the user asks about
+current events or information that may have changed after your training cutoff.`,
+};
+
+// Compose and build
+const prompt = new PromptBuilder<MyContext>()
+  .use(identity)
+  .use(guidelines)
+  .use(webSearch)
+  .build({
+    flags: { webSearchEnabled: true },
+    vars: { assistantName: 'Daniel' },
+  });
+```
+
+## Sections
+
+A section has an `id`, a `render` function, and optionally a `when` guard:
+
+```ts
+const citation: PromptSection<MyContext> = {
+  id: 'citation',
+  when: (ctx) => ctx.flags.citationEnabled,   // excluded when false
+  render: () => 'Always include citations with links when referencing external sources.',
+};
+```
+
+Sections render in the order you call `.use()`. To reorder, change the call order.
+
+## Forking
+
+Create variants without duplicating prompt code:
+
+```ts
+const base = new PromptBuilder<MyContext>()
+  .use(identity)
+  .use(guidelines)
+  .use(tone);
+
+// Customer support agent — adds escalation rules
+const supportAgent = base.fork()
+  .use(escalationPolicy)
+  .use(ticketFormat);
+
+// Code assistant — swaps guidelines, drops tone
+const codeAssistant = base.fork()
+  .without(guidelines)
+  .without(tone)
+  .use(codingGuidelines)
+  .use(outputFormat);
+```
+
+Each fork is independent. Modifying one doesn't affect the others.
+
+## Context
+
+Sections receive a typed context with boolean flags and arbitrary variables:
+
+```ts
+type MyFlags = {
+  webSearchEnabled: boolean;
+  citationEnabled: boolean;
+};
+
+type MyVars = {
+  assistantName: string;
+  language: string;
+};
+
+type MyContext = PromptContext<MyFlags, MyVars>;
+```
+
+You build the context once and pass it to `.build(ctx)`. Every section receives the same object — no threading booleans through function signatures.
+
+## Builder API
+
+```ts
+new PromptBuilder<MyContext>()
+  // append a section (replaces if same id exists)
+  .use(section)
+
+  // remove by section object or string id
+  .without(section)
+
+  // check existence by section object or string id
+  .has(section)
+
+  // list all section ids
+  .ids()
+
+  // independent copy
+  .fork()
+
+  // render to string
+  .build(ctx)
+
+  // render + debug info: { included: string[], excluded: string[] }
+  .buildWithMeta(ctx)        
+```
+
+## Testing
+
+```ts
+import { mockContext, renderSection } from '@anythingai/teleprompt/testing';
+
+// Render a section in isolation
+const output = renderSection(webSearch, { flags: { webSearchEnabled: true } });
+expect(output).toContain('web search');
+
+// Assert on prompt structure
+const { included, excluded } = builder.buildWithMeta(ctx);
+expect(included).toContain('web-search');
+expect(excluded).toContain('citation');
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,95 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); var _class;// src/builder.ts
+var PromptBuilder = (_class = class _PromptBuilder {constructor() { _class.prototype.__init.call(this); }
+  __init() {this.sections = []}
+  /**
+   * Add a section to the prompt.
+   *
+   * If a section with the same `id` already exists, it is replaced.
+   * This makes `.use()` idempotent — you can safely call it multiple
+   * times with the same section without creating duplicates.
+   */
+  use(section) {
+    const existingIdx = this.sections.findIndex((s) => s.id === section.id);
+    if (existingIdx >= 0) {
+      this.sections[existingIdx] = section;
+    } else {
+      this.sections.push(section);
+    }
+    return this;
+  }
+  /** Remove a section. Accepts an id string or a section object. */
+  without(ref) {
+    const id = typeof ref === "string" ? ref : ref.id;
+    this.sections = this.sections.filter((s) => s.id !== id);
+    return this;
+  }
+  /** Check if a section exists. Accepts an id string or a section object. */
+  has(ref) {
+    const id = typeof ref === "string" ? ref : ref.id;
+    return this.sections.some((s) => s.id === id);
+  }
+  /** Get the ids of all registered sections (in insertion order). */
+  ids() {
+    return this.sections.map((s) => s.id);
+  }
+  /**
+   * Create an independent copy of this builder.
+   *
+   * Use this to create mode-specific or model-specific variants
+   * without mutating the base builder.
+   *
+   * @example
+   * ```ts
+   * const base = new PromptBuilder().use(a).use(b);
+   * const variant = base.fork().use(c); // base is unchanged
+   * ```
+   */
+  fork() {
+    const forked = new _PromptBuilder();
+    forked.sections = [...this.sections];
+    return forked;
+  }
+  /**
+   * Build the final prompt string.
+   *
+   * 1. Filters out sections whose `when` guard returns false
+   * 2. Renders each section
+   * 3. Filters out empty strings
+   * 4. Joins with separator and trims
+   */
+  build(ctx) {
+    return this.buildWithMeta(ctx).prompt;
+  }
+  /**
+   * Build the prompt and return metadata about which sections were
+   * included/excluded. Useful for debugging and logging.
+   *
+   * A section is "excluded" if its `when` guard returns false.
+   * A section is "included" only if it passes the guard and renders
+   * a non-empty string.
+   */
+  buildWithMeta(ctx) {
+    const included = [];
+    const excluded = [];
+    const rendered = this.sections.filter((s) => {
+      if (s.when && !s.when(ctx)) {
+        excluded.push(s.id);
+        return false;
+      }
+      return true;
+    }).map((s) => {
+      const output = s.render(ctx);
+      if (output) {
+        included.push(s.id);
+      } else {
+        excluded.push(s.id);
+      }
+      return output;
+    }).filter(Boolean).join("\n\n").trim();
+    return { prompt: rendered, included, excluded };
+  }
+}, _class);
+
+
+exports.PromptBuilder = PromptBuilder;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/asurve/dev/teleprompt/dist/index.cjs","../src/builder.ts"],"names":[],"mappings":"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","file":"/Users/asurve/dev/teleprompt/dist/index.cjs","sourcesContent":[null,"import type { PromptContext, PromptSection } from './types';\n\n/**\n * Declarative, composable prompt builder.\n *\n * Prompts are composed from discrete {@link PromptSection}s that are\n * independently testable pure functions. The builder handles ordering,\n * conditional inclusion, and final assembly.\n *\n * @example\n * ```ts\n * const prompt = new PromptBuilder()\n *   .use(identitySection)\n *   .use(rulesSection)\n *   .use(featureSection)\n *   .build(ctx);\n * ```\n */\nexport class PromptBuilder<\n  TCtx extends PromptContext<Record<string, boolean>, Record<string, unknown>>,\n> {\n  private sections: PromptSection<TCtx>[] = [];\n\n  /**\n   * Add a section to the prompt.\n   *\n   * If a section with the same `id` already exists, it is replaced.\n   * This makes `.use()` idempotent — you can safely call it multiple\n   * times with the same section without creating duplicates.\n   */\n  use(section: PromptSection<TCtx>): this {\n    const existingIdx = this.sections.findIndex((s) => s.id === section.id);\n    if (existingIdx >= 0) {\n      this.sections[existingIdx] = section;\n    } else {\n      this.sections.push(section);\n    }\n    return this;\n  }\n\n  /** Remove a section. Accepts an id string or a section object. */\n  without(ref: string | { id: string }): this {\n    const id = typeof ref === 'string' ? ref : ref.id;\n    this.sections = this.sections.filter((s) => s.id !== id);\n    return this;\n  }\n\n  /** Check if a section exists. Accepts an id string or a section object. */\n  has(ref: string | { id: string }): boolean {\n    const id = typeof ref === 'string' ? ref : ref.id;\n    return this.sections.some((s) => s.id === id);\n  }\n\n  /** Get the ids of all registered sections (in insertion order). */\n  ids(): string[] {\n    return this.sections.map((s) => s.id);\n  }\n\n  /**\n   * Create an independent copy of this builder.\n   *\n   * Use this to create mode-specific or model-specific variants\n   * without mutating the base builder.\n   *\n   * @example\n   * ```ts\n   * const base = new PromptBuilder().use(a).use(b);\n   * const variant = base.fork().use(c); // base is unchanged\n   * ```\n   */\n  fork(): PromptBuilder<TCtx> {\n    const forked = new PromptBuilder<TCtx>();\n    forked.sections = [...this.sections];\n    return forked;\n  }\n\n  /**\n   * Build the final prompt string.\n   *\n   * 1. Filters out sections whose `when` guard returns false\n   * 2. Renders each section\n   * 3. Filters out empty strings\n   * 4. Joins with separator and trims\n   */\n  build(ctx: TCtx): string {\n    return this.buildWithMeta(ctx).prompt;\n  }\n\n  /**\n   * Build the prompt and return metadata about which sections were\n   * included/excluded. Useful for debugging and logging.\n   *\n   * A section is \"excluded\" if its `when` guard returns false.\n   * A section is \"included\" only if it passes the guard and renders\n   * a non-empty string.\n   */\n  buildWithMeta(ctx: TCtx): {\n    prompt: string;\n    included: string[];\n    excluded: string[];\n  } {\n    const included: string[] = [];\n    const excluded: string[] = [];\n\n    const rendered = this.sections\n      .filter((s) => {\n        if (s.when && !s.when(ctx)) {\n          excluded.push(s.id);\n          return false;\n        }\n        return true;\n      })\n      .map((s) => {\n        const output = s.render(ctx);\n        if (output) {\n          included.push(s.id);\n        } else {\n          excluded.push(s.id);\n        }\n        return output;\n      })\n      .filter(Boolean)\n      .join('\\n\\n')\n      .trim();\n\n    return { prompt: rendered, included, excluded };\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,76 @@
+import { P as PromptContext, a as PromptSection } from './types-DXgCksVT.cjs';
+
+/**
+ * Declarative, composable prompt builder.
+ *
+ * Prompts are composed from discrete {@link PromptSection}s that are
+ * independently testable pure functions. The builder handles ordering,
+ * conditional inclusion, and final assembly.
+ *
+ * @example
+ * ```ts
+ * const prompt = new PromptBuilder()
+ *   .use(identitySection)
+ *   .use(rulesSection)
+ *   .use(featureSection)
+ *   .build(ctx);
+ * ```
+ */
+declare class PromptBuilder<TCtx extends PromptContext<Record<string, boolean>, Record<string, unknown>>> {
+    private sections;
+    /**
+     * Add a section to the prompt.
+     *
+     * If a section with the same `id` already exists, it is replaced.
+     * This makes `.use()` idempotent — you can safely call it multiple
+     * times with the same section without creating duplicates.
+     */
+    use(section: PromptSection<TCtx>): this;
+    /** Remove a section. Accepts an id string or a section object. */
+    without(ref: string | {
+        id: string;
+    }): this;
+    /** Check if a section exists. Accepts an id string or a section object. */
+    has(ref: string | {
+        id: string;
+    }): boolean;
+    /** Get the ids of all registered sections (in insertion order). */
+    ids(): string[];
+    /**
+     * Create an independent copy of this builder.
+     *
+     * Use this to create mode-specific or model-specific variants
+     * without mutating the base builder.
+     *
+     * @example
+     * ```ts
+     * const base = new PromptBuilder().use(a).use(b);
+     * const variant = base.fork().use(c); // base is unchanged
+     * ```
+     */
+    fork(): PromptBuilder<TCtx>;
+    /**
+     * Build the final prompt string.
+     *
+     * 1. Filters out sections whose `when` guard returns false
+     * 2. Renders each section
+     * 3. Filters out empty strings
+     * 4. Joins with separator and trims
+     */
+    build(ctx: TCtx): string;
+    /**
+     * Build the prompt and return metadata about which sections were
+     * included/excluded. Useful for debugging and logging.
+     *
+     * A section is "excluded" if its `when` guard returns false.
+     * A section is "included" only if it passes the guard and renders
+     * a non-empty string.
+     */
+    buildWithMeta(ctx: TCtx): {
+        prompt: string;
+        included: string[];
+        excluded: string[];
+    };
+}
+
+export { PromptBuilder, PromptContext, PromptSection };

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+import { P as PromptContext, a as PromptSection } from './types-DXgCksVT.js';
+
+/**
+ * Declarative, composable prompt builder.
+ *
+ * Prompts are composed from discrete {@link PromptSection}s that are
+ * independently testable pure functions. The builder handles ordering,
+ * conditional inclusion, and final assembly.
+ *
+ * @example
+ * ```ts
+ * const prompt = new PromptBuilder()
+ *   .use(identitySection)
+ *   .use(rulesSection)
+ *   .use(featureSection)
+ *   .build(ctx);
+ * ```
+ */
+declare class PromptBuilder<TCtx extends PromptContext<Record<string, boolean>, Record<string, unknown>>> {
+    private sections;
+    /**
+     * Add a section to the prompt.
+     *
+     * If a section with the same `id` already exists, it is replaced.
+     * This makes `.use()` idempotent — you can safely call it multiple
+     * times with the same section without creating duplicates.
+     */
+    use(section: PromptSection<TCtx>): this;
+    /** Remove a section. Accepts an id string or a section object. */
+    without(ref: string | {
+        id: string;
+    }): this;
+    /** Check if a section exists. Accepts an id string or a section object. */
+    has(ref: string | {
+        id: string;
+    }): boolean;
+    /** Get the ids of all registered sections (in insertion order). */
+    ids(): string[];
+    /**
+     * Create an independent copy of this builder.
+     *
+     * Use this to create mode-specific or model-specific variants
+     * without mutating the base builder.
+     *
+     * @example
+     * ```ts
+     * const base = new PromptBuilder().use(a).use(b);
+     * const variant = base.fork().use(c); // base is unchanged
+     * ```
+     */
+    fork(): PromptBuilder<TCtx>;
+    /**
+     * Build the final prompt string.
+     *
+     * 1. Filters out sections whose `when` guard returns false
+     * 2. Renders each section
+     * 3. Filters out empty strings
+     * 4. Joins with separator and trims
+     */
+    build(ctx: TCtx): string;
+    /**
+     * Build the prompt and return metadata about which sections were
+     * included/excluded. Useful for debugging and logging.
+     *
+     * A section is "excluded" if its `when` guard returns false.
+     * A section is "included" only if it passes the guard and renders
+     * a non-empty string.
+     */
+    buildWithMeta(ctx: TCtx): {
+        prompt: string;
+        included: string[];
+        excluded: string[];
+    };
+}
+
+export { PromptBuilder, PromptContext, PromptSection };

package/dist/index.js

@@ -0,0 +1,95 @@
+// src/builder.ts
+var PromptBuilder = class _PromptBuilder {
+  sections = [];
+  /**
+   * Add a section to the prompt.
+   *
+   * If a section with the same `id` already exists, it is replaced.
+   * This makes `.use()` idempotent — you can safely call it multiple
+   * times with the same section without creating duplicates.
+   */
+  use(section) {
+    const existingIdx = this.sections.findIndex((s) => s.id === section.id);
+    if (existingIdx >= 0) {
+      this.sections[existingIdx] = section;
+    } else {
+      this.sections.push(section);
+    }
+    return this;
+  }
+  /** Remove a section. Accepts an id string or a section object. */
+  without(ref) {
+    const id = typeof ref === "string" ? ref : ref.id;
+    this.sections = this.sections.filter((s) => s.id !== id);
+    return this;
+  }
+  /** Check if a section exists. Accepts an id string or a section object. */
+  has(ref) {
+    const id = typeof ref === "string" ? ref : ref.id;
+    return this.sections.some((s) => s.id === id);
+  }
+  /** Get the ids of all registered sections (in insertion order). */
+  ids() {
+    return this.sections.map((s) => s.id);
+  }
+  /**
+   * Create an independent copy of this builder.
+   *
+   * Use this to create mode-specific or model-specific variants
+   * without mutating the base builder.
+   *
+   * @example
+   * ```ts
+   * const base = new PromptBuilder().use(a).use(b);
+   * const variant = base.fork().use(c); // base is unchanged
+   * ```
+   */
+  fork() {
+    const forked = new _PromptBuilder();
+    forked.sections = [...this.sections];
+    return forked;
+  }
+  /**
+   * Build the final prompt string.
+   *
+   * 1. Filters out sections whose `when` guard returns false
+   * 2. Renders each section
+   * 3. Filters out empty strings
+   * 4. Joins with separator and trims
+   */
+  build(ctx) {
+    return this.buildWithMeta(ctx).prompt;
+  }
+  /**
+   * Build the prompt and return metadata about which sections were
+   * included/excluded. Useful for debugging and logging.
+   *
+   * A section is "excluded" if its `when` guard returns false.
+   * A section is "included" only if it passes the guard and renders
+   * a non-empty string.
+   */
+  buildWithMeta(ctx) {
+    const included = [];
+    const excluded = [];
+    const rendered = this.sections.filter((s) => {
+      if (s.when && !s.when(ctx)) {
+        excluded.push(s.id);
+        return false;
+      }
+      return true;
+    }).map((s) => {
+      const output = s.render(ctx);
+      if (output) {
+        included.push(s.id);
+      } else {
+        excluded.push(s.id);
+      }
+      return output;
+    }).filter(Boolean).join("\n\n").trim();
+    return { prompt: rendered, included, excluded };
+  }
+};
+export {
+  PromptBuilder
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/builder.ts"],"sourcesContent":["import type { PromptContext, PromptSection } from './types';\n\n/**\n * Declarative, composable prompt builder.\n *\n * Prompts are composed from discrete {@link PromptSection}s that are\n * independently testable pure functions. The builder handles ordering,\n * conditional inclusion, and final assembly.\n *\n * @example\n * ```ts\n * const prompt = new PromptBuilder()\n *   .use(identitySection)\n *   .use(rulesSection)\n *   .use(featureSection)\n *   .build(ctx);\n * ```\n */\nexport class PromptBuilder<\n  TCtx extends PromptContext<Record<string, boolean>, Record<string, unknown>>,\n> {\n  private sections: PromptSection<TCtx>[] = [];\n\n  /**\n   * Add a section to the prompt.\n   *\n   * If a section with the same `id` already exists, it is replaced.\n   * This makes `.use()` idempotent — you can safely call it multiple\n   * times with the same section without creating duplicates.\n   */\n  use(section: PromptSection<TCtx>): this {\n    const existingIdx = this.sections.findIndex((s) => s.id === section.id);\n    if (existingIdx >= 0) {\n      this.sections[existingIdx] = section;\n    } else {\n      this.sections.push(section);\n    }\n    return this;\n  }\n\n  /** Remove a section. Accepts an id string or a section object. */\n  without(ref: string | { id: string }): this {\n    const id = typeof ref === 'string' ? ref : ref.id;\n    this.sections = this.sections.filter((s) => s.id !== id);\n    return this;\n  }\n\n  /** Check if a section exists. Accepts an id string or a section object. */\n  has(ref: string | { id: string }): boolean {\n    const id = typeof ref === 'string' ? ref : ref.id;\n    return this.sections.some((s) => s.id === id);\n  }\n\n  /** Get the ids of all registered sections (in insertion order). */\n  ids(): string[] {\n    return this.sections.map((s) => s.id);\n  }\n\n  /**\n   * Create an independent copy of this builder.\n   *\n   * Use this to create mode-specific or model-specific variants\n   * without mutating the base builder.\n   *\n   * @example\n   * ```ts\n   * const base = new PromptBuilder().use(a).use(b);\n   * const variant = base.fork().use(c); // base is unchanged\n   * ```\n   */\n  fork(): PromptBuilder<TCtx> {\n    const forked = new PromptBuilder<TCtx>();\n    forked.sections = [...this.sections];\n    return forked;\n  }\n\n  /**\n   * Build the final prompt string.\n   *\n   * 1. Filters out sections whose `when` guard returns false\n   * 2. Renders each section\n   * 3. Filters out empty strings\n   * 4. Joins with separator and trims\n   */\n  build(ctx: TCtx): string {\n    return this.buildWithMeta(ctx).prompt;\n  }\n\n  /**\n   * Build the prompt and return metadata about which sections were\n   * included/excluded. Useful for debugging and logging.\n   *\n   * A section is \"excluded\" if its `when` guard returns false.\n   * A section is \"included\" only if it passes the guard and renders\n   * a non-empty string.\n   */\n  buildWithMeta(ctx: TCtx): {\n    prompt: string;\n    included: string[];\n    excluded: string[];\n  } {\n    const included: string[] = [];\n    const excluded: string[] = [];\n\n    const rendered = this.sections\n      .filter((s) => {\n        if (s.when && !s.when(ctx)) {\n          excluded.push(s.id);\n          return false;\n        }\n        return true;\n      })\n      .map((s) => {\n        const output = s.render(ctx);\n        if (output) {\n          included.push(s.id);\n        } else {\n          excluded.push(s.id);\n        }\n        return output;\n      })\n      .filter(Boolean)\n      .join('\\n\\n')\n      .trim();\n\n    return { prompt: rendered, included, excluded };\n  }\n}\n"],"mappings":";AAkBO,IAAM,gBAAN,MAAM,eAEX;AAAA,EACQ,WAAkC,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAS3C,IAAI,SAAoC;AACtC,UAAM,cAAc,KAAK,SAAS,UAAU,CAAC,MAAM,EAAE,OAAO,QAAQ,EAAE;AACtE,QAAI,eAAe,GAAG;AACpB,WAAK,SAAS,WAAW,IAAI;AAAA,IAC/B,OAAO;AACL,WAAK,SAAS,KAAK,OAAO;AAAA,IAC5B;AACA,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,QAAQ,KAAoC;AAC1C,UAAM,KAAK,OAAO,QAAQ,WAAW,MAAM,IAAI;AAC/C,SAAK,WAAW,KAAK,SAAS,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE;AACvD,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,IAAI,KAAuC;AACzC,UAAM,KAAK,OAAO,QAAQ,WAAW,MAAM,IAAI;AAC/C,WAAO,KAAK,SAAS,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE;AAAA,EAC9C;AAAA;AAAA,EAGA,MAAgB;AACd,WAAO,KAAK,SAAS,IAAI,CAAC,MAAM,EAAE,EAAE;AAAA,EACtC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,OAA4B;AAC1B,UAAM,SAAS,IAAI,eAAoB;AACvC,WAAO,WAAW,CAAC,GAAG,KAAK,QAAQ;AACnC,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,KAAmB;AACvB,WAAO,KAAK,cAAc,GAAG,EAAE;AAAA,EACjC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,cAAc,KAIZ;AACA,UAAM,WAAqB,CAAC;AAC5B,UAAM,WAAqB,CAAC;AAE5B,UAAM,WAAW,KAAK,SACnB,OAAO,CAAC,MAAM;AACb,UAAI,EAAE,QAAQ,CAAC,EAAE,KAAK,GAAG,GAAG;AAC1B,iBAAS,KAAK,EAAE,EAAE;AAClB,eAAO;AAAA,MACT;AACA,aAAO;AAAA,IACT,CAAC,EACA,IAAI,CAAC,MAAM;AACV,YAAM,SAAS,EAAE,OAAO,GAAG;AAC3B,UAAI,QAAQ;AACV,iBAAS,KAAK,EAAE,EAAE;AAAA,MACpB,OAAO;AACL,iBAAS,KAAK,EAAE,EAAE;AAAA,MACpB;AACA,aAAO;AAAA,IACT,CAAC,EACA,OAAO,OAAO,EACd,KAAK,MAAM,EACX,KAAK;AAER,WAAO,EAAE,QAAQ,UAAU,UAAU,SAAS;AAAA,EAChD;AACF;","names":[]}

package/dist/testing.cjs

@@ -0,0 +1,20 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/testing.ts
+function mockContext(overrides) {
+  return {
+    flags: {},
+    vars: {},
+    ...overrides
+  };
+}
+function renderSection(section, contextOverrides) {
+  const ctx = mockContext(contextOverrides);
+  if (section.when && !section.when(ctx)) {
+    return null;
+  }
+  return section.render(ctx);
+}
+
+
+
+exports.mockContext = mockContext; exports.renderSection = renderSection;
+//# sourceMappingURL=testing.cjs.map

package/dist/testing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/asurve/dev/teleprompt/dist/testing.cjs","../src/testing.ts"],"names":[],"mappings":"AAAA;ACYO,SAAS,WAAA,CAGd,SAAA,EAAiF;AACjF,EAAA,OAAO;AAAA,IACL,KAAA,EAAO,CAAC,CAAA;AAAA,IACR,IAAA,EAAM,CAAC,CAAA;AAAA,IACP,GAAG;AAAA,EACL,CAAA;AACF;AAYO,SAAS,aAAA,CAEd,OAAA,EAA8B,gBAAA,EAAiD;AAC/E,EAAA,MAAM,IAAA,EAAM,WAAA,CAAY,gBAAgB,CAAA;AACxC,EAAA,GAAA,CAAI,OAAA,CAAQ,KAAA,GAAQ,CAAC,OAAA,CAAQ,IAAA,CAAK,GAAG,CAAA,EAAG;AACtC,IAAA,OAAO,IAAA;AAAA,EACT;AACA,EAAA,OAAO,OAAA,CAAQ,MAAA,CAAO,GAAG,CAAA;AAC3B;AD1BA;AACE;AACA;AACF,yEAAC","file":"/Users/asurve/dev/teleprompt/dist/testing.cjs","sourcesContent":[null,"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"]}

package/dist/testing.d.cts

@@ -0,0 +1,26 @@
+import { P as PromptContext, a as PromptSection } from './types-DXgCksVT.cjs';
+
+/**
+ * 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;
+
+export { mockContext, renderSection };

package/dist/testing.d.ts

@@ -0,0 +1,26 @@
+import { P as PromptContext, a as PromptSection } from './types-DXgCksVT.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;
+
+export { mockContext, renderSection };

package/dist/testing.js

@@ -0,0 +1,20 @@
+// src/testing.ts
+function mockContext(overrides) {
+  return {
+    flags: {},
+    vars: {},
+    ...overrides
+  };
+}
+function renderSection(section, contextOverrides) {
+  const ctx = mockContext(contextOverrides);
+  if (section.when && !section.when(ctx)) {
+    return null;
+  }
+  return section.render(ctx);
+}
+export {
+  mockContext,
+  renderSection
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +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":[]}

package/dist/types-DXgCksVT.d.cts

@@ -0,0 +1,34 @@
+/**
+ * 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>, TVars extends 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<Record<string, boolean>, Record<string, unknown>>> {
+    /** 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-DXgCksVT.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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>, TVars extends 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<Record<string, boolean>, Record<string, unknown>>> {
+    /** 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/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@anythingai/teleprompt",
+  "version": "0.1.0",
+  "description": "Composable, declarative prompt builder for LLM system prompts",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./testing": {
+      "import": {
+        "types": "./dist/testing.d.ts",
+        "default": "./dist/testing.js"
+      },
+      "require": {
+        "types": "./dist/testing.d.cts",
+        "default": "./dist/testing.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "prompt",
+    "llm",
+    "ai",
+    "system-prompt",
+    "prompt-builder",
+    "prompt-composition",
+    "composable"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Create-Inc/teleprompt.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.17.0",
+    "@biomejs/biome": "^1.9.0",
+    "publint": "^0.3.0",
+    "tsup": "^8.4.0",
+    "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"
+  }
+}