@axlsdk/axl 0.2.0 → 0.4.0

package/README.md

@@ -108,16 +108,16 @@ const history = await session.history();
 
 ### Context Primitives
 
-All available on `ctx` inside workflow handlers:
+All available on `ctx` inside workflow handlers. See the [API Reference](../../docs/api-reference.md) for complete option types, valid values, and defaults.
 
 ```typescript
 // Invoke an agent
 const answer = await ctx.ask(agent, 'prompt', { schema, retries });
 
-// Run N concurrent tasks
+// Run 3 agents in parallel — each gets the same question independently
 const results = await ctx.spawn(3, async (i) => ctx.ask(agent, prompts[i]));
 
-// Consensus vote
+// Pick the answer that appeared most often (pure aggregation, no LLM involved)
 const winner = ctx.vote(results, { strategy: 'majority', key: 'answer' });
 
 // Self-correcting validation
@@ -144,7 +144,7 @@ const [a, b] = await ctx.parallel([
   () => ctx.ask(agentB, promptB),
 ]);
 
-// Map with bounded concurrency
+// Map with bounded concurrency — resolve when 3 of N succeed, cancel the rest
 const mapped = await ctx.map(items, async (item) => ctx.ask(agent, item), {
   concurrency: 5,
   quorum: 3,
@@ -166,21 +166,27 @@ Automatic span emission for every `ctx.*` primitive with cost-per-span attributi
 
 ```typescript
 import { defineConfig, AxlRuntime } from '@axlsdk/axl';
+import { BasicTracerProvider, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
 
+const tracerProvider = new BasicTracerProvider();
+tracerProvider.addSpanProcessor(new SimpleSpanProcessor(
+  new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }),
+));
+
 const config = defineConfig({
   telemetry: {
     enabled: true,
     serviceName: 'my-app',
-    exporter: new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }),
+    tracerProvider,
   },
 });
 
 const runtime = new AxlRuntime(config);
-runtime.initializeTelemetry();
+await runtime.initializeTelemetry();
 ```
 
-**Span model:** `axl.workflow.execute` > `axl.agent.ask` > `axl.tool.call`. Also: `axl.ctx.spawn`, `axl.ctx.race`, `axl.ctx.vote`, `axl.ctx.budget`, `axl.ctx.checkpoint`, `axl.ctx.awaitHuman`. Each span includes relevant attributes (cost, duration, token counts, etc.).
+**Span model:** `axl.workflow.execute` > `axl.agent.ask` > `axl.tool.call`. Also: `axl.ctx.spawn`, `axl.ctx.race`, `axl.ctx.vote`, `axl.ctx.budget`, `axl.ctx.awaitHuman`. Each span includes relevant attributes (cost, duration, token counts, etc.).
 
 When disabled (default), `NoopSpanManager` provides zero overhead.
 
@@ -210,7 +216,7 @@ import { AxlRuntime, InMemoryVectorStore, OpenAIEmbedder } from '@axlsdk/axl';
 
 const runtime = new AxlRuntime({
   memory: {
-    vector: new InMemoryVectorStore(),
+    vectorStore: new InMemoryVectorStore(),
     embedder: new OpenAIEmbedder({ model: 'text-embedding-3-small' }),
   },
 });
@@ -226,9 +232,13 @@ Vector store implementations: `InMemoryVectorStore` (testing), `SqliteVectorStor
 
 ### Agent Guardrails
 
