@prompty/core 2.0.0-alpha.1 → 2.0.0-alpha.3

package/README.md

@@ -1,105 +1,108 @@
-# @prompty/core
-
-Prompty core runtime — load, render, parse, and trace `.prompty` files in TypeScript/JavaScript.
-
-## Installation
-
-```bash
-npm install @prompty/core
-```
-
-You'll also need a **provider package** for your LLM:
-
-```bash
-# OpenAI
-npm install @prompty/openai
-
-# Azure AI Foundry
-npm install @prompty/foundry
-```
-
-## Quick Start
-
-```typescript
-import "@prompty/openai"; // registers the OpenAI provider
-import { load, run } from "@prompty/core";
-
-// Load and run a .prompty file
-const result = await run("./my-prompt.prompty", {
-  question: "What is the capital of France?",
-});
-console.log(result);
-```
-
-## Step-by-Step Usage
-
-```typescript
-import "@prompty/openai";
-import { load, prepare, execute, process } from "@prompty/core";
-
-// 1. Load — parse .prompty file into a typed Prompty object
-const agent = await load("./chat.prompty");
-
-// 2. Prepare — render template + parse into messages
-const messages = await prepare(agent, { name: "Alice" });
-
-// 3. Execute — call the LLM
-const response = await execute(agent, messages);
-
-// 4. Process — extract the result
-const result = await process(agent, response);
-```
-
-## What's a `.prompty` file?
-
-A Markdown file with YAML frontmatter that defines an LLM prompt:
-
-```prompty
----
-name: greeting
-model:
-  id: gpt-4o-mini
-  provider: openai
-  connection:
-    kind: key
-    endpoint: ${env:OPENAI_BASE_URL}
-    apiKey: ${env:OPENAI_API_KEY}
----
-system:
-You are a helpful assistant.
-
-user:
-Hello, my name is {{name}}. {{question}}
-```
-
-## Tracing
-
-```typescript
-import { Tracer, PromptyTracer } from "@prompty/core";
-
-// Write .tracy JSON files to .runs/
-const tracer = new PromptyTracer({ outputDir: ".runs" });
-Tracer.add("prompty", tracer.factory);
-
-const result = await run("./chat.prompty", { question: "Hi" });
-console.log("Trace:", tracer.lastTracePath);
-```
-
-## Key Exports
-
-| Export | Description |
-|--------|-------------|
-| `load` | Parse a `.prompty` file → `Prompty` object |
-| `prepare` | Render template + parse → `Message[]` |
-| `execute` | Call the LLM provider |
-| `process` | Extract result from LLM response |
-| `run` | All-in-one: load → prepare → execute → process |
-| `executeAgent` | Agent loop with tool calling |
-| `Tracer` / `PromptyTracer` | Observability and tracing |
-| `registerExecutor` / `registerProcessor` | Register custom providers |
-| `registerConnection` | Register named connections |
-| `Message`, `ContentPart`, `PromptyStream` | Core types |
-
-## License
-
-MIT
+# @prompty/core
+
+Prompty core runtime — load, render, parse, and trace `.prompty` files in TypeScript/JavaScript.
+
+## Installation
+
+```bash
+npm install @prompty/core
+```
+
+You'll also need a **provider package** for your LLM:
+
+```bash
+# OpenAI
+npm install @prompty/openai
+
+# Azure AI Foundry
+npm install @prompty/foundry
+
+# Anthropic
+npm install @prompty/anthropic
+```
+
+## Quick Start
+
+```typescript
+import "@prompty/openai"; // registers the OpenAI provider
+import { load, run } from "@prompty/core";
+
+// Load and run a .prompty file
+const result = await run("./my-prompt.prompty", {
+  question: "What is the capital of France?",
+});
+console.log(result);
+```
+
+## Step-by-Step Usage
+
+```typescript
+import "@prompty/openai";
+import { load, prepare, execute, process } from "@prompty/core";
+
+// 1. Load — parse .prompty file into a typed Prompty object
+const agent = await load("./chat.prompty");
+
+// 2. Prepare — render template + parse into messages
+const messages = await prepare(agent, { name: "Alice" });
+
+// 3. Execute — call the LLM
+const response = await execute(agent, messages);
+
+// 4. Process — extract the result
+const result = await process(agent, response);
+```
+
+## What's a `.prompty` file?
+
+A Markdown file with YAML frontmatter that defines an LLM prompt:
+
+```prompty
+---
+name: greeting
+model:
+  id: gpt-4o-mini
+  provider: openai
+  connection:
+    kind: key
+    endpoint: ${env:OPENAI_BASE_URL}
+    apiKey: ${env:OPENAI_API_KEY}
+---
+system:
+You are a helpful assistant.
+
+user:
+Hello, my name is {{name}}. {{question}}
+```
+
+## Tracing
+
+```typescript
+import { Tracer, PromptyTracer } from "@prompty/core";
+
+// Write .tracy JSON files to .runs/
+const tracer = new PromptyTracer({ outputDir: ".runs" });
+Tracer.add("prompty", tracer.factory);
+
+const result = await run("./chat.prompty", { question: "Hi" });
+console.log("Trace:", tracer.lastTracePath);
+```
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `load` | Parse a `.prompty` file → `Prompty` object |
+| `prepare` | Render template + parse → `Message[]` |
+| `execute` | Call the LLM provider |
+| `process` | Extract result from LLM response |
+| `run` | All-in-one: load → prepare → execute → process |
+| `executeAgent` | Agent loop with tool calling |
+| `Tracer` / `PromptyTracer` | Observability and tracing |
+| `registerExecutor` / `registerProcessor` | Register custom providers |
+| `registerConnection` | Register named connections |
+| `Message`, `ContentPart`, `PromptyStream` | Core types |
+
+## License
+
+MIT

