@neutrome/open-ai-router 0.1.18 → 0.2.0

package/src/router/execution-runtime.ts

@@ -0,0 +1,632 @@
+import { cloneProgram, validateProgram } from "@neutrome/lil-engine";
+import type { Program, ValidationMode } from "@neutrome/lil-engine";
+import type { ExecutorContext } from "@neutrome/lilsdk-ts";
+import { createAuditEvent } from "./audit.ts";
+import { ExecutionError, isExecutionError } from "./errors.ts";
+import { executionTargetAuditRef, executionTargetId } from "./targets.ts";
+import type {
+  AuditEvent,
+  ExecutionRuntime,
+  ExecutionRuntimeOptions,
+  ExecutionTarget,
+  Executor,
+  InvokeOptions,
+  ProgramTransform,
+  ProviderInvocationContext,
+  ProviderInvoker,
+} from "./execution-types.ts";
+
+const DEFAULT_MAX_DEPTH = 8;
+
+export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): ExecutionRuntime {
+  let requestCounter = 0;
+  let executionCounter = 0;
+
+  const requestIdFactory = options.requestIdFactory ?? (() => `req_${++requestCounter}`);
+  const executionIdFactory = options.executionIdFactory ?? (() => `exec_${++executionCounter}`);
+  const observe = options.observe ?? (() => {});
+  const fallbackSignal = options.signal ?? new AbortController().signal;
+  const executorImplementations = new Map(Object.entries(options.executorImplementations ?? {}));
+  const transforms = new Map(Object.entries(options.transforms ?? {}));
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const validatePrograms = options.validatePrograms ?? true;
+
+  return {
+    async execute(request, invokeOptions) {
+      return executeTarget(cloneProgram(request), invokeOptions, 0);
+    },
+    async *stream(request, invokeOptions) {
+      yield* streamTarget(cloneProgram(request), invokeOptions, 0);
+    },
+  };
+
+  async function executeTarget(
+    request: ReturnType<typeof cloneProgram>,
+    invokeOptions: InvokeOptions = {},
+    depth: number,
+  ) {
+    throwIfRecursionExceeded(depth);
+    const requestId = invokeOptions.requestId ?? requestIdFactory();
+    const executionId = invokeOptions.executionId ?? executionIdFactory();
+    const parentExecutionId = invokeOptions.parentExecutionId;
+    const signal = fallbackSignal;
+    const target = resolveTargetOrThrow(request, invokeOptions);
+
+    ensureActiveSignal(signal, "request", target, depth);
+    validateProgramOrThrow(request, {
+      stage: "request",
+      mode: "program",
+      requestId,
+      executionId,
+      parentExecutionId,
+      target,
+      depth,
+      emitSuccess: true,
+    });
+
+    const transformed = applyTransforms(
+      request,
+      target,
+      requestId,
+      executionId,
+      parentExecutionId,
+      signal,
+      depth,
+    );
+
+    if (target.kind === "executor") {
+      const executor = await getExecutorOrThrow(target.executorId);
+      observe(createAuditEvent({
+        kind: "executor.started",
+        requestId,
+        executionId,
+        target: executionTargetAuditRef(target),
+        data: {
+          executorId: target.executorId,
+          alias: target.alias,
+          transforms: target.transforms ?? [],
+          depth,
+          maxDepth,
+        },
+        ...withParentExecutionId(parentExecutionId),
+      }));
+
+      try {
+        const result = await executor.execute(
+          transformed,
+          createExecutionContext(requestId, executionId, parentExecutionId, signal, depth),
+        );
+        validateProgramOrThrow(result, {
+          stage: "executor_result",
+          mode: "program",
+          requestId,
+          executionId,
+          parentExecutionId,
+          target,
+          depth,
+          emitSuccess: true,
+        });
+        observe(createAuditEvent({
+          kind: "executor.finished",
+          requestId,
+          executionId,
+          target: executionTargetAuditRef(target),
+          ...withParentExecutionId(parentExecutionId),
+        }));
+        return result;
+      } catch (error) {
+        const normalized = normalizeExecutionError(error, "executor", "executor_invoke", target, depth);
+        observeExecutionError(normalized, requestId, executionId, parentExecutionId, target, depth);
+        throw normalized;
+      }
+    }
+
+    const providerInvoker = getProviderInvokerOrThrow();
+    const providerCtx = createProviderInvocationContext(
+      requestId,
+      executionId,
+      parentExecutionId,
+      target,
+      signal,
+    );
+
+    observe(createAuditEvent({
+      kind: "provider.started",
+      requestId,
+      executionId,
+      target: executionTargetAuditRef(target),
+        data: {
+          model: target.model,
+          provider: target.provider ?? "",
+          transforms: target.transforms ?? [],
+          depth,
+          maxDepth,
+      },
+      ...withParentExecutionId(parentExecutionId),
+    }));
+
+    try {
+      const result = await providerInvoker.execute(transformed, providerCtx);
+      validateProgramOrThrow(result, {
+        stage: "provider_result",
+        mode: "program",
+        requestId,
+        executionId,
+        parentExecutionId,
+        target,
+        depth,
+        emitSuccess: true,
+      });
+      observe(createAuditEvent({
+        kind: "provider.finished",
+        requestId,
+        executionId,
+        target: executionTargetAuditRef(target),
+        ...withParentExecutionId(parentExecutionId),
+      }));
+      return result;
+    } catch (error) {
+      const normalized = normalizeExecutionError(error, "provider", "provider_invoke", target, depth);
+      observeExecutionError(normalized, requestId, executionId, parentExecutionId, target, depth);
+      throw normalized;
+    }
+  }
+
+  async function* streamTarget(
+    request: ReturnType<typeof cloneProgram>,
+    invokeOptions: InvokeOptions = {},
+    depth: number,
+  ) {
+    throwIfRecursionExceeded(depth);
+    const requestId = invokeOptions.requestId ?? requestIdFactory();
+    const executionId = invokeOptions.executionId ?? executionIdFactory();
+    const parentExecutionId = invokeOptions.parentExecutionId;
+    const signal = fallbackSignal;
+    const target = resolveTargetOrThrow(request, invokeOptions);
+
+    ensureActiveSignal(signal, "request", target, depth);
+    validateProgramOrThrow(request, {
+      stage: "request",
+      mode: "program",
+      requestId,
+      executionId,
+      parentExecutionId,
+      target,
+      depth,
+      emitSuccess: true,
+    });
+
+    const transformed = applyTransforms(
+      request,
+      target,
+      requestId,
+      executionId,
+      parentExecutionId,
+      signal,
+      depth,
+    );
+
+    if (target.kind === "executor") {
+      const executor = await getExecutorOrThrow(target.executorId);
+      observe(createAuditEvent({
+        kind: "executor.stream_started",
+        requestId,
+        executionId,
+        target: executionTargetAuditRef(target),
+        data: {
+          executorId: target.executorId,
+          alias: target.alias,
+          transforms: target.transforms ?? [],
+          depth,
+          maxDepth,
+        },
+        ...withParentExecutionId(parentExecutionId),
+      }));
+
+      try {
+        for await (const chunk of executor.stream(
+          transformed,
+          createExecutionContext(requestId, executionId, parentExecutionId, signal, depth),
+        )) {
+          validateProgramOrThrow(chunk, {
+            stage: "stream_chunk",
+            mode: "stream_chunk",
+            requestId,
+            executionId,
+            parentExecutionId,
+            target,
+            depth,
+            emitSuccess: false,
+          });
+          yield chunk;
+        }
+        observe(createAuditEvent({
+          kind: "executor.stream_finished",
+          requestId,
+          executionId,
+          target: executionTargetAuditRef(target),
+          ...withParentExecutionId(parentExecutionId),
+        }));
+        return;
+      } catch (error) {
+        const normalized = normalizeExecutionError(error, "stream", "stream_chunk", target, depth);
+        observeExecutionError(normalized, requestId, executionId, parentExecutionId, target, depth);
+        throw normalized;
+      }
+    }
+
+    const providerInvoker = getProviderInvokerOrThrow();
+    const providerCtx = createProviderInvocationContext(
+      requestId,
+      executionId,
+      parentExecutionId,
+      target,
+      signal,
+    );
+
+    observe(createAuditEvent({
+      kind: "provider.stream_started",
+      requestId,
+      executionId,
+      target: executionTargetAuditRef(target),
+        data: {
+          model: target.model,
+          provider: target.provider ?? "",
+          transforms: target.transforms ?? [],
+          depth,
+          maxDepth,
+      },
+      ...withParentExecutionId(parentExecutionId),
+    }));
+
+    try {
+      for await (const chunk of providerInvoker.stream(transformed, providerCtx)) {
+        validateProgramOrThrow(chunk, {
+          stage: "stream_chunk",
+          mode: "stream_chunk",
+          requestId,
+          executionId,
+          parentExecutionId,
+          target,
+          depth,
+          emitSuccess: false,
+        });
+        yield chunk;
+      }
+      observe(createAuditEvent({
+        kind: "provider.stream_finished",
+        requestId,
+        executionId,
+        target: executionTargetAuditRef(target),
+        ...withParentExecutionId(parentExecutionId),
+      }));
+    } catch (error) {
+      const normalized = normalizeExecutionError(error, "stream", "stream_chunk", target, depth);
+      observeExecutionError(normalized, requestId, executionId, parentExecutionId, target, depth);
+      throw normalized;
+    }
+  }
+
+  function createExecutionContext(
+    requestId: string,
+    executionId: string,
+    parentExecutionId: string | undefined,
+    signal: AbortSignal,
+    depth: number,
+  ): ExecutorContext {
+    return {
+      requestId,
+      executionId,
+      ...(parentExecutionId ? { parentExecutionId } : {}),
+      async invoke(request, invokeOptions = {}) {
+        return executeTarget(cloneProgram(request), {
+          ...invokeOptions,
+          requestId,
+          parentExecutionId: executionId,
+        }, depth + 1);
+      },
+      async *invokeStream(request, invokeOptions = {}) {
+        yield* streamTarget(cloneProgram(request), {
+          ...invokeOptions,
+          requestId,
+          parentExecutionId: executionId,
+        }, depth + 1);
+      },
+      observe,
+      signal,
+    };
+  }
+
+  function applyTransforms(
+    program: ReturnType<typeof cloneProgram>,
+    target: ExecutionTarget,
+    requestId: string,
+    executionId: string,
+    parentExecutionId: string | undefined,
+    signal: AbortSignal,
+    depth: number,
+  ) {
+    let current = cloneProgram(program);
+    for (const transformName of target.transforms ?? []) {
+      const transform = transforms.get(transformName);
+      if (!transform) {
+        throw new ExecutionError(
+          "transform",
+          `Unknown transform: ${transformName}`,
+          {
+            stage: "transform",
+            details: { transform: transformName, target: executionTargetId(target), depth, maxDepth },
+          },
+        );
+      }
+      try {
+        current = transform.apply(current, { observe, signal });
+      } catch (error) {
+        throw new ExecutionError(
+          "transform",
+          `Transform ${transform.name} failed`,
+          {
+            stage: "transform",
+            details: { transform: transform.name, target: executionTargetId(target), depth, maxDepth },
+            cause: error,
+          },
+        );
+      }
+      validateProgramOrThrow(current, {
+        stage: "transform_output",
+        mode: "program",
+        requestId,
+        executionId,
+        parentExecutionId,
+        target,
+        depth,
+        emitSuccess: true,
+      });
+      observe(createAuditEvent({
+        kind: "transform.applied",
+        requestId,
+        executionId,
+        target: executionTargetAuditRef(target),
+        data: {
+          transform: transform.name,
+          target: executionTargetId(target),
+          depth,
+          maxDepth,
+        },
+        ...withParentExecutionId(parentExecutionId),
+      }));
+    }
+    return current;
+  }
+
+  function resolveTargetOrThrow(
+    request: ReturnType<typeof cloneProgram>,
+    invokeOptions: InvokeOptions,
+  ): ExecutionTarget {
+    if (invokeOptions.target) {
+      return invokeOptions.target;
+    }
+    if (options.resolveTarget) {
+      try {
+        return options.resolveTarget(request, invokeOptions);
+      } catch (error) {
+        throw new ExecutionError(
+          "resolution",
+          error instanceof Error ? error.message : "Execution target resolution failed",
+          {
+            stage: "target_resolution",
+            cause: error,
+          },
+        );
+      }
+    }
+    throw new ExecutionError("resolution", "No execution target specified", {
+      stage: "target_resolution",
+    });
+  }
+
+  async function getExecutorOrThrow(name: string): Promise<Executor> {
+    const cached = executorImplementations.get(name);
+    if (cached) {
+      return cached;
+    }
+
+    const resolved = await options.resolveExecutor?.(name);
+    if (resolved) {
+      executorImplementations.set(name, resolved);
+      return resolved;
+    }
+
+    const executor = executorImplementations.get(name);
+    if (!executor) {
+      throw new ExecutionError("resolution", `Unknown executor: ${name}`, {
+        stage: "target_resolution",
+      });
+    }
+    return executor;
+  }
+
+  function getProviderInvokerOrThrow(): ProviderInvoker {
+    if (!options.providerInvoker) {
+      throw new ExecutionError("provider", "No provider invoker configured", {
+        stage: "provider_invoke",
+      });
+    }
+    return options.providerInvoker;
+  }
+
+  function observeExecutionError(
+    error: ExecutionError,
+    requestId: string,
+    executionId: string,
+    parentExecutionId: string | undefined,
+    target: ExecutionTarget,
+    depth: number,
+  ): void {
+    observe(createAuditEvent({
+      kind: "execution.failed",
+      requestId,
+      executionId,
+      target: executionTargetAuditRef(target),
+      errorKind: error.kind,
+      data: {
+        message: error.message,
+        stage: error.stage,
+        depth,
+        maxDepth,
+        ...(error.details ?? {}),
+      },
+      ...withParentExecutionId(parentExecutionId),
+    }));
+  }
+
+  function createProviderInvocationContext(
+    requestId: string,
+    executionId: string,
+    parentExecutionId: string | undefined,
+    target: Extract<ExecutionTarget, { kind: "provider" }>,
+    signal: AbortSignal,
+  ): ProviderInvocationContext {
+    return {
+      requestId,
+      executionId,
+      target,
+      signal,
+      observe,
+      ...withParentExecutionId(parentExecutionId),
+    };
+  }
+
+  function withParentExecutionId(parentExecutionId: string | undefined): {
+    parentExecutionId?: string;
+  } {
+    if (parentExecutionId === undefined) {
+      return {};
+    }
+    return { parentExecutionId };
+  }
+
+  function throwIfRecursionExceeded(depth: number): void {
+    if (depth <= maxDepth) {
+      return;
+    }
+    throw new ExecutionError(
+      "recursion_limit",
+      `Execution recursion depth ${depth} exceeds maxDepth ${maxDepth}`,
+      {
+        stage: "target_resolution",
+        details: { depth, maxDepth },
+      },
+    );
+  }
+
+  function validateProgramOrThrow(
+    program: Program,
+    context: {
+      stage: "request" | "transform_output" | "provider_result" | "executor_result" | "stream_chunk";
+      mode: ValidationMode;
+      requestId: string;
+      executionId: string;
+      parentExecutionId: string | undefined;
+      target: ExecutionTarget;
+      depth: number;
+      emitSuccess: boolean;
+    },
+  ): void {
+    if (!validatePrograms) {
+      return;
+    }
+
+    const result = validateProgram(program, { mode: context.mode });
+    if (!result.ok) {
+      throw new ExecutionError(
+        "validation",
+        `Program validation failed during ${context.stage}`,
+        {
+          stage: context.stage,
+          details: {
+            issues: result.issues,
+            depth: context.depth,
+            maxDepth,
+            target: executionTargetId(context.target),
+          },
+        },
+      );
+    }
+
+    if (context.emitSuccess) {
+      observe(createAuditEvent({
+        kind: "program.validated",
+        requestId: context.requestId,
+        executionId: context.executionId,
+        target: executionTargetAuditRef(context.target),
+        data: {
+          stage: context.stage,
+          mode: context.mode,
+          issues: 0,
+          depth: context.depth,
+          maxDepth,
+        },
+        ...withParentExecutionId(context.parentExecutionId),
+      }));
+    }
+  }
+
+  function ensureActiveSignal(
+    signal: AbortSignal,
+    stage: "request",
+    target: ExecutionTarget,
+    depth: number,
+  ): void {
+    if (!signal.aborted) {
+      return;
+    }
+    throw new ExecutionError(
+      "cancellation",
+      "Execution aborted",
+      {
+        stage,
+        details: { depth, maxDepth, target: executionTargetId(target) },
+        cause: signal.reason,
+      },
+    );
+  }
+
+  function normalizeExecutionError(
+    error: unknown,
+    fallbackKind: "provider" | "executor" | "stream",
+    fallbackStage: "provider_invoke" | "executor_invoke" | "stream_chunk",
+    target: ExecutionTarget,
+    depth: number,
+  ): ExecutionError {
+    if (isExecutionError(error)) {
+      return error;
+    }
+    if (isAbortLike(error)) {
+      return new ExecutionError(
+        "cancellation",
+        "Execution aborted",
+        {
+          stage: fallbackStage,
+          details: { depth, maxDepth, target: executionTargetId(target) },
+          cause: error,
+        },
+      );
+    }
+    return new ExecutionError(
+      fallbackKind,
+      error instanceof Error ? error.message : String(error),
+      {
+        stage: fallbackStage,
+        details: { depth, maxDepth, target: executionTargetId(target) },
+        cause: error,
+      },
+    );
+  }
+
+  function isAbortLike(error: unknown): boolean {
+    return error instanceof DOMException
+      ? error.name === "AbortError"
+      : error instanceof Error && error.name === "AbortError";
+  }
+}

