llm-exe 2.2.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-exe",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Simplify building LLM-powered apps with easy-to-use base components, supporting text and chat-based prompts with handlebars template engine, output parsers, and flexible function calling capabilities.",
   "keywords": [
     "ai",
@@ -38,7 +38,8 @@
     "typecheck": "tsc --noEmit",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --config jest.config.ts --detectOpenHandles --coverage --forceExit",
     "test-examples": "eval $(cat .env) NODE_OPTIONS=--experimental-vm-modules jest --config jest.config.examples.ts --detectOpenHandles --coverage --forceExit",
-    "test-one": "eval $(cat .env) NODE_OPTIONS=--experimental-vm-modules jest --detectOpenHandles --coverage --forceExit --config jest.config.examples.ts examples/helloWorldReasoning.test.ts",
+    "test-one": "eval $(cat .env) NODE_OPTIONS=--experimental-vm-modules jest --detectOpenHandles --coverage --forceExit --config jest.config.examples.ts examples/intentBot.test.ts",
+    "run-one": "eval $(cat .env) ts-node ./examples/chains/self-refinement/usage.ts",
     "build": "(concurrently \"tsc --p ./tsconfig.json -w\" \"tsc-alias -p tsconfig.json -w\")",
     "build:ci": "tsup src/index.ts --format cjs,esm --dts --clean",
     "build:browser": "tsup src/script.ts --format iife --platform browser --target es6 --sourcemap --clean --external '**'",
@@ -46,8 +47,8 @@
     "build:docs-examples": "./node_modules/.bin/esbuild examples/prompt/index.ts examples/state/index.ts --bundle --outdir=docs/.vitepress/components/examples  --platform=node --target=es6 --format=esm",
     "build:watch:docs-examples": "./node_modules/.bin/esbuild  examples/prompt/index.ts examples/state/index.ts  --watch --bundle --outdir=docs/.vitepress/components/examples  --platform=node --target=es6 --format=esm",
     "predocs:build": "npm run build:docs-examples",
-    "docs:dev": "(concurrently \"vitepress dev docs\" \"npm run build:watch:docs-examples\")",
-    "docs:build": "vitepress build docs",
+    "docs:dev": "eval $(cat docs/.env) && concurrently \"vitepress dev docs\" \"npm run build:watch:docs-examples\"",
+    "docs:build": "eval $(cat docs/.env) && vitepress build docs",
     "lint": "eslint .",
     "format:check": "prettier --check \"src\"",
     "format:write": "prettier --write \"src\"",
@@ -88,7 +89,7 @@
     "tsconfig-paths": "4.2.0",
     "tsup": "^8.4.0",
     "typescript": "5.8.3",
-    "vitepress": "^1.3.2"
+    "vitepress": "^1.6.3"
   },
   "repository": {
     "type": "git",

package/readme.md

@@ -6,81 +6,151 @@ A package that provides simplified base components to make building and maintain
 
 - Write functions powered by LLM's with easy to use building blocks.
 - Pure Javascript and Typescript. Allows you to pass and infer types.
+- Supercharge your prompts by using handlebars within prompt template.
 - Support for text-based (llama-3) and chat-based prompts. (gpt-4o, claude-3.5, grok-3, Gemini, Bedrock, Ollama, etc)
 - Call LLM's from different providers without changing your code. (OpenAi/Anthropic/xAI/Google/AWS Bedrock/Ollama/Deepseek)
-- Supercharge your prompts by using handlebars within prompt template.
 - Allow LLM's to call functions (or call other LLM executors).
 - Not very opinionated. You have control on how you use it.
 
-![llm-exe](https://assets.llm-exe.com/llm-exe-featured.jpg)
-
+![llm-exe](https://assets.llm-exe.com/llm-exe-featured-2025.png)
 
 See full docs here: [https://llm-exe.com](https://llm-exe.com)
 
-
 ---
+
 # Install
 
 Install llm-exe using npm.
+
 ```
 npm i llm-exe
 ```
 
+ESM-first. CommonJS works too.
+
 ```typescript
+// ESM
 import * as llmExe from "llm-exe";
+// or specific modules
+import { useLlm, createChatPrompt, createParser } from "llm-exe";
+
+// CommonJS
+const llmExe = require("llm-exe");
+```
 
-// or 
+## Overview
 
-import { /* specific modules */ } from from "llm-exe"
+```ts
+// Prompt
+const prompt = createChatPrompt("You are a support agent. Help the user.");
+prompt.addUserMessage("I need help with my order.");
+
+// LLM
+const llm = useLlm("openai.gpt-4o");
+
+// Parser
+const parser = createParser("json", { schema: mySchema });
+
+// Executor
+const executor = createLlmExecutor({ llm, prompt, parser });
+await executor.execute({ input: "..." });
+```
+
+#### Prompt Helpers
+
+```ts
+const prompt = createChatPrompt(`
+{{#if user.isFirstTime}}
+Welcome!
+{{else}}
+Welcome back!
+{{/if}}
+`);
+```
+
+#### Built-In Parsers
+
+```ts
+createParser("stringExtract", { enum: ["yes", "no"] });
+createParser("listToJson");
+createParser("listToArray");
+createParser("markdownCodeBlock");
+// ...etc
+```
+
+#### Custom Parsers
+
+```ts
+const parser = createCustomParser("MyUppercaseParser", (output, input) => {
+  return output.toUpperCase();
+});
+```
+
+#### State
+
+```ts
+const dialogue = createDialogue("chat");
+dialogue.setUserMessage("Hi");
+dialogue.setAssistantMessage("Hello!");
+dialogue.getHistory(); // returns chat array
+```
+
+#### Hooks
+
+```ts
+executor.on("onSuccess", console.log);
+executor.on("onError", console.error);
 ```
 
 ## Basic Example
+
 Below is simple example:
+
 ```typescript
-import * as llmExe from "llm-exe";
+// 1. Use the model you want
+const llm = useLlm("openai.gpt-4o");
+
+// 2. Create a parameterized prompt
+const instruction = `
+You are a classifier. Given a user message, reply with the category it belongs to.
+Pick from only the following options:
+
+{{#each options}}- {{this}}
+{{/each}}
+
+Respond with only one of the options.`;
+
+const prompt = createChatPrompt<{ options: string[]; input: string }>(
+  instruction
+).addUserMessage("{{input}}"); // placeholder for message content
+
+// 3. Create a parser that ensures a clean match
+const parser = createParser("stringExtract", {
+  enum: ["billing", "support", "cancel", "unknown"],
+});
+
+// 4. Create the executor
+const classifyMessage = createLlmExecutor({
+  llm,
+  prompt,
+  parser,
+});
+
+// 5. Pass in options and a message — like a real function!
+// classifyMessage.execute is typed based on the prompt/parser!
+const result = await classifyMessage.execute({
+  input: "Hi, I'm moving and no longer need this service.",
+  options: ["billing", "support", "cancel", "unknown"],
+});
+
+console.log(result); // => "cancel"
+```
+
+### Further Reading
+
+[Find llm-exe on Medium](https://medium.com/llm-exe)
 
-/**
- * Define a yes/no llm-powered function
- */
-export async function YesOrNoBot<I extends string>(input: I) {
-  const llm = llmExe.useLlm("openai.gpt-4o-mini");
-
-  const instruction = `You are not an assistant, I need you to reply with only 
-  'yes' or 'no' as an answer to the question below. Do not explain yourself 
-  or ask questions. Answer with only yes or no.`;
-
-  const prompt = llmExe
-    .createChatPrompt(instruction)
-    .addUserMessage(input)
-    .addUserMessage(`yes or no:`);
-
-  const parser = llmExe.createParser("stringExtract", { enum: ["yes", "no"] });
-  return llmExe.createLlmExecutor({ llm, prompt, parser }).execute({ input });
-}
-
-const isTheSkyBlue = await YesOrNoBot(`Is AI cool?`)
-
-/**
- * 
- * The prompt sent to the LLM would be: 
- * (line breaks added for readability)
- * 
- * [{ 
- *   role: 'system', 
- *    content: 'You are not an assistant, I need you to reply with only 
-  'yes' or 'no' as an answer to the question asked by the user. Do not explain yourself 
-  or ask questions. Answer only with yes or no.' 
- * },
- * { 
- *   role: 'user',
- *   content: 'Is AI cool?'
- * }]
- * 
- */
-
-/**
- * 
- * console.log(isTheSkyBlue)
- * yes
- * /
-```
+- [Prompt: Create Typed, Modular Prompt Templates in TypeScript](https://medium.com/llm-exe/llm-exe-intro-prompt-3d9d40dc923d)
+- [LLM: Keep Your Code Clean While Switching Models](https://medium.com/llm-exe/llm-exe-intro-llm-2f5f35e60caf)
+- [Parser: Parse, Validate, and Structure AI Responses](https://medium.com/llm-exe/llm-exe-intro-parser-aed787f81082)
+- [Executor: Prompt, Parse, and Execute with Type Safety](https://medium.com/llm-exe/llm-exe-intro-llm-executor-52bb95c76c84)