@nudge-ai/core 0.0.1-beta.0

package/dist/index.cjs

@@ -0,0 +1,121 @@
+
+//#region src/builder.ts
+function createBuilder(targetState) {
+	const state = targetState ?? [];
+	const builder = {
+		raw: (value) => (state.push({
+			type: "raw",
+			value
+		}), builder),
+		persona: (role) => (state.push({
+			type: "persona",
+			role
+		}), builder),
+		input: (description) => (state.push({
+			type: "input",
+			description
+		}), builder),
+		output: (description) => (state.push({
+			type: "output",
+			description
+		}), builder),
+		context: (information) => (state.push({
+			type: "context",
+			information
+		}), builder),
+		do: (instruction, options) => (state.push({
+			type: "do",
+			instruction,
+			nudge: options?.nudge
+		}), builder),
+		dont: (instruction, options) => (state.push({
+			type: "dont",
+			instruction,
+			nudge: options?.nudge
+		}), builder),
+		constraint: (rule, options) => (state.push({
+			type: "constraint",
+			rule,
+			nudge: options?.nudge
+		}), builder),
+		example: (input, output) => (state.push({
+			type: "example",
+			input,
+			output
+		}), builder),
+		use: (source) => (state.push(...source._state), builder),
+		optional: (name, builderFn) => {
+			const optionalSteps = [];
+			const { builder: innerBuilder } = createBuilder(optionalSteps);
+			builderFn(innerBuilder);
+			state.push({
+				type: "optional",
+				name,
+				steps: optionalSteps
+			});
+			return builder;
+		}
+	};
+	return {
+		builder,
+		state
+	};
+}
+
+//#endregion
+//#region src/steps.ts
+function formatNudge(nudge) {
+	if (!nudge || nudge === 3) return "";
+	return `\nNudge: ${nudge}`;
+}
+function formatStepForAI(step) {
+	switch (step.type) {
+		case "raw": return `[Raw Text] (Include this text verbatim in the system prompt.)\nValue: "${step.value}"`;
+		case "persona": return `[Persona] (Define the identity and role the AI should assume. Frame this as 'You are...' at the start of the system prompt.)\nValue: "${step.role}"`;
+		case "input": return `[Input] (Describe what input the AI will receive from the user. Help the AI understand the context of what it will be working with.)\nValue: "${step.description}"`;
+		case "output": return `[Output] (Specify what the AI should produce as output. Be clear about the expected format and content.)\nValue: "${step.description}"`;
+		case "context": return `[Context] (Background information or context that helps the AI understand the situation. This is not an instruction, just helpful information.)\nValue: "${step.information}"`;
+		case "do": return `[Do] (A positive instruction the AI must follow.)\nValue: "${step.instruction}"${formatNudge(step.nudge)}`;
+		case "dont": return `[Don't] (A negative instruction - something the AI must avoid.)\nValue: "${step.instruction}"${formatNudge(step.nudge)}`;
+		case "constraint": return `[Constraint] (A rule or limitation the AI must respect.)\nValue: "${step.rule}"${formatNudge(step.nudge)}`;
+		case "example": return `[Example] (An input/output example showing the AI how to respond. Use these to demonstrate the expected behavior.)\nInput: "${step.input}"\nExpected output: "${step.output}"`;
+		case "optional": {
+			const innerSteps = step.steps.map(formatStepForAI).join("\n\n");
+			return `[Optional Block Start: "${step.name}"] (The following instructions are OPTIONAL. Wrap the generated content for these in {{#${step.name}}}...{{/${step.name}}} markers so it can be toggled at runtime.)\n\n${innerSteps}\n\n[Optional Block End: "${step.name}"]`;
+		}
+	}
+}
+
+//#endregion
+//#region src/index.ts
+let promptCache = {};
+function registerPrompts(prompts) {
+	promptCache = {
+		...promptCache,
+		...prompts
+	};
+}
+function processTemplate(text, options = {}) {
+	const processOptionals = (str) => str.replace(/\{\{#(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g, (_, name, content) => options[name] ? processOptionals(content) : "");
+	const processVars = (str) => str.replace(/\{\{(?![#\/])(\w+)\}\}/g, (match, name) => {
+		const value = options[name];
+		return typeof value === "string" ? value : match;
+	});
+	return processVars(processOptionals(text)).replace(/\n{3,}/g, "\n\n");
+}
+function prompt(id, promptFunc) {
+	const { builder, state } = createBuilder();
+	promptFunc(builder);
+	return {
+		id,
+		_state: state,
+		toString: ((options) => {
+			return processTemplate(promptCache[id]?.text ?? "", options).trim();
+		})
+	};
+}
+
+//#endregion
+exports.formatStepForAI = formatStepForAI;
+exports.prompt = prompt;
+exports.registerPrompts = registerPrompts;

package/dist/index.d.cts

@@ -0,0 +1,94 @@
+//#region src/steps.d.ts
+type Nudge = 1 | 2 | 3 | 4 | 5;
+type RawStep = {
+  type: "raw";
+  value: string;
+};
+type PersonaStep = {
+  type: "persona";
+  role: string;
+};
+type InputStep = {
+  type: "input";
+  description: string;
+};
+type OutputStep = {
+  type: "output";
+  description: string;
+};
+type ContextStep = {
+  type: "context";
+  information: string;
+};
+type DoStep = {
+  type: "do";
+  instruction: string;
+  nudge?: Nudge;
+};
+type DontStep = {
+  type: "dont";
+  instruction: string;
+  nudge?: Nudge;
+};
+type ConstraintStep = {
+  type: "constraint";
+  rule: string;
+  nudge?: Nudge;
+};
+type ExampleStep = {
+  type: "example";
+  input: string;
+  output: string;
+};
+type OptionalStep = {
+  type: "optional";
+  name: string;
+  steps: PromptStep[];
+};
+type PromptStep = RawStep | PersonaStep | InputStep | OutputStep | ContextStep | DoStep | DontStep | ConstraintStep | ExampleStep | OptionalStep;
+type StepType = PromptStep["type"];
+declare function formatStepForAI(step: PromptStep): string;
+//#endregion
+//#region src/types.d.ts
+type PromptBuilderState = PromptStep[];
+type PromptBuilder<Optionals extends string = never> = {
+  raw: (value: string) => PromptBuilder<Optionals>;
+  persona: (role: string) => PromptBuilder<Optionals>;
+  input: (description: string) => PromptBuilder<Optionals>;
+  output: (description: string) => PromptBuilder<Optionals>;
+  context: (information: string) => PromptBuilder<Optionals>;
+  do: (instruction: string, options?: {
+    nudge?: Nudge;
+  }) => PromptBuilder<Optionals>;
+  dont: (instruction: string, options?: {
+    nudge?: Nudge;
+  }) => PromptBuilder<Optionals>;
+  constraint: (rule: string, options?: {
+    nudge?: Nudge;
+  }) => PromptBuilder<Optionals>;
+  example: (input: string, output: string) => PromptBuilder<Optionals>;
+  use: (source: {
+    _state: PromptBuilderState;
+  }) => PromptBuilder<Optionals>;
+  optional: <Name extends string, Inner extends string = never>(name: Name, builderFn: (p: PromptBuilder) => PromptBuilder<Inner>) => PromptBuilder<Optionals | Name | Inner>;
+};
+interface PromptRegistry {}
+interface PromptVariables {}
+type PromptId = keyof PromptRegistry;
+type ToStringOptions<Optionals extends string, Variables extends string> = [Variables] extends [never] ? [Optionals] extends [never] ? () => string : (options?: Partial<Record<Optionals, boolean>>) => string : [Optionals] extends [never] ? (options: Record<Variables, string>) => string : (options: Record<Variables, string> & Partial<Record<Optionals, boolean>>) => string;
+type Prompt<Id extends string = string, Optionals extends string = never> = {
+  id: Id;
+  _state: PromptBuilderState;
+  toString: ToStringOptions<Optionals, Id extends keyof PromptVariables ? PromptVariables[Id] : never>;
+};
+type GeneratedPrompt = {
+  text: string;
+  hash: string;
+};
+//#endregion
+//#region src/index.d.ts
+declare function registerPrompts(prompts: Record<string, GeneratedPrompt>): void;
+declare function prompt<Id extends string, Optionals extends string = never>(id: Id, promptFunc: (p: PromptBuilder) => PromptBuilder<Optionals>): Prompt<Id, Optionals>;
+//#endregion
+export { type GeneratedPrompt, type Nudge, type Prompt, type PromptBuilder, type PromptBuilderState, type PromptId, type PromptRegistry, type PromptStep, type PromptVariables, type StepType, formatStepForAI, prompt, registerPrompts };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/steps.ts","../src/types.ts","../src/index.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/index.d.mts

@@ -0,0 +1,94 @@
+//#region src/steps.d.ts
+type Nudge = 1 | 2 | 3 | 4 | 5;
+type RawStep = {
+  type: "raw";
+  value: string;
+};
+type PersonaStep = {
+  type: "persona";
+  role: string;
+};
+type InputStep = {
+  type: "input";
+  description: string;
+};
+type OutputStep = {
+  type: "output";
+  description: string;
+};
+type ContextStep = {
+  type: "context";
+  information: string;
+};
+type DoStep = {
+  type: "do";
+  instruction: string;
+  nudge?: Nudge;
+};
+type DontStep = {
+  type: "dont";
+  instruction: string;
+  nudge?: Nudge;
+};
+type ConstraintStep = {
+  type: "constraint";
+  rule: string;
+  nudge?: Nudge;
+};
+type ExampleStep = {
+  type: "example";
+  input: string;
+  output: string;
+};
+type OptionalStep = {
+  type: "optional";
+  name: string;
+  steps: PromptStep[];
+};
+type PromptStep = RawStep | PersonaStep | InputStep | OutputStep | ContextStep | DoStep | DontStep | ConstraintStep | ExampleStep | OptionalStep;
+type StepType = PromptStep["type"];
+declare function formatStepForAI(step: PromptStep): string;
+//#endregion
+//#region src/types.d.ts
+type PromptBuilderState = PromptStep[];
+type PromptBuilder<Optionals extends string = never> = {
+  raw: (value: string) => PromptBuilder<Optionals>;
+  persona: (role: string) => PromptBuilder<Optionals>;
+  input: (description: string) => PromptBuilder<Optionals>;
+  output: (description: string) => PromptBuilder<Optionals>;
+  context: (information: string) => PromptBuilder<Optionals>;
+  do: (instruction: string, options?: {
+    nudge?: Nudge;
+  }) => PromptBuilder<Optionals>;
+  dont: (instruction: string, options?: {
+    nudge?: Nudge;
+  }) => PromptBuilder<Optionals>;
+  constraint: (rule: string, options?: {
+    nudge?: Nudge;
+  }) => PromptBuilder<Optionals>;
+  example: (input: string, output: string) => PromptBuilder<Optionals>;
+  use: (source: {
+    _state: PromptBuilderState;
+  }) => PromptBuilder<Optionals>;
+  optional: <Name extends string, Inner extends string = never>(name: Name, builderFn: (p: PromptBuilder) => PromptBuilder<Inner>) => PromptBuilder<Optionals | Name | Inner>;
+};
+interface PromptRegistry {}
+interface PromptVariables {}
+type PromptId = keyof PromptRegistry;
+type ToStringOptions<Optionals extends string, Variables extends string> = [Variables] extends [never] ? [Optionals] extends [never] ? () => string : (options?: Partial<Record<Optionals, boolean>>) => string : [Optionals] extends [never] ? (options: Record<Variables, string>) => string : (options: Record<Variables, string> & Partial<Record<Optionals, boolean>>) => string;
+type Prompt<Id extends string = string, Optionals extends string = never> = {
+  id: Id;
+  _state: PromptBuilderState;
+  toString: ToStringOptions<Optionals, Id extends keyof PromptVariables ? PromptVariables[Id] : never>;
+};
+type GeneratedPrompt = {
+  text: string;
+  hash: string;
+};
+//#endregion
+//#region src/index.d.ts
+declare function registerPrompts(prompts: Record<string, GeneratedPrompt>): void;
+declare function prompt<Id extends string, Optionals extends string = never>(id: Id, promptFunc: (p: PromptBuilder) => PromptBuilder<Optionals>): Prompt<Id, Optionals>;
+//#endregion
+export { type GeneratedPrompt, type Nudge, type Prompt, type PromptBuilder, type PromptBuilderState, type PromptId, type PromptRegistry, type PromptStep, type PromptVariables, type StepType, formatStepForAI, prompt, registerPrompts };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/steps.ts","../src/types.ts","../src/index.ts"],"sourcesContent":[],"mappings":";KACY,KAAA;AAAA,KAGA,OAAA,GAHK;EAGL,IAAA,EAAA,KAAO;EACP,KAAA,EAAA,MAAA;AACZ,CAAA;AACY,KAFA,WAAA,GAEU;EACV,IAAA,EAAA,SAAW;EACX,IAAA,EAAA,MAAM;AAClB,CAAA;AACY,KALA,SAAA,GAKc;EAKd,IAAA,EAAA,OAAA;EACA,WAAA,EAAA,MAAY;AAMxB,CAAA;AACI,KAjBQ,UAAA,GAiBR;EACA,IAAA,EAAA,QAAA;EACA,WAAA,EAAA,MAAA;CACA;AACA,KApBQ,WAAA,GAoBR;EACA,IAAA,EAAA,SAAA;EACA,WAAA,EAAA,MAAA;CACA;AACA,KAvBQ,MAAA,GAuBR;EACA,IAAA,EAAA,IAAA;EAAY,WAAA,EAAA,MAAA;EAEJ,KAAA,CAAA,EA1BoD,KA0B5C;AAQpB,CAAA;KAjCY,QAAA;;;ECNA,KAAA,CAAA,EDMwD,KCNxD;AAEZ,CAAA;AACwC,KDI5B,cAAA,GCJ4B;EAAd,IAAA,EAAA,YAAA;EACiB,IAAA,EAAA,MAAA;EAAd,KAAA,CAAA,EDMnB,KCNmB;CACmB;AAAd,KDOtB,WAAA,GCPsB;EACe,IAAA,EAAA,SAAA;EAAd,KAAA,EAAA,MAAA;EACe,MAAA,EAAA,MAAA;CAAd;AAGZ,KDGZ,YAAA,GCHY;EACH,IAAA,EAAA,UAAA;EAAd,IAAA,EAAA,MAAA;EAGiB,KAAA,EDEf,UCFe,EAAA;CACH;AAAd,KDIK,UAAA,GACR,OCLG,GDMH,WCNG,GDOH,SCPG,GDQH,UCRG,GDSH,WCTG,GDUH,MCVG,GDWH,QCXG,GDYH,cCZG,GDaH,WCbG,GDcH,YCdG;AAGiB,KDaZ,QAAA,GAAW,UCbC,CAAA,MAAA,CAAA;AACH,iBDoBL,eAAA,CCpBK,IAAA,EDoBiB,UCpBjB,CAAA,EAAA,MAAA;;;ADnBT,KCAA,kBAAA,GAAqB,UDAd,EAAA;AACP,KCCA,aDDW,CAAA,kBAAA,MAAA,GAAA,KAAA,CAAA,GAAA;EACX,GAAA,EAAA,CAAA,KAAA,EAAS,MAAA,EAAA,GCCK,aDDL,CCCmB,SDDnB,CAAA;EACT,OAAA,EAAA,CAAA,IAAU,EAAA,MAAA,EAAA,GCCO,aDDP,CCCqB,SDDrB,CAAA;EACV,KAAA,EAAA,CAAA,WAAW,EAAA,MAAA,EAAA,GCCW,aDDX,CCCyB,SDDzB,CAAA;EACX,MAAA,EAAA,CAAM,WAA8C,EAAA,MAAK,EAAA,GCClC,aDDkC,CCCpB,SDDoB,CAAA;EACzD,OAAA,EAAA,CAAA,WAAQ,EAAgD,MAAK,EAAA,GCCrC,aDDqC,CCCvB,SDDuB,CAAA;EAC7D,EAAA,EAAA,CAAA,WAAA,EAAc,MAAA,EAAA,OAMd,CAHF,EAAK;IAEH,KAAA,CAAA,ECFY,KDED;EACX,CAAA,EAAA,GCFL,aDEiB,CCFH,SDKZ,CAAA;EAGG,IAAA,EAAA,CAAA,WAAU,EAAA,MAAA,EAAA,OAElB,CAFkB,EAAA;IAClB,KAAA,CAAA,ECNoB,KDMpB;EACA,CAAA,EAAA,GCNG,aDMH,CCNiB,SDMjB,CAAA;EACA,UAAA,EAAA,CAAA,IAAA,EAAA,MAAA,EAAA,OAEA,CAFA,EAAA;IACA,KAAA,CAAA,ECLoB,KDKpB;EACA,CAAA,EAAA,GCLG,aDKH,CCLiB,SDKjB,CAAA;EACA,OAAA,EAAA,CAAA,KAAA,EAAA,MAAA,EAAA,MAAA,EAAA,MAAA,EAAA,GCL0C,aDK1C,CCLwD,SDKxD,CAAA;EACA,GAAA,EAAA,CAAA,MAAA,EAAA;IACA,MAAA,ECNsB,kBDMtB;EACA,CAAA,EAAA,GCP+C,aDO/C,CCP6D,SDO7D,CAAA;EACA,QAAA,EAAA,CAAA,aAAA,MAAA,EAAA,cAAA,MAAA,GAAA,KAAA,CAAA,CAAA,IAAA,ECNM,IDMN,EAAA,SAAA,EAAA,CAAA,CAAA,ECLe,aDKf,EAAA,GCLiC,aDKjC,CCL+C,KDK/C,CAAA,EAAA,GCJG,aDIH,CCJiB,SDIjB,GCJ6B,IDI7B,GCJoC,KDIpC,CAAA;CAAY;AAEJ,UCFK,cAAA,CDEM,CAQvB;UCTiB,eAAA;KAEL,QAAA,SAAiB;AAhC7B,KAmCK,eAnCO,CAAA,kBAAqB,MAAA,EAAA,kBAAU,MAAA,CAAA,GAAA,CAoCzC,SAlCU,CAC4B,SAAA,CAAA,KAAA,CAAA,GAAA,CAmCnC,SAnCmC,CAAA,SAAA,CAAA,KAAA,CAAA,GAAA,GAAA,GAAA,MAAA,GAAA,CAAA,OAAA,CAAA,EAqCvB,OArCuB,CAqCf,MArCe,CAqCR,SArCQ,EAAA,OAAA,CAAA,CAAA,EAAA,GAAA,MAAA,GAAA,CAsCnC,SAtCmC,CAAA,SAAA,CAAA,KAAA,CAAA,GAAA,CAAA,OAAA,EAuCxB,MAvCwB,CAuCjB,SAvCiB,EAAA,MAAA,CAAA,EAAA,GAAA,MAAA,GAAA,CAAA,OAAA,EAyCvB,MAzCuB,CAyChB,SAzCgB,EAAA,MAAA,CAAA,GA0C9B,OA1C8B,CA0CtB,MA1CsB,CA0Cf,SA1Ce,EAAA,OAAA,CAAA,CAAA,EAAA,GAAA,MAAA;AAAd,KA6Cd,MA7Cc,CAAA,WAAA,MAAA,GAAA,MAAA,EAAA,kBAAA,MAAA,GAAA,KAAA,CAAA,GAAA;EACiB,EAAA,EAgDrC,EAhDqC;EAAd,MAAA,EAiDnB,kBAjDmB;EACmB,QAAA,EAiDpC,eAjDoC,CAkD5C,SAlD4C,EAmD5C,EAnD4C,SAAA,MAmD3B,eAnD2B,GAmDT,eAnDS,CAmDO,EAnDP,CAAA,GAAA,KAAA,CAAA;CAAd;AACe,KAsDrC,eAAA,GAtDqC;EAAd,IAAA,EAAA,MAAA;EACe,IAAA,EAAA,MAAA;CAAd;;;ADPpC,iBEcS,eAAA,CFdU,OAAA,EEce,MFdf,CAAA,MAAA,EEc8B,eFd9B,CAAA,CAAA,EAAA,IAAA;AACnB,iBEqCS,MFrCc,CAAA,WAAA,MAAA,EAAA,kBAAA,MAAA,GAAA,KAAA,CAAA,CAAA,EAAA,EEsCjB,EFtCiB,EAAA,UAAA,EAAA,CAAA,CAAA,EEuCL,aFvCK,EAAA,GEuCa,aFvCb,CEuC2B,SFvC3B,CAAA,CAAA,EEwCpB,MFxCoB,CEwCb,EFxCa,EEwCT,SFxCS,CAAA"}

package/dist/index.mjs

@@ -0,0 +1,119 @@
+//#region src/builder.ts
+function createBuilder(targetState) {
+	const state = targetState ?? [];
+	const builder = {
+		raw: (value) => (state.push({
+			type: "raw",
+			value
+		}), builder),
+		persona: (role) => (state.push({
+			type: "persona",
+			role
+		}), builder),
+		input: (description) => (state.push({
+			type: "input",
+			description
+		}), builder),
+		output: (description) => (state.push({
+			type: "output",
+			description
+		}), builder),
+		context: (information) => (state.push({
+			type: "context",
+			information
+		}), builder),
+		do: (instruction, options) => (state.push({
+			type: "do",
+			instruction,
+			nudge: options?.nudge
+		}), builder),
+		dont: (instruction, options) => (state.push({
+			type: "dont",
+			instruction,
+			nudge: options?.nudge
+		}), builder),
+		constraint: (rule, options) => (state.push({
+			type: "constraint",
+			rule,
+			nudge: options?.nudge
+		}), builder),
+		example: (input, output) => (state.push({
+			type: "example",
+			input,
+			output
+		}), builder),
+		use: (source) => (state.push(...source._state), builder),
+		optional: (name, builderFn) => {
+			const optionalSteps = [];
+			const { builder: innerBuilder } = createBuilder(optionalSteps);
+			builderFn(innerBuilder);
+			state.push({
+				type: "optional",
+				name,
+				steps: optionalSteps
+			});
+			return builder;
+		}
+	};
+	return {
+		builder,
+		state
+	};
+}
+
+//#endregion
+//#region src/steps.ts
+function formatNudge(nudge) {
+	if (!nudge || nudge === 3) return "";
+	return `\nNudge: ${nudge}`;
+}
+function formatStepForAI(step) {
+	switch (step.type) {
+		case "raw": return `[Raw Text] (Include this text verbatim in the system prompt.)\nValue: "${step.value}"`;
+		case "persona": return `[Persona] (Define the identity and role the AI should assume. Frame this as 'You are...' at the start of the system prompt.)\nValue: "${step.role}"`;
+		case "input": return `[Input] (Describe what input the AI will receive from the user. Help the AI understand the context of what it will be working with.)\nValue: "${step.description}"`;
+		case "output": return `[Output] (Specify what the AI should produce as output. Be clear about the expected format and content.)\nValue: "${step.description}"`;
+		case "context": return `[Context] (Background information or context that helps the AI understand the situation. This is not an instruction, just helpful information.)\nValue: "${step.information}"`;
+		case "do": return `[Do] (A positive instruction the AI must follow.)\nValue: "${step.instruction}"${formatNudge(step.nudge)}`;
+		case "dont": return `[Don't] (A negative instruction - something the AI must avoid.)\nValue: "${step.instruction}"${formatNudge(step.nudge)}`;
+		case "constraint": return `[Constraint] (A rule or limitation the AI must respect.)\nValue: "${step.rule}"${formatNudge(step.nudge)}`;
+		case "example": return `[Example] (An input/output example showing the AI how to respond. Use these to demonstrate the expected behavior.)\nInput: "${step.input}"\nExpected output: "${step.output}"`;
+		case "optional": {
+			const innerSteps = step.steps.map(formatStepForAI).join("\n\n");
+			return `[Optional Block Start: "${step.name}"] (The following instructions are OPTIONAL. Wrap the generated content for these in {{#${step.name}}}...{{/${step.name}}} markers so it can be toggled at runtime.)\n\n${innerSteps}\n\n[Optional Block End: "${step.name}"]`;
+		}
+	}
+}
+
+//#endregion
+//#region src/index.ts
+let promptCache = {};
+function registerPrompts(prompts) {
+	promptCache = {
+		...promptCache,
+		...prompts
+	};
+}
+function processTemplate(text, options = {}) {
+	const processOptionals = (str) => str.replace(/\{\{#(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g, (_, name, content) => options[name] ? processOptionals(content) : "");
+	const processVars = (str) => str.replace(/\{\{(?![#\/])(\w+)\}\}/g, (match, name) => {
+		const value = options[name];
+		return typeof value === "string" ? value : match;
+	});
+	return processVars(processOptionals(text)).replace(/\n{3,}/g, "\n\n");
+}
+function prompt(id, promptFunc) {
+	const { builder, state } = createBuilder();
+	promptFunc(builder);
+	return {
+		id,
+		_state: state,
+		toString: ((options) => {
+			return processTemplate(promptCache[id]?.text ?? "", options).trim();
+		})
+	};
+}
+
+//#endregion
+export { formatStepForAI, prompt, registerPrompts };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/builder.ts","../src/steps.ts","../src/index.ts"],"sourcesContent":["import type { Nudge } from \"./steps.js\";\nimport type { PromptBuilder, PromptBuilderState } from \"./types.js\";\n\nexport function createBuilder(targetState?: PromptBuilderState): {\n  builder: PromptBuilder;\n  state: PromptBuilderState;\n} {\n  const state: PromptBuilderState = targetState ?? [];\n\n  const builder: PromptBuilder = {\n    raw: (value) => (state.push({ type: \"raw\", value }), builder),\n    persona: (role) => (state.push({ type: \"persona\", role }), builder),\n    input: (description) => (\n      state.push({ type: \"input\", description }),\n      builder\n    ),\n    output: (description) => (\n      state.push({ type: \"output\", description }),\n      builder\n    ),\n    context: (information) => (\n      state.push({ type: \"context\", information }),\n      builder\n    ),\n    do: (instruction, options?: { nudge?: Nudge }) => (\n      state.push({ type: \"do\", instruction, nudge: options?.nudge }),\n      builder\n    ),\n    dont: (instruction, options?: { nudge?: Nudge }) => (\n      state.push({ type: \"dont\", instruction, nudge: options?.nudge }),\n      builder\n    ),\n    constraint: (rule, options?: { nudge?: Nudge }) => (\n      state.push({ type: \"constraint\", rule, nudge: options?.nudge }),\n      builder\n    ),\n    example: (input, output) => (\n      state.push({ type: \"example\", input, output }),\n      builder\n    ),\n    use: (source) => (state.push(...source._state), builder),\n    optional: (name, builderFn) => {\n      const optionalSteps: PromptBuilderState = [];\n      const { builder: innerBuilder } = createBuilder(optionalSteps);\n      builderFn(innerBuilder);\n      state.push({ type: \"optional\", name, steps: optionalSteps });\n      return builder;\n    },\n  };\n\n  return { builder, state };\n}\n","// Nudge levels for instructions (1 = gentlest, 5 = strongest)\nexport type Nudge = 1 | 2 | 3 | 4 | 5;\n\n// Step types\nexport type RawStep = { type: \"raw\"; value: string };\nexport type PersonaStep = { type: \"persona\"; role: string };\nexport type InputStep = { type: \"input\"; description: string };\nexport type OutputStep = { type: \"output\"; description: string };\nexport type ContextStep = { type: \"context\"; information: string };\nexport type DoStep = { type: \"do\"; instruction: string; nudge?: Nudge };\nexport type DontStep = { type: \"dont\"; instruction: string; nudge?: Nudge };\nexport type ConstraintStep = {\n  type: \"constraint\";\n  rule: string;\n  nudge?: Nudge;\n};\nexport type ExampleStep = { type: \"example\"; input: string; output: string };\nexport type OptionalStep = {\n  type: \"optional\";\n  name: string;\n  steps: PromptStep[];\n};\n\nexport type PromptStep =\n  | RawStep\n  | PersonaStep\n  | InputStep\n  | OutputStep\n  | ContextStep\n  | DoStep\n  | DontStep\n  | ConstraintStep\n  | ExampleStep\n  | OptionalStep;\n\nexport type StepType = PromptStep[\"type\"];\n\nfunction formatNudge(nudge?: Nudge): string {\n  if (!nudge || nudge === 3) return \"\";\n  return `\\nNudge: ${nudge}`;\n}\n\n// Format step for AI consumption - each case returns the full formatted output\nexport function formatStepForAI(step: PromptStep): string {\n  switch (step.type) {\n    case \"raw\":\n      return `[Raw Text] (Include this text verbatim in the system prompt.)\\nValue: \"${step.value}\"`;\n    case \"persona\":\n      return `[Persona] (Define the identity and role the AI should assume. Frame this as 'You are...' at the start of the system prompt.)\\nValue: \"${step.role}\"`;\n    case \"input\":\n      return `[Input] (Describe what input the AI will receive from the user. Help the AI understand the context of what it will be working with.)\\nValue: \"${step.description}\"`;\n    case \"output\":\n      return `[Output] (Specify what the AI should produce as output. Be clear about the expected format and content.)\\nValue: \"${step.description}\"`;\n    case \"context\":\n      return `[Context] (Background information or context that helps the AI understand the situation. This is not an instruction, just helpful information.)\\nValue: \"${step.information}\"`;\n    case \"do\":\n      return `[Do] (A positive instruction the AI must follow.)\\nValue: \"${step.instruction}\"${formatNudge(step.nudge)}`;\n    case \"dont\":\n      return `[Don't] (A negative instruction - something the AI must avoid.)\\nValue: \"${step.instruction}\"${formatNudge(step.nudge)}`;\n    case \"constraint\":\n      return `[Constraint] (A rule or limitation the AI must respect.)\\nValue: \"${step.rule}\"${formatNudge(step.nudge)}`;\n    case \"example\":\n      return `[Example] (An input/output example showing the AI how to respond. Use these to demonstrate the expected behavior.)\\nInput: \"${step.input}\"\\nExpected output: \"${step.output}\"`;\n    case \"optional\": {\n      const innerSteps = step.steps.map(formatStepForAI).join(\"\\n\\n\");\n      return `[Optional Block Start: \"${step.name}\"] (The following instructions are OPTIONAL. Wrap the generated content for these in {{#${step.name}}}...{{/${step.name}}} markers so it can be toggled at runtime.)\\n\\n${innerSteps}\\n\\n[Optional Block End: \"${step.name}\"]`;\n    }\n  }\n}\n","import { createBuilder } from \"./builder.js\";\nimport { formatStepForAI } from \"./steps.js\";\nimport type {\n  GeneratedPrompt,\n  Nudge,\n  Prompt,\n  PromptBuilder,\n  PromptBuilderState,\n  PromptId,\n  PromptRegistry,\n  PromptStep,\n  PromptVariables,\n  StepType,\n} from \"./types.js\";\n\n// Cache for generated prompts, populated by registerPrompts()\nlet promptCache: Record<string, GeneratedPrompt> = {};\n\nfunction registerPrompts(prompts: Record<string, GeneratedPrompt>): void {\n  promptCache = { ...promptCache, ...prompts };\n}\n\nfunction processTemplate(\n  text: string,\n  options: Record<string, string | boolean> = {},\n): string {\n  // Recursively process optional blocks (handles nesting)\n  const processOptionals = (str: string): string =>\n    str.replace(/\\{\\{#(\\w+)\\}\\}([\\s\\S]*?)\\{\\{\\/\\1\\}\\}/g, (_, name, content) =>\n      options[name] ? processOptionals(content) : \"\",\n    );\n\n  // Replace variables {{name}} (not #name or /name)\n  const processVars = (str: string): string =>\n    str.replace(/\\{\\{(?![#\\/])(\\w+)\\}\\}/g, (match, name) => {\n      const value = options[name];\n      return typeof value === \"string\" ? value : match;\n    });\n\n  return processVars(processOptionals(text)).replace(/\\n{3,}/g, \"\\n\\n\");\n}\n\nfunction prompt<Id extends string, Optionals extends string = never>(\n  id: Id,\n  promptFunc: (p: PromptBuilder) => PromptBuilder<Optionals>,\n): Prompt<Id, Optionals> {\n  const { builder, state } = createBuilder();\n  promptFunc(builder);\n\n  return {\n    id,\n    _state: state,\n    toString: ((options?: Record<string, string | boolean>): string => {\n      const text = promptCache[id]?.text ?? \"\";\n      return processTemplate(text, options).trim();\n    }) as Prompt<Id, Optionals>[\"toString\"],\n  };\n}\n\nexport {\n  formatStepForAI,\n  prompt,\n  registerPrompts,\n  type GeneratedPrompt,\n  type Nudge,\n  type Prompt,\n  type PromptBuilder,\n  type PromptBuilderState,\n  type PromptId,\n  type PromptRegistry,\n  type PromptStep,\n  type PromptVariables,\n  type StepType,\n};\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nudge-ai/core",
+  "version": "0.0.1-beta.0",
+  "description": "Core library for Nudge - type-safe prompt builder for AI applications",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nudge-libs/nudge.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "prompt",
+    "prompt-engineering",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsdown": "^0.19.0",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  }
+}