-Input and output validation at the agent boundary:
+Input and output validation at the agent boundary. You define your own validation logic — Axl calls it before and after each LLM turn:
 
 ```typescript
+// Your validation functions — Axl doesn't ship these, you bring your own
+const containsPII = (text: string) => /\b\d{3}-\d{2}-\d{4}\b/.test(text);
+const isOffTopic = (text: string) => !text.toLowerCase().includes('support');
+
 const safe = agent({
   model: 'openai:gpt-4o',
   system: 'You are a helpful assistant.',
@@ -254,10 +264,11 @@ When `onBlock` is `'retry'`, the LLM sees the block reason and self-corrects (sa
 ```typescript
 const session = runtime.session('user-123', {
   history: {
-    maxMessages: 100,   // Trim oldest messages when exceeded
-    summarize: true,    // Auto-summarize trimmed messages
+    maxMessages: 100,          // Trim oldest messages when exceeded
+    summarize: true,           // Auto-summarize trimmed messages
+    summaryModel: 'openai:gpt-4o-mini',  // Model for summarization
   },
-  persist: true,        // Save to StateStore (default: true)
+  persist: true,               // Save to StateStore (default: true)
 });
 ```
 
@@ -267,6 +278,7 @@ const session = runtime.session('user-123', {
 |--------|------|---------|-------------|
 | `history.maxMessages` | `number` | unlimited | Max messages to retain |
 | `history.summarize` | `boolean` | `false` | Summarize trimmed messages |
+| `history.summaryModel` | `string` | — | Model URI for summarization (required when `summarize: true`) |
 | `persist` | `boolean` | `true` | Persist history to StateStore |
 
 ### Error Hierarchy
@@ -306,58 +318,17 @@ const runtime = new AxlRuntime({
 
 ### Provider URIs
 
-Four built-in providers are supported:
+Four built-in providers using the `provider:model` URI scheme:
 
 ```