package/src/router/execution-types.ts

@@ -0,0 +1,80 @@
+import type { Program, ValidationIssue } from "@neutrome/lil-engine";
+import type {
+  ExecutionTarget,
+  Executor,
+  InvokeOptions,
+  ProgramTransform,
+} from "@neutrome/lilsdk-ts";
+import type {
+  ExecutionErrorDetails,
+  ExecutionErrorKind,
+  ExecutionErrorStage,
+} from "./errors.ts";
+
+export type AuditEvent = {
+  kind: string;
+  requestId: string;
+  executionId: string;
+  timestamp: string;
+  parentExecutionId?: string;
+  target?: { kind: "provider" | "executor"; id: string };
+  errorKind?: string;
+  data?: Record<string, unknown>;
+};
+
+export type AuditEventInput = Omit<AuditEvent, "timestamp"> & {
+  timestamp?: string;
+};
+
+export type ProviderInvocationContext = {
+  requestId: string;
+  executionId: string;
+  parentExecutionId?: string;
+  target: Extract<ExecutionTarget, { kind: "provider" }>;
+  signal: AbortSignal;
+  observe(event: AuditEvent): void;
+};
+
+export type ProviderInvoker = {
+  execute(request: Program, ctx: ProviderInvocationContext): Promise<Program>;
+  stream(request: Program, ctx: ProviderInvocationContext): AsyncIterable<Program>;
+};
+
+export type ResolveTarget = (
+  request: Program,
+  options?: InvokeOptions,
+) => ExecutionTarget;
+
+export type ResolveExecutor = (
+  name: string,
+) => Executor | Promise<Executor | null> | null;
+
+export type ExecutionRuntimeOptions = {
+  executorImplementations?: Readonly<Record<string, Executor>>;
+  resolveExecutor?: ResolveExecutor;
+  transforms?: Readonly<Record<string, ProgramTransform>>;
+  providerInvoker?: ProviderInvoker;
+  resolveTarget?: ResolveTarget;
+  observe?: (event: AuditEvent) => void;
+  signal?: AbortSignal;
+  requestIdFactory?: () => string;
+  executionIdFactory?: () => string;
+  maxDepth?: number;
+  validatePrograms?: boolean;
+};
+
+export type ExecutionRuntime = {
+  execute(request: Program, options?: InvokeOptions): Promise<Program>;
+  stream(request: Program, options?: InvokeOptions): AsyncIterable<Program>;
+};
+
+export type {
+  ExecutionErrorDetails,
+  ExecutionErrorKind,
+  ExecutionErrorStage,
+  ExecutionTarget,
+  Executor,
+  InvokeOptions,
+  ProgramTransform,
+  ValidationIssue,
+};