@neutrome/open-ai-router 0.4.2 → 0.5.0

package/src/router/execution-events.ts

@@ -0,0 +1,39 @@
+import { createExecutionEvent } from "@neutrome/lilsdk-ts";
+import type { ExecutionEvent } from "@neutrome/lilsdk-ts";
+
+type TimedExecutionInput = {
+  observe?: ((event: ExecutionEvent) => void) | undefined;
+  kind: string;
+  requestId: string;
+  executionId: string;
+  parentExecutionId?: string | undefined;
+  startedAtMs: number;
+  finishedAtMs?: number | undefined;
+  data?: Record<string, unknown> | undefined;
+};
+
+export function observeTimedExecution(input: TimedExecutionInput): void {
+  if (!input.observe) return;
+  const data: Record<string, unknown> = {
+    ...(input.data ?? {}),
+    startedAt: new Date(input.startedAtMs).toISOString(),
+  };
+  if (input.finishedAtMs !== undefined) {
+    data.finishedAt = new Date(input.finishedAtMs).toISOString();
+    data.durationMs = Math.max(0, input.finishedAtMs - input.startedAtMs);
+  }
+  input.observe(
+    createExecutionEvent({
+      kind: input.kind,
+      requestId: input.requestId,
+      executionId: input.executionId,
+      ...(input.parentExecutionId
+        ? { parentExecutionId: input.parentExecutionId }
+        : {}),
+      timestamp: new Date(
+        input.finishedAtMs ?? input.startedAtMs,
+      ).toISOString(),
+      data,
+    }),
+  );
+}

package/src/router/execution-invocation.ts

@@ -0,0 +1,144 @@
+import type { Program, ValidationMode } from "@neutrome/lil-engine";
+import type { ExecutorContext } from "@neutrome/lilsdk-ts";
+import {
+  finishInvocation,
+  observeExecutionError,
+  startInvocation,
+  type ExecutionObservation,
+} from "./execution-observation.ts";
+import { normalizeExecutionError } from "./execution-resolution.ts";
+import type {
+  ExecutionTarget,
+  Executor,
+  ProviderInvocationContext,
+  ProviderInvoker,
+} from "./execution-types.ts";
+
+type InvocationIdentity = {
+  requestId: string;
+  executionId: string;
+  parentExecutionId: string | undefined;
+  target: ExecutionTarget;
+  depth: number;
+};
+
+export type InvocationOptions = {
+  program: Program;
+  identity: InvocationIdentity;
+  signal: AbortSignal;
+  maxDepth: number;
+  observe: ExecutionObservation;
+  executor: Executor | undefined;
+  providerInvoker: ProviderInvoker | undefined;
+  createExecutorContext(): ExecutorContext;
+  createProviderContext(
+    target: Extract<ExecutionTarget, { kind: "provider" }>,
+  ): ProviderInvocationContext;
+  validate(
+    program: Program,
+    stage: "provider_result" | "executor_result" | "stream_chunk",
+    mode: ValidationMode,
+  ): void;
+};
+
+export async function invokeExecution(
+  options: InvocationOptions,
+): Promise<Program> {
+  const primitive = invocationPrimitive(options);
+  const timing = startInvocation(
+    options.identity,
+    options.maxDepth,
+    false,
+    options.observe,
+  );
+  try {
+    const result = await primitive.execute(options.program);
+    options.validate(result, primitive.resultStage, "program");
+    finishInvocation(options.identity, timing, false, options.observe);
+    return result;
+  } catch (error) {
+    throw observedFailure(
+      options,
+      error,
+      primitive.failureKind,
+      primitive.stage,
+    );
+  }
+}
+
+export async function* streamExecution(
+  options: InvocationOptions,
+): AsyncGenerator<Program> {
+  const primitive = invocationPrimitive(options);
+  const timing = startInvocation(
+    options.identity,
+    options.maxDepth,
+    true,
+    options.observe,
+  );
+  try {
+    for await (const chunk of primitive.stream(options.program)) {
+      options.validate(chunk, "stream_chunk", "stream_chunk");
+      yield chunk;
+    }
+    finishInvocation(options.identity, timing, true, options.observe);
+  } catch (error) {
+    throw observedFailure(options, error, "stream", "stream_chunk");
+  }
+}
+
+function invocationPrimitive(options: InvocationOptions): {
+  execute(program: Program): Promise<Program>;
+  stream(program: Program): AsyncIterable<Program>;
+  resultStage: "provider_result" | "executor_result";
+  failureKind: "provider" | "executor";
+  stage: "provider_invoke" | "executor_invoke";
+} {
+  if (options.identity.target.kind === "executor") {
+    const executor = options.executor;
+    if (!executor) throw new Error("Missing executor invocation primitive");
+    const context = options.createExecutorContext();
+    return {
+      execute: (program) => executor.execute(program, context),
+      stream: (program) => executor.stream(program, context),
+      resultStage: "executor_result",
+      failureKind: "executor",
+      stage: "executor_invoke",
+    };
+  }
+
+  const providerInvoker = options.providerInvoker;
+  if (!providerInvoker)
+    throw new Error("Missing provider invocation primitive");
+  const context = options.createProviderContext(options.identity.target);
+  return {
+    execute: (program) => providerInvoker.execute(program, context),
+    stream: (program) => providerInvoker.stream(program, context),
+    resultStage: "provider_result",
+    failureKind: "provider",
+    stage: "provider_invoke",
+  };
+}
+
+function observedFailure(
+  options: InvocationOptions,
+  cause: unknown,
+  fallbackKind: "provider" | "executor" | "stream",
+  stage: "provider_invoke" | "executor_invoke" | "stream_chunk",
+) {
+  const error = normalizeExecutionError(
+    cause,
+    fallbackKind,
+    stage,
+    options.identity.target,
+    options.identity.depth,
+    options.maxDepth,
+  );
+  observeExecutionError(
+    error,
+    options.identity,
+    options.maxDepth,
+    options.observe,
+  );
+  return error;
+}

