llm-agent-runtime 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,177 @@
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import type { Embeddings } from "@langchain/core/embeddings";
+import type { DynamicStructuredTool } from "@langchain/core/tools";
+import type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint";
+/** Intent catalog entry used for embedding routing + sticky-flow rules. */
+export type IntentDefinition = {
+    name: string;
+    examples: string[];
+    /** Persist this intent across turns until finalize marks complete. */
+    sticky?: boolean;
+    /** Short description for the LLM intent router. */
+    description?: string;
+};
+/** Context passed into prompt builders (app-defined shape). */
+export type PromptContext = {
+    hasConversationHistory: boolean;
+    intent: string;
+    intentScore?: number;
+    message?: string;
+    /** Arbitrary app context (userInfo, contactName, phone, etc.). */
+    context?: Record<string, unknown>;
+};
+export type IntentBinding = {
+    prompt: (ctx: PromptContext) => string;
+    tools: (phoneKey: string) => DynamicStructuredTool[];
+};
+export type IntentRegistry = Record<string, IntentBinding>;
+export type DetectedIntentResult = {
+    intent: string;
+    score: number;
+};
+export type LlmIntentResult = DetectedIntentResult & {
+    action: "continue" | "switch" | "cancel";
+    reason?: string;
+};
+export type FlowState = {
+    active: boolean;
+    intent: string | null;
+};
+export type ChatFlowState = {
+    intent: string;
+    timestamp: number;
+};
+export type FlowResolution = {
+    messageIntent: DetectedIntentResult;
+    flow: FlowState;
+    promptIntent: string;
+    llmResult?: LlmIntentResult;
+};
+export type LlmProvider = "ollama" | "openai";
+export type LlmConfig = {
+    provider: LlmProvider;
+    model: string;
+    intentRouterModel?: string;
+    embeddingsModel?: string;
+    embeddingsProvider?: LlmProvider;
+    baseUrl?: string;
+    apiKey?: string;
+    temperature?: number;
+};
+export type CacheConfig = {
+    /** Exact-match answer cache (Redis). Default false. */
+    enabled?: boolean;
+    /** TTL for cached answers in seconds. Default 24h. */
+    ttlSeconds?: number;
+    /** TTL for sticky flow state. Default 30m. */
+    flowTtlSeconds?: number;
+    scope?: string;
+};
+export type TracingConfig = {
+    enabled?: boolean;
+    projectName?: string;
+};
+export type ToolCall = {
+    name?: string;
+    args?: Record<string, unknown>;
+};
+/**
+ * Per-tool parser (same idea as Xel extractToolCall switch cases).
+ * Mutate `acc` to accumulate structured outputs; skip if already set (first-wins).
+ */
+export type ToolExtractor = (args: Record<string, unknown>, acc: Record<string, unknown>) => void;
+/** toolName → extractor. Keys are LangChain tool `name` values. */
+export type ToolExtractorMap = Record<string, ToolExtractor>;
+export type FinalizeFlowInput = {
+    threadId: string;
+    promptIntent: string;
+    flow: FlowState;
+    toolOutputs: Record<string, unknown>;
+};
+export type FinalizeFlowResult = {
+    flow: FlowState;
+    flowCompleted: boolean;
+    /** Extra fields the app wants returned from invoke (campaign, tickets, …). */
+    extras?: Record<string, unknown>;
+};
+export type InvokeInput = {
+    message: string;
+    threadId: string;
+    /** App context passed to prompts and optional phoneKey helper. */
+    context?: Record<string, unknown>;
+    /** Force an intent (skips hybrid routing). */
+    explicitIntent?: string;
+    phoneKey?: string;
+};
+export type InvokeResult = {
+    messages: unknown[];
+    answer?: string;
+    intent: DetectedIntentResult;
+    flow: FlowState;
+    toolOutputs: Record<string, unknown>;
+    flowCompleted: boolean;
+    router?: {
+        action: LlmIntentResult["action"];
+        reason?: string;
+    };
+    extras?: Record<string, unknown>;
+};
+export type AgentRuntimeConfig = {
+    redisUrl?: string;
+    llm: LlmConfig;
+    /** Intent catalog for embeddings + sticky flags. */
+    intents: IntentDefinition[];
+    /** Per-intent prompt + tools factory. */
+    intentRegistry: IntentRegistry;
+    /** Digit / short-code → intent (e.g. greeting menu "1" → create_campaign). */
+    menuMap?: Record<string, string>;
+    /** Map legacy/alias names onto catalog intents. */
+    intentAliases?: Record<string, string>;
+    defaultIntent?: string;
+    /** Override LLM router system prompt. */
+    routerSystemPrompt?: string | ((intents: IntentDefinition[]) => string);
+    /** Custom system prompt builder; default uses intentRegistry[intent].prompt. */
+    buildSystemPrompt?: (ctx: PromptContext) => string;
+    /**
+     * Per-tool extractors (Xel extractToolCall style).
+     * Prefer this over a custom `extractToolOutputs` unless you need full control.
+     */
+    toolExtractors?: ToolExtractorMap;
+    /** Seed object for tool extractors (e.g. () => ({ tickets: [] })). */
+    initialToolOutputs?: () => Record<string, unknown>;
+    /** If true, unknown tool names are kept as raw args. Default false when using toolExtractors. */
+    includeUnknownToolOutputs?: boolean;
+    /** Full custom extractor. Overrides toolExtractors when provided. */
+    extractToolOutputs?: (messages: unknown[]) => Record<string, unknown>;
+    /**
+     * Decide when a sticky flow is done.
+     * Default: never auto-complete (app must clear via finalize or clearFlow).
+     */
+    finalizeFlow?: (input: FinalizeFlowInput) => FinalizeFlowResult | Promise<FinalizeFlowResult>;
+    /** Derive phone/session key for tools. Default: phoneKey ?? threadId. */
+    resolvePhoneKey?: (input: {
+        threadId: string;
+        phoneKey?: string;
+        context?: Record<string, unknown>;
+    }) => string;
+    cache?: CacheConfig;
+    tracing?: TracingConfig;
+    recursionLimit?: number;
+    /** Sticky-flow switch thresholds (defaults match Xel-agent). */
+    thresholds?: {
+        switch?: number;
+        ambiguous?: number;
+        switchMargin?: number;
+        llmConfidence?: number;
+        embeddingConfidence?: number;
+    };
+    /** Inject pre-built models instead of creating from llm config. */
+    models?: {
+        chat?: BaseChatModel;
+        intentRouter?: BaseChatModel;
+        embeddings?: Embeddings;
+    };
+    /** Inject a custom checkpointer (skips redisUrl / MemorySaver). */
+    checkpointer?: BaseCheckpointSaver;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/message.d.ts

@@ -0,0 +1,9 @@
+export type CachedMessage = {
+    content?: unknown;
+    kwargs?: {
+        content?: unknown;
+    };
+};
+/** Returns the content of the most recent non-empty message. */
+export declare const getLastMessageContent: (messages: CachedMessage[] | undefined) => string | undefined;
+//# sourceMappingURL=message.d.ts.map

package/dist/utils/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../src/utils/message.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,qBAAqB,GAChC,UAAU,aAAa,EAAE,GAAG,SAAS,KACpC,MAAM,GAAG,SAcX,CAAC"}

package/dist/utils/message.js

@@ -0,0 +1,13 @@
+/** Returns the content of the most recent non-empty message. */
+export const getLastMessageContent = (messages) => {
+    if (!Array.isArray(messages)) {
+        return undefined;
+    }
+    for (const message of messages.toReversed()) {
+        const content = message.content ?? message.kwargs?.content;
+        if (typeof content === "string" && content.trim()) {
+            return content;
+        }
+    }
+    return undefined;
+};

package/dist/utils/normalize.d.ts

@@ -0,0 +1,3 @@
+/** Normalize text for exact-match cache keys. */
+export declare function normalize(text: string): string;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/utils/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/utils/normalize.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM9C"}

package/dist/utils/normalize.js

@@ -0,0 +1,8 @@
+/** Normalize text for exact-match cache keys. */
+export function normalize(text) {
+    return text
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9\s]/g, "")
+        .replace(/\s+/g, " ");
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "llm-agent-runtime",
+  "version": "0.1.0",
+  "description": "Reusable LangGraph agent runtime: intent routing, sticky flows, Redis checkpointer, optional answer cache",
+  "license": "ISC",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test src/**/*.test.ts",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@langchain/core": "^1.2.0",
+    "@langchain/langgraph": "^1.4.0",
+    "@langchain/langgraph-checkpoint": "^1.1.0",
+    "zod": "^4.0.0"
+  },
+  "dependencies": {
+    "@langchain/langgraph-checkpoint-redis": "^1.0.10",
+    "@langchain/ollama": "^1.3.0",
+    "@langchain/openai": "^1.5.1",
+    "redis": "^6.0.0"
+  },
+  "optionalDependencies": {
+    "langsmith": "^0.7.10"
+  },
+  "devDependencies": {
+    "@langchain/core": "^1.2.0",
+    "@langchain/langgraph": "^1.4.4",
+    "@langchain/langgraph-checkpoint": "^1.1.2",
+    "@types/node": "^25.9.3",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3",
+    "zod": "^4.4.3"
+  }
+}