package/dist/index.cjs

@@ -4537,6 +4537,114 @@ async function execute(prompt, inputs, options) {
     return result;
   });
 }
+function isAsyncIterable(value) {
+  return value != null && typeof value === "object" && Symbol.asyncIterator in value;
+}
+function isToolCallLike(item) {
+  return typeof item === "object" && item !== null && "id" in item && "name" in item && "arguments" in item;
+}
+async function consumeStream(agent, response) {
+  const processed = await process2(agent, response);
+  const toolCalls = [];
+  const textParts = [];
+  if (isAsyncIterable(processed)) {
+    for await (const item of processed) {
+      if (isToolCallLike(item)) {
+        toolCalls.push(item);
+      } else if (typeof item === "string") {
+        textParts.push(item);
+      }
+    }
+  } else if (typeof processed === "string") {
+    textParts.push(processed);
+  }
+  return { toolCalls, content: textParts.join("") };
+}
+async function buildToolMessagesFromCalls(toolCalls, textContent, tools, agent, parentEmit) {
+  const provider = resolveProvider(agent);
+  const apiType = agent.model?.apiType || "chat";
+  const messages = [];
+  const toolInputs = [];
+  if (provider === "anthropic") {
+    const rawContent = [];
+    if (textContent) rawContent.push({ type: "text", text: textContent });
+    for (const tc of toolCalls) {
+      rawContent.push({
+        type: "tool_use",
+        id: tc.id,
+        name: tc.name,
+        input: JSON.parse(tc.arguments)
+      });
+    }
+    messages.push(
+      new Message("assistant", textContent ? [text(textContent)] : [], { content: rawContent })
+    );
+  } else if (apiType === "responses") {
+    for (const tc of toolCalls) {
+      messages.push(
+        new Message("assistant", [], {
+          responses_function_call: {
+            type: "function_call",
+            call_id: tc.id,
+            name: tc.name,
+            arguments: tc.arguments
+          }
+        })
+      );
+    }
+  } else {
+    const rawToolCalls = toolCalls.map((tc) => ({
+      id: tc.id,
+      type: "function",
+      function: { name: tc.name, arguments: tc.arguments }
+    }));
+    messages.push(
+      new Message("assistant", textContent ? [text(textContent)] : [], {
+        tool_calls: rawToolCalls
+      })
+    );
+  }
+  const toolResultBlocks = [];
+  for (const tc of toolCalls) {
+    let result;
+    let parsedArgs;
+    try {
+      parsedArgs = JSON.parse(tc.arguments);
+      const toolFn = tools[tc.name];
+      if (!toolFn) {
+        result = `Error: tool "${tc.name}" not found`;
+      } else {
+        const toolResult = await traceSpan(tc.name, async (toolEmit) => {
+          toolEmit("signature", `prompty.tool.${tc.name}`);
+          toolEmit("description", `Execute tool: ${tc.name}`);
+          toolEmit("inputs", { arguments: parsedArgs, id: tc.id });
+          const r = await toolFn(...Array.isArray(parsedArgs) ? parsedArgs : [parsedArgs]);
+          const str = typeof r === "string" ? r : JSON.stringify(r);
+          toolEmit("result", str);
+          return str;
+        });
+        result = toolResult;
+      }
+    } catch (err) {
+      result = `Error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    toolInputs.push({ name: tc.name, arguments: parsedArgs, id: tc.id, result });
+    if (provider === "anthropic") {
+      toolResultBlocks.push({ type: "tool_result", tool_use_id: tc.id, content: result });
+    } else {
+      messages.push(
+        new Message("tool", [text(result)], { tool_call_id: tc.id, name: tc.name })
+      );
+    }
+  }
+  if (provider === "anthropic" && toolResultBlocks.length > 0) {
+    messages.push(new Message("user", [], { tool_results: toolResultBlocks }));
+  }
+  if (parentEmit) {
+    parentEmit("inputs", { tool_calls: toolInputs });
+  }
+  return messages;
+}
 async function executeAgent(prompt, inputs, options) {
   return traceSpan("executeAgent", async (emit) => {
     const agent = typeof prompt === "string" ? await traceSpan("load", async (loadEmit) => {
@@ -4557,7 +4665,32 @@ async function executeAgent(prompt, inputs, options) {
     const executor = getExecutor(provider);
     let response = await executor.execute(agent, messages);
     let iteration = 0;
-    while (hasToolCalls(response)) {
+    while (true) {
+      if (isAsyncIterable(response)) {
+        const { toolCalls, content } = await consumeStream(agent, response);
+        if (toolCalls.length === 0) {
+          emit("iterations", iteration);
+          emit("result", content);
+          return content;
+        }
+        iteration++;
+        if (iteration > maxIterations) {
+          throw new Error(
+            `Agent loop exceeded maxIterations (${maxIterations}). The model kept requesting tool calls. Increase maxIterations or check your tools.`
+          );
+        }
+        const toolMessages2 = await traceSpan("toolCalls", async (toolEmit) => {
+          toolEmit("signature", "prompty.executeAgent.toolCalls");
+          toolEmit("description", `Tool call round ${iteration}`);
+          const result2 = await buildToolMessagesFromCalls(toolCalls, content, tools, agent, toolEmit);
+          toolEmit("result", result2.map((m) => ({ role: m.role, content: m.parts.map((p) => p.value ?? "").join(""), metadata: m.metadata })));
+          return result2;
+        });
+        messages.push(...toolMessages2);
+        response = await executor.execute(agent, messages);
+        continue;
+      }
+      if (!hasToolCalls(response)) break;
       iteration++;
       if (iteration > maxIterations) {
         throw new Error(
@@ -4631,15 +4764,37 @@ function hasToolCalls(response) {
   if (typeof response !== "object" || response === null) return false;
   const r = response;
   const choices = r.choices;
-  if (!Array.isArray(choices) || choices.length === 0) return false;
-  const choice = choices[0];
-  const message = choice.message;
-  if (!message) return false;
-  const toolCalls = message.tool_calls;
-  return Array.isArray(toolCalls) && toolCalls.length > 0;
+  if (Array.isArray(choices) && choices.length > 0) {
+    const choice = choices[0];
+    const message = choice.message;
+    if (message) {
+      const toolCalls = message.tool_calls;
+      if (Array.isArray(toolCalls) && toolCalls.length > 0) return true;
+    }
+  }
+  if (r.stop_reason === "tool_use" && Array.isArray(r.content)) {
+    return r.content.some(
+      (block) => block.type === "tool_use"
+    );
+  }
+  if (r.object === "response" && Array.isArray(r.output)) {
+    return r.output.some(
+      (item) => item.type === "function_call"
+    );
+  }
+  return false;
 }
 async function buildToolResultMessages(response, tools, parentEmit) {
   const r = response;
+  if (Array.isArray(r.content) && r.stop_reason === "tool_use") {
+    return buildAnthropicToolResultMessages(r, tools, parentEmit);
+  }
+  if (r.object === "response" && Array.isArray(r.output)) {
+    return buildResponsesToolResultMessages(r, tools, parentEmit);
+  }
+  return buildOpenAIToolResultMessages(r, tools, parentEmit);
+}
+async function buildOpenAIToolResultMessages(r, tools, parentEmit) {
   const choices = r.choices;
   const choice = choices[0];
   const message = choice.message;
@@ -4691,6 +4846,109 @@ async function buildToolResultMessages(response, tools, parentEmit) {
   }
   return messages;
 }
+async function buildAnthropicToolResultMessages(r, tools, parentEmit) {
+  const content = r.content;
+  const toolUseBlocks = content.filter((block) => block.type === "tool_use");
+  const messages = [];
+  const textParts = content.filter((block) => block.type === "text").map((block) => text(block.text));
+  messages.push(
+    new Message("assistant", textParts, { content })
+  );
+  const toolInputs = [];
+  const toolResultBlocks = [];
+  for (const block of toolUseBlocks) {
+    const toolName = block.name;
+    const toolCallId = block.id;
+    const toolArgs = block.input;
+    let result;
+    try {
+      const toolFn = tools[toolName];
+      if (!toolFn) {
+        result = `Error: tool "${toolName}" not found`;
+      } else {
+        const toolResult = await traceSpan(toolName, async (toolEmit) => {
+          toolEmit("signature", `prompty.tool.${toolName}`);
+          toolEmit("description", `Execute tool: ${toolName}`);
+          toolEmit("inputs", { arguments: toolArgs, tool_use_id: toolCallId });
+          const r2 = await toolFn(...Array.isArray(toolArgs) ? toolArgs : [toolArgs]);
+          const str = typeof r2 === "string" ? r2 : JSON.stringify(r2);
+          toolEmit("result", str);
+          return str;
+        });
+        result = toolResult;
+      }
+    } catch (err) {
+      result = `Error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    toolInputs.push({ name: toolName, arguments: toolArgs, tool_use_id: toolCallId, result });
+    toolResultBlocks.push({
+      type: "tool_result",
+      tool_use_id: toolCallId,
+      content: result
+    });
+  }
+  if (parentEmit) {
+    parentEmit("inputs", { tool_calls: toolInputs });
+  }
+  messages.push(
+    new Message("user", [], { tool_results: toolResultBlocks })
+  );
+  return messages;
+}
+async function buildResponsesToolResultMessages(r, tools, parentEmit) {
+  const output = r.output;
+  const funcCalls = output.filter((item) => item.type === "function_call");
+  const messages = [];
+  const toolInputs = [];
+  for (const fc of funcCalls) {
+    const toolName = fc.name;
+    const callId = fc.call_id ?? fc.id ?? "";
+    const argsStr = fc.arguments ?? "{}";
+    messages.push(
+      new Message("assistant", [], {
+        responses_function_call: {
+          type: "function_call",
+          call_id: callId,
+          name: toolName,
+          arguments: argsStr
+        }
+      })
+    );
+    let result;
+    let parsedArgs;
+    try {
+      parsedArgs = JSON.parse(argsStr);
+      const toolFn = tools[toolName];
+      if (!toolFn) {
+        result = `Error: tool "${toolName}" not found`;
+      } else {
+        const toolResult = await traceSpan(toolName, async (toolEmit) => {
+          toolEmit("signature", `prompty.tool.${toolName}`);
+          toolEmit("description", `Execute tool: ${toolName}`);
+          toolEmit("inputs", { arguments: parsedArgs, call_id: callId });
+          const r2 = await toolFn(...Array.isArray(parsedArgs) ? parsedArgs : [parsedArgs]);
+          const str = typeof r2 === "string" ? r2 : JSON.stringify(r2);
+          toolEmit("result", str);
+          return str;
+        });
+        result = toolResult;
+      }
+    } catch (err) {
+      result = `Error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    toolInputs.push({ name: toolName, arguments: parsedArgs, call_id: callId, result });
+    messages.push(
+      new Message("tool", [text(result)], {
+        tool_call_id: callId,
+        name: toolName
+      })
+    );
+  }
+  if (parentEmit) {
+    parentEmit("inputs", { tool_calls: toolInputs });
+  }
+  return messages;
+}
 var runAgent = executeAgent;
 
 // src/renderers/nunjucks.ts