package/src/router/execution-observation.ts

@@ -0,0 +1,161 @@
+import { validateProgram } from "@neutrome/lil-engine";
+import type { Program, ValidationMode } from "@neutrome/lil-engine";
+import { createExecutionEvent } from "@neutrome/lilsdk-ts";
+import type { ExecutionEvent } from "@neutrome/lilsdk-ts";
+import { ExecutionError } from "./errors.ts";
+import { executionTargetAuditRef, executionTargetId } from "./targets.ts";
+import type { ExecutionTarget } from "./execution-types.ts";
+
+export type ExecutionObservation = (event: ExecutionEvent) => void;
+
+type ExecutionIdentity = {
+  requestId: string;
+  executionId: string;
+  parentExecutionId: string | undefined;
+  target: ExecutionTarget;
+  depth: number;
+};
+
+export function startInvocation(
+  identity: ExecutionIdentity,
+  maxDepth: number,
+  streaming: boolean,
+  observe: ExecutionObservation,
+): { startedMs: number; startedAt: string } {
+  const startedMs = Date.now();
+  const startedAt = new Date(startedMs).toISOString();
+  const { target } = identity;
+  observe(
+    createExecutionEvent({
+      kind: `${target.kind === "provider" ? "provider" : "executor"}.${streaming ? "stream_started" : "started"}`,
+      requestId: identity.requestId,
+      executionId: identity.executionId,
+      target: executionTargetAuditRef(target),
+      data: {
+        ...(target.kind === "provider"
+          ? { provider: target.provider ?? "", model: target.model }
+          : { executorId: target.executorId, alias: target.alias }),
+        transforms: target.transforms ?? [],
+        depth: identity.depth,
+        maxDepth,
+        startedAt,
+      },
+      ...parent(identity.parentExecutionId),
+    }),
+  );
+  return { startedMs, startedAt };
+}
+
+export function finishInvocation(
+  identity: ExecutionIdentity,
+  timing: { startedMs: number; startedAt: string },
+  streaming: boolean,
+  observe: ExecutionObservation,
+): void {
+  const finishedMs = Date.now();
+  const { target } = identity;
+  observe(
+    createExecutionEvent({
+      kind: `${target.kind === "provider" ? "provider" : "executor"}.${streaming ? "stream_finished" : "finished"}`,
+      requestId: identity.requestId,
+      executionId: identity.executionId,
+      target: executionTargetAuditRef(target),
+      data: {
+        ...(target.kind === "provider"
+          ? { provider: target.provider ?? "", model: target.model }
+          : {}),
+        startedAt: timing.startedAt,
+        finishedAt: new Date(finishedMs).toISOString(),
+        durationMs: finishedMs - timing.startedMs,
+      },
+      ...parent(identity.parentExecutionId),
+    }),
+  );
+}
+
+export function observeExecutionError(
+  error: ExecutionError,
+  identity: ExecutionIdentity,
+  maxDepth: number,
+  observe: ExecutionObservation,
+): void {
+  observe(
+    createExecutionEvent({
+      kind: "execution.failed",
+      requestId: identity.requestId,
+      executionId: identity.executionId,
+      target: executionTargetAuditRef(identity.target),
+      errorKind: error.kind,
+      data: {
+        message: error.message,
+        stage: error.stage,
+        depth: identity.depth,
+        maxDepth,
+        ...(error.details ?? {}),
+      },
+      ...parent(identity.parentExecutionId),
+    }),
+  );
+}
+
+export function validateProgramOrThrow(
+  program: Program,
+  context: ExecutionIdentity & {
+    stage:
+      | "request"
+      | "transform_output"
+      | "provider_result"
+      | "executor_result"
+      | "stream_chunk";
+    mode: ValidationMode;
+    emitSuccess: boolean;
+  },
+  options: {
+    enabled: boolean;
+    maxDepth: number;
+    observe: ExecutionObservation;
+  },
+): void {
+  if (!options.enabled) 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: options.maxDepth,
+          target: executionTargetId(context.target),
+        },
+      },
+    );
+  }
+  if (!context.emitSuccess) return;
+
+  options.observe(
+    createExecutionEvent({
+      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: options.maxDepth,
+      },
+      ...parent(context.parentExecutionId),
+    }),
+  );
+}
+
+function parent(parentExecutionId: string | undefined): {
+  parentExecutionId?: string;
+} {
+  return parentExecutionId === undefined ? {} : { parentExecutionId };
+}