-# OpenAI — Chat Completions API
-openai:gpt-4o                          # Flagship multimodal
-openai:gpt-4o-mini                     # Fast and affordable
-openai:gpt-4.1                         # GPT-4.1
-openai:gpt-4.1-mini                    # GPT-4.1 small
-openai:gpt-4.1-nano                    # GPT-4.1 cheapest
-openai:gpt-5                           # GPT-5
-openai:gpt-5-mini                      # GPT-5 small
-openai:gpt-5-nano                      # GPT-5 cheapest
-openai:gpt-5.1                         # GPT-5.1
-openai:gpt-5.2                         # GPT-5.2
-openai:o1                              # Reasoning
-openai:o1-mini                         # Reasoning (small)
-openai:o1-pro                          # Reasoning (pro)
-openai:o3                              # Reasoning
-openai:o3-mini                         # Reasoning (small)
-openai:o3-pro                          # Reasoning (pro)
-openai:o4-mini                         # Reasoning (small)
-openai:gpt-4-turbo                     # Legacy
-openai:gpt-4                           # Legacy
-openai:gpt-3.5-turbo                   # Legacy
-
-# OpenAI — Responses API (same models, better caching, native reasoning)
-openai-responses:gpt-4o
-openai-responses:o3
-
-# Anthropic
-anthropic:claude-opus-4-6              # Most capable
-anthropic:claude-sonnet-4-5            # Balanced
-anthropic:claude-haiku-4-5             # Fast and affordable
-anthropic:claude-sonnet-4              # Previous gen
-anthropic:claude-opus-4                # Previous gen
-anthropic:claude-3-7-sonnet            # Legacy
-anthropic:claude-3-5-sonnet            # Legacy
-anthropic:claude-3-5-haiku             # Legacy
-anthropic:claude-3-opus                # Legacy
-anthropic:claude-3-sonnet              # Legacy
-anthropic:claude-3-haiku               # Legacy
-
-# Google Gemini
-google:gemini-2.5-pro                  # Most capable
-google:gemini-2.5-flash                # Fast
-google:gemini-2.5-flash-lite           # Cheapest 2.5
-google:gemini-2.0-flash                # Previous gen
-google:gemini-2.0-flash-lite           # Previous gen (lite)
-google:gemini-3-pro-preview            # Next gen (preview)
-google:gemini-3-flash-preview          # Next gen fast (preview)
+openai:gpt-4o                          # OpenAI Chat Completions
+openai-responses:gpt-4o                # OpenAI Responses API
+anthropic:claude-sonnet-4-5            # Anthropic
+google:gemini-2.5-pro                  # Google Gemini
 ```
 
+See [docs/providers.md](../../docs/providers.md) for the full model list including reasoning models.
+
 ## License
 
 [Apache 2.0](../../LICENSE)

package/dist/index.cjs

@@ -1890,6 +1890,15 @@ function zodToJsonSchema(schema) {
 function estimateTokens(text) {
   return Math.ceil(text.length / 4);
 }
+function stripMarkdownFences(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("```")) {
+    const withoutOpening = trimmed.replace(/^```\w*\s*\n?/, "");
+    const withoutClosing = withoutOpening.replace(/\n?```\s*$/, "");
+    return withoutClosing.trim();
+  }
+  return trimmed;
+}
 function estimateMessagesTokens(messages) {
   let total = 0;
   for (const msg of messages) {
@@ -2583,7 +2592,7 @@ Please fix and try again.`;
       }
       if (options?.schema) {
         try {
-          const parsed = JSON.parse(content);
+          const parsed = JSON.parse(stripMarkdownFences(content));
           const validated = options.schema.parse(parsed);
           return validated;
         } catch (err) {
@@ -4722,6 +4731,7 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
   executions = /* @__PURE__ */ new Map();
   pendingDecisionResolvers = /* @__PURE__ */ new Map();
   abortControllers = /* @__PURE__ */ new Map();
+  registeredEvals = /* @__PURE__ */ new Map();
   mcpManager;
   memoryManager;
   spanManager = new NoopSpanManager();
@@ -4817,6 +4827,52 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
   getAgent(name) {
     return this.agents.get(name);
   }
+  /**
+   * Register an eval config for Studio introspection and execution.
+   * The config should be the result of `defineEval()` from `@axlsdk/eval`.
+   * An optional `executeWorkflow` function can override the default behavior
+   * of calling `runtime.execute()`.
+   */
+  registerEval(name, config, executeWorkflow) {
+    this.registeredEvals.set(name, { config, executeWorkflow });
+  }
+  /** Get metadata about all registered evals. */
+  getRegisteredEvals() {
+    const result = [];
+    for (const [name, { config }] of this.registeredEvals) {
+      const cfg = config;
+      result.push({
+        name,
+        workflow: cfg.workflow ?? "unknown",
+        dataset: cfg.dataset?.name ?? "unknown",
+        scorers: (cfg.scorers ?? []).map((s) => s.name ?? "unknown")
+      });
+    }
+    return result;
+  }
+  /** Get a registered eval config by name. */
+  getRegisteredEval(name) {
+    return this.registeredEvals.get(name);
+  }
+  /** Run a registered eval by name. */
+  async runRegisteredEval(name) {
+    const entry = this.registeredEvals.get(name);
+    if (!entry) throw new Error(`Eval "${name}" is not registered`);
+    if (entry.executeWorkflow) {
+      let runEvalFn;
+      try {
+        ({ runEval: runEvalFn } = await import("@axlsdk/eval"));
+      } catch {
+        throw new Error(
+          "axl-eval is required for AxlRuntime.runRegisteredEval(). Install it with: npm install @axlsdk/eval"
+        );
+      }
+      return runEvalFn(entry.config, entry.executeWorkflow);
+    }
+    return this.eval(
+      entry.config
+    );
+  }
   /** Get all execution info (running + completed). */
   getExecutions() {
     return [...this.executions.values()];
@@ -5200,10 +5256,10 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
   async eval(config) {
     let runEval;
     try {
-      ({ runEval } = await import("axl-eval"));
+      ({ runEval } = await import("@axlsdk/eval"));
     } catch {
       throw new Error(
-        "axl-eval is required for AxlRuntime.eval(). Install it with: npm install axl-eval"
+        "axl-eval is required for AxlRuntime.eval(). Install it with: npm install @axlsdk/eval"
       );
     }
     const executeWorkflow = async (input) => {
@@ -5230,10 +5286,10 @@ var AxlRuntime = class extends import_node_events2.EventEmitter {
   async evalCompare(baseline, candidate) {
     let evalCompareFn;
     try {
-      ({ evalCompare: evalCompareFn } = await import("axl-eval"));
+      ({ evalCompare: evalCompareFn } = await import("@axlsdk/eval"));
     } catch {
       throw new Error(
-        "axl-eval is required for AxlRuntime.evalCompare(). Install it with: npm install axl-eval"
+        "axl-eval is required for AxlRuntime.evalCompare(). Install it with: npm install @axlsdk/eval"
       );
     }
     return evalCompareFn(baseline, candidate);