@axlsdk/axl 0.1.0

package/README.md

@@ -0,0 +1,363 @@
+# axl
+
+Core SDK for orchestrating agentic systems in TypeScript.
+
+## Installation
+
+```bash
+npm install axl zod
+```
+
+## API
+
+### `tool(config)`
+
+Define a tool with Zod input validation:
+
+```typescript
+import { tool } from 'axl';
+import { z } from 'zod';
+
+const calculator = tool({
+  name: 'calculator',
+  description: 'Evaluate arithmetic expressions',
+  input: z.object({ expression: z.string() }),
+  handler: ({ expression }) => {
+    const result = new Function(`return (${expression})`)();
+    return { result };
+  },
+  retry: { attempts: 3, backoff: 'exponential' },
+  sensitive: false,
+});
+```
+
+### `agent(config)`
+
+Define an agent with model, system prompt, tools, and handoffs:
+
+```typescript
+import { agent } from 'axl';
+
+const researcher = agent({
+  name: 'researcher',
+  model: 'openai:gpt-4o',
+  system: 'You are a research assistant.',
+  tools: [calculator],
+  maxTurns: 10,
+  timeout: '30s',
+  temperature: 0.7,
+  version: 'v1.2',
+});
+```
+
+Dynamic model and system prompt selection:
+
+```typescript
+const dynamicAgent = agent({
+  model: (ctx) => ctx.metadata?.tier === 'premium'
+    ? 'openai:gpt-4o'
+    : 'openai:gpt-4.1-nano',
+  system: (ctx) => `You are a ${ctx.metadata?.role ?? 'general'} assistant.`,
+});
+```
+
+### `workflow(config)`
+
+Define a named workflow with typed input/output:
+
+```typescript
+import { workflow } from 'axl';
+import { z } from 'zod';
+
+const myWorkflow = workflow({
+  name: 'my-workflow',
+  input: z.object({ query: z.string() }),
+  output: z.object({ answer: z.string() }),
+  handler: async (ctx) => {
+    const answer = await ctx.ask(researcher, ctx.input.query);
+    return { answer };
+  },
+});
+```
+
+### `AxlRuntime`
+
+Register and execute workflows:
+
+```typescript
+import { AxlRuntime } from 'axl';
+
+const runtime = new AxlRuntime();
+runtime.register(myWorkflow);
+
+// Execute
+const result = await runtime.execute('my-workflow', { query: 'Hello' });
+
+// Stream
+const stream = runtime.stream('my-workflow', { query: 'Hello' });
+for await (const event of stream) {
+  if (event.type === 'token') process.stdout.write(event.data);
+}
+
+// Sessions
+const session = runtime.session('user-123');
+await session.send('my-workflow', { query: 'Hello' });
+await session.send('my-workflow', { query: 'Follow-up' });
+const history = await session.history();
+```
+
+### Context Primitives
+
+All available on `ctx` inside workflow handlers:
+
+```typescript
+// Invoke an agent
+const answer = await ctx.ask(agent, 'prompt', { schema, retries });
+
+// Run N concurrent tasks
+const results = await ctx.spawn(3, async (i) => ctx.ask(agent, prompts[i]));
+
+// Consensus vote
+const winner = ctx.vote(results, { strategy: 'majority', key: 'answer' });
+
+// Self-correcting validation
+const valid = await ctx.verify(
+  async (lastOutput, error) => ctx.ask(agent, prompt),
+  schema,
+  { retries: 3, fallback: defaultValue },
+);
+
+// Cost control
+const budgeted = await ctx.budget({ cost: '$1.00', onExceed: 'hard_stop' }, async () => {
+  return ctx.ask(agent, prompt);
+});
+
+// First to complete
+const fastest = await ctx.race([
+  () => ctx.ask(agentA, prompt),
+  () => ctx.ask(agentB, prompt),
+], { schema });
+
+// Concurrent independent tasks
+const [a, b] = await ctx.parallel([
+  () => ctx.ask(agentA, promptA),
+  () => ctx.ask(agentB, promptB),
+]);
+
+// Map with bounded concurrency
+const mapped = await ctx.map(items, async (item) => ctx.ask(agent, item), {
+  concurrency: 5,
+  quorum: 3,
+});
+
+// Human-in-the-loop
+const decision = await ctx.awaitHuman({
+  channel: 'slack',
+  prompt: 'Approve this action?',
+});
+
+// Durable checkpoint
+const value = await ctx.checkpoint(async () => expensiveOperation());
+```
+
+### OpenTelemetry Observability
+
+Automatic span emission for every `ctx.*` primitive with cost-per-span attribution. Install `@opentelemetry/api` as an optional peer dependency.
+
+```typescript
+import { defineConfig, AxlRuntime } from 'axl';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+
+const config = defineConfig({
+  telemetry: {
+    enabled: true,
+    serviceName: 'my-app',
+    exporter: new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }),
+  },
+});
+
+const runtime = new AxlRuntime(config);
+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.).
+
+When disabled (default), `NoopSpanManager` provides zero overhead.
+
+```typescript
+import { createSpanManager, NoopSpanManager } from 'axl';
+```
+
+### Memory Primitives
+
+Working memory backed by the existing `StateStore` interface:
+
+```typescript
+// Store and retrieve structured state
+await ctx.remember('user-preferences', { theme: 'dark', lang: 'en' });
+const prefs = await ctx.recall('user-preferences');
+await ctx.forget('user-preferences');
+
+// Scoped to session (default) or global
+await ctx.remember('user-profile', data, { scope: 'global' });
+const profile = await ctx.recall('user-profile', { scope: 'global' });
+```
+
+Semantic recall requires a vector store and embedder configured on the runtime:
+
+```typescript
+import { AxlRuntime, InMemoryVectorStore, OpenAIEmbedder } from 'axl';
+
+const runtime = new AxlRuntime({
+  memory: {
+    vector: new InMemoryVectorStore(),
+    embedder: new OpenAIEmbedder({ model: 'text-embedding-3-small' }),
+  },
+});
+
+// In a workflow:
+const relevant = await ctx.recall('knowledge-base', {
+  query: 'refund policy',
+  topK: 5,
+});
+```
+
+Vector store implementations: `InMemoryVectorStore` (testing), `SqliteVectorStore` (production, requires `better-sqlite3`).
+
+### Agent Guardrails
+
+Input and output validation at the agent boundary:
+
+```typescript
+const safe = agent({
+  model: 'openai:gpt-4o',
+  system: 'You are a helpful assistant.',
+  guardrails: {
+    input: async (prompt, ctx) => {
+      if (containsPII(prompt)) return { block: true, reason: 'PII detected' };
+      return { block: false };
+    },
+    output: async (response, ctx) => {
+      if (isOffTopic(response)) return { block: true, reason: 'Off-topic response' };
+      return { block: false };
+    },
+    onBlock: 'retry',   // 'retry' | 'throw' | (reason, ctx) => fallbackResponse
+    maxRetries: 2,
+  },
+});
+```
+
+When `onBlock` is `'retry'`, the LLM sees the block reason and self-corrects (same pattern as `ctx.verify()`). Throws `GuardrailError` if retries are exhausted or `onBlock` is `'throw'`.
+
+### Session Options
+
+```typescript
+const session = runtime.session('user-123', {
+  history: {
+    maxMessages: 100,   // Trim oldest messages when exceeded
+    summarize: true,    // Auto-summarize trimmed messages
+  },
+  persist: true,        // Save to StateStore (default: true)
+});
+```
+
+`SessionOptions` type:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `history.maxMessages` | `number` | unlimited | Max messages to retain |
+| `history.summarize` | `boolean` | `false` | Summarize trimmed messages |
+| `persist` | `boolean` | `true` | Persist history to StateStore |
+
+### Error Hierarchy
+
+```typescript
+import {
+  AxlError,        // Base class
+  VerifyError,     // Schema validation failed after retries
+  QuorumNotMet,    // Quorum threshold not reached
+  NoConsensus,     // Vote could not reach consensus
+  TimeoutError,    // Operation exceeded timeout
+  MaxTurnsError,   // Agent exceeded max tool-calling turns
+  BudgetExceededError, // Budget limit exceeded
+  GuardrailError,  // Guardrail blocked input or output
+  ToolDenied,      // Agent tried to call unauthorized tool
+} from 'axl';
+```
+
+### State Stores
+
+```typescript
+import { MemoryStore, SQLiteStore, RedisStore } from 'axl';
+
+// In-memory (default)
+const runtime = new AxlRuntime();
+
+// SQLite (requires better-sqlite3)
+const runtime = new AxlRuntime({
+  state: { store: 'sqlite', sqlite: { path: './data/axl.db' } },
+});
+
+// Redis (requires ioredis)
+const runtime = new AxlRuntime({
+  state: { store: 'redis', redis: { url: 'redis://localhost:6379' } },
+});
+```
+
+### Provider URIs
+
+Four built-in providers are supported:
+
+```
+# 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)
+```
+
+## License
+
+[Apache 2.0](../../LICENSE)

package/dist/chunk-EE2BCC37.js

@@ -0,0 +1,79 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/telemetry/span-manager.ts
+var OTelSpanManager = class _OTelSpanManager {
+  tracer;
+  otelApi;
+  tracerProvider;
+  constructor(otelApi, tracer, tracerProvider) {
+    this.otelApi = otelApi;
+    this.tracer = tracer;
+    this.tracerProvider = tracerProvider;
+  }
+  static async create(config) {
+    let otelApi;
+    try {
+      otelApi = await import("@opentelemetry/api");
+    } catch {
+      throw new Error(
+        "@opentelemetry/api is required for telemetry. Install it with: npm install @opentelemetry/api"
+      );
+    }
+    const tracerProvider = config.tracerProvider ?? otelApi.trace.getTracerProvider();
+    const serviceName = config.serviceName ?? "axl";
+    const tracer = tracerProvider.getTracer(serviceName);
+    return new _OTelSpanManager(otelApi, tracer, tracerProvider);
+  }
+  async withSpanAsync(name, attributes, fn) {
+    const otelApi = this.otelApi;
+    return this.tracer.startActiveSpan(name, { attributes }, async (otelSpan) => {
+      const handle = {
+        setAttribute(key, value) {
+          otelSpan.setAttribute(key, value);
+        },
+        addEvent(eventName, attrs) {
+          otelSpan.addEvent(eventName, attrs);
+        },
+        setStatus(code, message) {
+          const statusCode = code === "ok" ? otelApi.SpanStatusCode.OK : otelApi.SpanStatusCode.ERROR;
+          otelSpan.setStatus({ code: statusCode, message });
+        },
+        end() {
+          otelSpan.end();
+        }
+      };
+      try {
+        const result = await fn(handle);
+        handle.setStatus("ok");
+        return result;
+      } catch (err) {
+        handle.setStatus("error", err instanceof Error ? err.message : String(err));
+        throw err;
+      } finally {
+        handle.end();
+      }
+    });
+  }
+  addEventToActiveSpan(name, attributes) {
+    const activeSpan = this.otelApi.trace.getActiveSpan?.();
+    if (activeSpan) {
+      activeSpan.addEvent(name, attributes);
+    }
+  }
+  async shutdown() {
+    if (this.tracerProvider && typeof this.tracerProvider.shutdown === "function") {
+      await this.tracerProvider.shutdown();
+    }
+  }
+};
+
+export {
+  __require,
+  OTelSpanManager
+};
+//# sourceMappingURL=chunk-EE2BCC37.js.map

package/dist/chunk-EE2BCC37.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/telemetry/span-manager.ts"],"sourcesContent":["import type { SpanHandle, SpanManager, TelemetryConfig } from './types.js';\n\n/**\n * OpenTelemetry-backed SpanManager.\n * Dynamically imports @opentelemetry/api to avoid hard dependency.\n */\nexport class OTelSpanManager implements SpanManager {\n  private tracer: any;\n  private otelApi: any;\n  private tracerProvider: any;\n\n  private constructor(otelApi: any, tracer: any, tracerProvider: any) {\n    this.otelApi = otelApi;\n    this.tracer = tracer;\n    this.tracerProvider = tracerProvider;\n  }\n\n  static async create(config: TelemetryConfig): Promise<OTelSpanManager> {\n    let otelApi: any;\n    try {\n      otelApi = await import('@opentelemetry/api');\n    } catch {\n      throw new Error(\n        '@opentelemetry/api is required for telemetry. Install it with: npm install @opentelemetry/api',\n      );\n    }\n\n    const tracerProvider = config.tracerProvider ?? otelApi.trace.getTracerProvider();\n    const serviceName = config.serviceName ?? 'axl';\n    const tracer = (tracerProvider as any).getTracer(serviceName);\n\n    return new OTelSpanManager(otelApi, tracer, tracerProvider);\n  }\n\n  async withSpanAsync<T>(\n    name: string,\n    attributes: Record<string, string | number | boolean>,\n    fn: (span: SpanHandle) => Promise<T>,\n  ): Promise<T> {\n    const otelApi = this.otelApi;\n\n    return this.tracer.startActiveSpan(name, { attributes }, async (otelSpan: any) => {\n      const handle: SpanHandle = {\n        setAttribute(key: string, value: string | number | boolean) {\n          otelSpan.setAttribute(key, value);\n        },\n        addEvent(eventName: string, attrs?: Record<string, string | number | boolean>) {\n          otelSpan.addEvent(eventName, attrs);\n        },\n        setStatus(code: 'ok' | 'error', message?: string) {\n          const statusCode =\n            code === 'ok' ? otelApi.SpanStatusCode.OK : otelApi.SpanStatusCode.ERROR;\n          otelSpan.setStatus({ code: statusCode, message });\n        },\n        end() {\n          otelSpan.end();\n        },\n      };\n\n      try {\n        const result = await fn(handle);\n        handle.setStatus('ok');\n        return result;\n      } catch (err) {\n        handle.setStatus('error', err instanceof Error ? err.message : String(err));\n        throw err;\n      } finally {\n        handle.end();\n      }\n    });\n  }\n\n  addEventToActiveSpan(name: string, attributes?: Record<string, string | number | boolean>): void {\n    const activeSpan = this.otelApi.trace.getActiveSpan?.();\n    if (activeSpan) {\n      activeSpan.addEvent(name, attributes);\n    }\n  }\n\n  async shutdown(): Promise<void> {\n    if (this.tracerProvider && typeof this.tracerProvider.shutdown === 'function') {\n      await this.tracerProvider.shutdown();\n    }\n  }\n}\n"],"mappings":";;;;;;;;AAMO,IAAM,kBAAN,MAAM,iBAAuC;AAAA,EAC1C;AAAA,EACA;AAAA,EACA;AAAA,EAEA,YAAY,SAAc,QAAa,gBAAqB;AAClE,SAAK,UAAU;AACf,SAAK,SAAS;AACd,SAAK,iBAAiB;AAAA,EACxB;AAAA,EAEA,aAAa,OAAO,QAAmD;AACrE,QAAI;AACJ,QAAI;AACF,gBAAU,MAAM,OAAO,oBAAoB;AAAA,IAC7C,QAAQ;AACN,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAEA,UAAM,iBAAiB,OAAO,kBAAkB,QAAQ,MAAM,kBAAkB;AAChF,UAAM,cAAc,OAAO,eAAe;AAC1C,UAAM,SAAU,eAAuB,UAAU,WAAW;AAE5D,WAAO,IAAI,iBAAgB,SAAS,QAAQ,cAAc;AAAA,EAC5D;AAAA,EAEA,MAAM,cACJ,MACA,YACA,IACY;AACZ,UAAM,UAAU,KAAK;AAErB,WAAO,KAAK,OAAO,gBAAgB,MAAM,EAAE,WAAW,GAAG,OAAO,aAAkB;AAChF,YAAM,SAAqB;AAAA,QACzB,aAAa,KAAa,OAAkC;AAC1D,mBAAS,aAAa,KAAK,KAAK;AAAA,QAClC;AAAA,QACA,SAAS,WAAmB,OAAmD;AAC7E,mBAAS,SAAS,WAAW,KAAK;AAAA,QACpC;AAAA,QACA,UAAU,MAAsB,SAAkB;AAChD,gBAAM,aACJ,SAAS,OAAO,QAAQ,eAAe,KAAK,QAAQ,eAAe;AACrE,mBAAS,UAAU,EAAE,MAAM,YAAY,QAAQ,CAAC;AAAA,QAClD;AAAA,QACA,MAAM;AACJ,mBAAS,IAAI;AAAA,QACf;AAAA,MACF;AAEA,UAAI;AACF,cAAM,SAAS,MAAM,GAAG,MAAM;AAC9B,eAAO,UAAU,IAAI;AACrB,eAAO;AAAA,MACT,SAAS,KAAK;AACZ,eAAO,UAAU,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAC1E,cAAM;AAAA,MACR,UAAE;AACA,eAAO,IAAI;AAAA,MACb;AAAA,IACF,CAAC;AAAA,EACH;AAAA,EAEA,qBAAqB,MAAc,YAA8D;AAC/F,UAAM,aAAa,KAAK,QAAQ,MAAM,gBAAgB;AACtD,QAAI,YAAY;AACd,iBAAW,SAAS,MAAM,UAAU;AAAA,IACtC;AAAA,EACF;AAAA,EAEA,MAAM,WAA0B;AAC9B,QAAI,KAAK,kBAAkB,OAAO,KAAK,eAAe,aAAa,YAAY;AAC7E,YAAM,KAAK,eAAe,SAAS;AAAA,IACrC;AAAA,EACF;AACF;","names":[]}