package/src/router/execution-resolution.ts

@@ -0,0 +1,120 @@
+import type { Program } from "@neutrome/lil-engine";
+import { ExecutionError, isExecutionError } from "./errors.ts";
+import { executionTargetId } from "./targets.ts";
+import type {
+  ExecutionRuntimeOptions,
+  ExecutionTarget,
+  Executor,
+  InvokeOptions,
+  ProviderInvoker,
+} from "./execution-types.ts";
+
+export function resolveTargetOrThrow(
+  options: ExecutionRuntimeOptions,
+  request: Program,
+  invokeOptions: InvokeOptions,
+): ExecutionTarget {
+  if (invokeOptions.target) return invokeOptions.target;
+  if (options.resolveTarget) {
+    try {
+      return options.resolveTarget(request, invokeOptions);
+    } catch (cause) {
+      throw new ExecutionError(
+        "resolution",
+        cause instanceof Error
+          ? cause.message
+          : "Execution target resolution failed",
+        { stage: "target_resolution", cause },
+      );
+    }
+  }
+  throw new ExecutionError("resolution", "No execution target specified", {
+    stage: "target_resolution",
+  });
+}
+
+export async function resolveExecutorOrThrow(
+  options: ExecutionRuntimeOptions,
+  executors: Map<string, Executor>,
+  name: string,
+): Promise<Executor> {
+  const cached = executors.get(name);
+  if (cached) return cached;
+
+  const resolved = await options.resolveExecutor?.(name);
+  if (resolved) {
+    executors.set(name, resolved);
+    return resolved;
+  }
+  throw new ExecutionError("resolution", `Unknown executor: ${name}`, {
+    stage: "target_resolution",
+  });
+}
+
+export function providerInvokerOrThrow(
+  options: ExecutionRuntimeOptions,
+): ProviderInvoker {
+  if (options.providerInvoker) return options.providerInvoker;
+  throw new ExecutionError("provider", "No provider invoker configured", {
+    stage: "provider_invoke",
+  });
+}
+
+export function throwIfRecursionExceeded(
+  depth: number,
+  maxDepth: number,
+): void {
+  if (depth <= maxDepth) return;
+  throw new ExecutionError(
+    "recursion_limit",
+    `Execution recursion depth ${depth} exceeds maxDepth ${maxDepth}`,
+    { stage: "target_resolution", details: { depth, maxDepth } },
+  );
+}
+
+export function ensureActiveSignal(
+  signal: AbortSignal,
+  target: ExecutionTarget,
+  depth: number,
+  maxDepth: number,
+): void {
+  if (!signal.aborted) return;
+  throw new ExecutionError("cancellation", "Execution aborted", {
+    stage: "request",
+    details: { depth, maxDepth, target: executionTargetId(target) },
+    cause: signal.reason,
+  });
+}
+
+export function normalizeExecutionError(
+  error: unknown,
+  fallbackKind: "provider" | "executor" | "stream",
+  fallbackStage: "provider_invoke" | "executor_invoke" | "stream_chunk",
+  target: ExecutionTarget,
+  depth: number,
+  maxDepth: 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";
+}