@hoplogic/engine 0.1.0

package/dist/index.js

@@ -0,0 +1,639 @@
+import { detectSerializationResidue, parseResult, repairValue, parseFullSpec, validateSpec } from '@hoplogic/spec';
+import { z } from 'zod';
+
+// src/execution-types.ts
+function createEmptyStats() {
+  return {
+    total_steps: 0,
+    completed_steps: 0,
+    failed_steps: 0,
+    total_retries: 0,
+    llm_calls: 0,
+    verify_calls: 0
+  };
+}
+function formatVerifier(result, expectedKeys) {
+  if (result === null || result === void 0) {
+    return { passed: false, reason: "Result is null or undefined" };
+  }
+  if (expectedKeys && expectedKeys.length > 0) {
+    if (typeof result !== "object" || Array.isArray(result)) {
+      return { passed: false, reason: `Expected object with keys [${expectedKeys.join(", ")}], got ${Array.isArray(result) ? "array" : typeof result}` };
+    }
+    const obj = result;
+    const missing = expectedKeys.filter((k) => !(k in obj));
+    if (missing.length > 0) {
+      return { passed: false, reason: `Missing expected keys: ${missing.join(", ")}` };
+    }
+  }
+  if (typeof result === "object" && result !== null) {
+    const residue = detectSerializationResidue(result);
+    if (residue.length > 0) {
+      return { passed: false, reason: `Serialization residue detected at: ${residue.join(", ")}` };
+    }
+  }
+  return { passed: true, reason: "Format check passed" };
+}
+async function reverseVerify(verifier, task, context, result) {
+  return verifier.verify(task, context, result);
+}
+async function forwardCrossVerify(verifier, task, context, result) {
+  const results = await Promise.allSettled([
+    verifier.verify(task, context, result),
+    verifier.verify(task, context, result),
+    verifier.verify(task, context, result)
+  ]);
+  let passCount = 0;
+  let failCount = 0;
+  const reasons = [];
+  for (const r of results) {
+    if (r.status === "fulfilled") {
+      if (r.value.passed) passCount++;
+      else failCount++;
+      reasons.push(r.value.reason);
+    } else {
+      failCount++;
+      reasons.push(`Verification error: ${r.reason}`);
+    }
+  }
+  const passed = passCount >= 2;
+  return {
+    passed,
+    reason: passed ? `Cross-verification passed (${passCount}/3 agree)` : `Cross-verification failed (${failCount}/3 disagree): ${reasons.filter((_r, i) => {
+      const res = results[i];
+      return res?.status === "fulfilled" && !res.value.passed || res?.status === "rejected";
+    }).join("; ")}`
+  };
+}
+var TYPE_MAP = {
+  "str": z.string(),
+  "string": z.string(),
+  "int": z.number().int(),
+  "integer": z.number().int(),
+  "float": z.number(),
+  "number": z.number(),
+  "bool": z.boolean(),
+  "boolean": z.boolean(),
+  "list": z.array(z.unknown()),
+  "dict": z.record(z.unknown()),
+  "list[str]": z.array(z.string()),
+  "List[str]": z.array(z.string()),
+  "list[int]": z.array(z.number().int()),
+  "List[int]": z.array(z.number().int()),
+  "list[dict]": z.array(z.record(z.unknown())),
+  "List[dict]": z.array(z.record(z.unknown())),
+  "list[float]": z.array(z.number()),
+  "List[float]": z.array(z.number())
+};
+function resolveType(typeStr) {
+  return TYPE_MAP[typeStr.trim()] ?? z.string();
+}
+var TUPLE_RE = /^\(\s*(.+?)\s*,\s*"((?:[^"\\]|\\.)*)"\s*\)$/;
+function splitTopLevel(s) {
+  const parts = [];
+  let current = "";
+  let depth = 0;
+  let inString = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (inString) {
+      current += ch;
+      if (ch === inString && s[i - 1] !== "\\") {
+        inString = null;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = ch;
+      current += ch;
+      continue;
+    }
+    if (ch === "{" || ch === "[" || ch === "(") {
+      depth++;
+      current += ch;
+      continue;
+    }
+    if (ch === "}" || ch === "]" || ch === ")") {
+      depth--;
+      current += ch;
+      continue;
+    }
+    if (ch === "," && depth === 0) {
+      parts.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) {
+    parts.push(current.trim());
+  }
+  return parts;
+}
+function parseReturnFormat(formatStr) {
+  const trimmed = formatStr.trim();
+  if (!trimmed) return void 0;
+  if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+    const inner = trimmed.slice(1, -1).trim();
+    if (!inner) return {};
+    const parts = splitTopLevel(inner);
+    const result = {};
+    for (const part of parts) {
+      const colonIdx = part.indexOf(":");
+      if (colonIdx < 0) continue;
+      const key = part.slice(0, colonIdx).trim().replace(/^["']|["']$/g, "");
+      if (!key) continue;
+      const valStr = part.slice(colonIdx + 1).trim();
+      const tupleMatch = TUPLE_RE.exec(valStr);
+      if (tupleMatch) {
+        const innerType = resolveType(tupleMatch[1]);
+        const desc = tupleMatch[2].replace(/\\"/g, '"');
+        result[key] = { type: innerType, description: desc };
+      } else {
+        result[key] = { type: resolveType(valStr) };
+      }
+    }
+    return result;
+  }
+  return { result: { type: z.string(), description: trimmed } };
+}
+function createResponseFormat(formatStr) {
+  const fields = parseReturnFormat(formatStr);
+  let answerSchema;
+  if (!fields || Object.keys(fields).length === 0) {
+    answerSchema = z.string();
+  } else if (Object.keys(fields).length === 1 && "result" in fields) {
+    answerSchema = fields["result"].type;
+  } else {
+    const shape = {};
+    for (const [key, def] of Object.entries(fields)) {
+      shape[key] = def.type;
+    }
+    answerSchema = z.object(shape);
+  }
+  return z.object({
+    explanation: z.string(),
+    final_answer: answerSchema,
+    confidence: z.enum(["OK", "LACK_OF_INFO", "UNCERTAIN"]),
+    missing_info: z.record(z.object({
+      field: z.string(),
+      description: z.string(),
+      importance: z.string()
+    })).nullable().optional(),
+    suggestions: z.array(z.string()).nullable().optional()
+  });
+}
+function createDataSchema(formatStr) {
+  const fields = parseReturnFormat(formatStr);
+  if (!fields || Object.keys(fields).length === 0) {
+    return z.string();
+  }
+  if (Object.keys(fields).length === 1 && "result" in fields) {
+    return fields["result"].type;
+  }
+  const shape = {};
+  for (const [key, def] of Object.entries(fields)) {
+    shape[key] = def.type;
+  }
+  return z.object(shape);
+}
+var ExitSignal = class {
+  constructor(exitId, output) {
+    this.exitId = exitId;
+    this.output = output;
+  }
+};
+var LoopSignal = class {
+  constructor(action, targetId) {
+    this.action = action;
+    this.targetId = targetId;
+  }
+};
+var SpecExecutor = class {
+  llm;
+  verifier;
+  maxRetries;
+  constructor(options) {
+    this.llm = options.llm;
+    this.verifier = options.verifier;
+    this.maxRetries = options.maxRetries ?? 3;
+  }
+  /** Execute a StepInfo tree with given input variables */
+  async execute(steps, input) {
+    const stats = createEmptyStats();
+    const scope = new Map(Object.entries(input));
+    const stepResults = [];
+    let finalStatus = "ok";
+    let finalOutput = {};
+    try {
+      for (const step of steps) {
+        stats.total_steps++;
+        const result = await this.executeStep(step, scope, stats);
+        stepResults.push(result);
+        if (result.status !== "ok") {
+          finalStatus = result.status;
+          finalOutput = result.output;
+          break;
+        }
+      }
+    } catch (e) {
+      if (e instanceof ExitSignal) {
+        finalOutput = e.output;
+      } else {
+        throw e;
+      }
+    }
+    if (finalOutput === void 0 || typeof finalOutput === "object" && finalOutput !== null && Object.keys(finalOutput).length === 0) {
+      finalOutput = Object.fromEntries(scope);
+    }
+    return {
+      status: finalStatus,
+      output: finalOutput,
+      steps: stepResults,
+      stats
+    };
+  }
+  /** Execute a single step, dispatching by type */
+  async executeStep(step, scope, stats) {
+    switch (step.step_type) {
+      case "LLM":
+        return this.executeLLM(step, scope, stats);
+      case "code":
+        return this.executeCode(step, scope, stats);
+      case "loop":
+        return this.executeLoop(step, scope, stats);
+      case "branch":
+        return this.executeBranch(step, scope, stats);
+      case "flow":
+        return this.executeFlow(step, scope);
+      case "call":
+        return this.executeCall(step, scope, stats);
+      case "subtask":
+        return this.executeSubtask(step, scope, stats);
+      default:
+        return {
+          step_id: step.step_id,
+          status: "fail",
+          output: null,
+          retries: 0,
+          error: `Unknown step type: ${step.step_type}`
+        };
+    }
+  }
+  // ─── LLM step ───────────────────────────────────────────
+  async executeLLM(step, scope, stats) {
+    const prompt = this.buildPrompt(step, scope);
+    const options = {};
+    if (step.return_format) {
+      const fields = parseReturnFormat(step.return_format);
+      if (fields) {
+        options.systemPrompt = `Respond in JSON format with these fields: ${Object.keys(fields).join(", ")}`;
+      }
+    }
+    let lastError = "";
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      stats.llm_calls++;
+      const llmResult = await this.llm.query(prompt, options);
+      if (!llmResult.success) {
+        lastError = llmResult.content;
+        if (attempt < this.maxRetries) continue;
+        break;
+      }
+      const parsed = parseResult(llmResult.content);
+      const repaired = repairValue(parsed);
+      const expectedKeys = step.return_format ? Object.keys(parseReturnFormat(step.return_format) ?? {}) : void 0;
+      const fmtCheck = formatVerifier(repaired, expectedKeys?.length ? expectedKeys : void 0);
+      if (!fmtCheck.passed) {
+        lastError = fmtCheck.reason;
+        if (attempt < this.maxRetries) continue;
+        break;
+      }
+      if (this.verifier && step.verify_strategy !== "none") {
+        stats.verify_calls++;
+        const verifyResult = await reverseVerify(
+          this.verifier,
+          step.task || step.description,
+          JSON.stringify(Object.fromEntries(scope)),
+          JSON.stringify(repaired)
+        );
+        if (!verifyResult.passed) {
+          lastError = verifyResult.reason;
+          if (attempt < this.maxRetries) continue;
+          break;
+        }
+      }
+      this.storeOutputs(step, repaired, scope);
+      return {
+        step_id: step.step_id,
+        status: "ok",
+        output: repaired,
+        retries: attempt
+      };
+    }
+    return {
+      step_id: step.step_id,
+      status: "fail",
+      output: null,
+      retries: this.maxRetries,
+      error: lastError
+    };
+  }
+  // ─── Code step ──────────────────────────────────────────
+  executeCode(step, scope, stats) {
+    stats.total_steps;
+    for (const key of Object.keys(step.outputs)) {
+      if (!scope.has(key)) {
+        scope.set(key, null);
+      }
+    }
+    return Promise.resolve({
+      step_id: step.step_id,
+      status: "ok",
+      output: Object.fromEntries(
+        Object.keys(step.outputs).map((k) => [k, scope.get(k)])
+      ),
+      retries: 0
+    });
+  }
+  // ─── Loop step ──────────────────────────────────────────
+  async executeLoop(step, scope, stats) {
+    if (step.loop_mode === "for-each" && step.collection) {
+      const collection = scope.get(step.collection);
+      if (!Array.isArray(collection)) {
+        return {
+          step_id: step.step_id,
+          status: "fail",
+          output: null,
+          retries: 0,
+          error: `Loop collection "${step.collection}" is not an array`
+        };
+      }
+      const results = [];
+      for (const item of collection) {
+        if (step.element_var) {
+          scope.set(step.element_var, item);
+        }
+        try {
+          for (const child of step.children) {
+            stats.total_steps++;
+            const childResult = await this.executeStep(child, scope, stats);
+            if (childResult.status !== "ok") {
+              return { step_id: step.step_id, status: childResult.status, output: results, retries: 0, error: childResult.error };
+            }
+          }
+          results.push(item);
+        } catch (e) {
+          if (e instanceof LoopSignal) {
+            if (e.action === "break") break;
+            if (e.action === "continue") continue;
+          }
+          throw e;
+        }
+      }
+      this.storeOutputs(step, results, scope);
+      return { step_id: step.step_id, status: "ok", output: results, retries: 0 };
+    }
+    if (step.loop_mode === "while" && step.condition) {
+      const maxIter = step.max_iterations ?? 10;
+      let iteration = 0;
+      const results = [];
+      while (iteration < maxIter) {
+        iteration++;
+        try {
+          for (const child of step.children) {
+            stats.total_steps++;
+            const childResult = await this.executeStep(child, scope, stats);
+            if (childResult.status !== "ok") {
+              return { step_id: step.step_id, status: childResult.status, output: results, retries: 0, error: childResult.error };
+            }
+          }
+          results.push(iteration);
+        } catch (e) {
+          if (e instanceof LoopSignal) {
+            if (e.action === "break") break;
+            if (e.action === "continue") continue;
+          }
+          throw e;
+        }
+      }
+      this.storeOutputs(step, results, scope);
+      return { step_id: step.step_id, status: "ok", output: results, retries: 0 };
+    }
+    return {
+      step_id: step.step_id,
+      status: "fail",
+      output: null,
+      retries: 0,
+      error: "Loop step missing collection or condition"
+    };
+  }
+  // ─── Branch step ────────────────────────────────────────
+  async executeBranch(step, scope, stats) {
+    for (const child of step.children) {
+      stats.total_steps++;
+      const childResult = await this.executeStep(child, scope, stats);
+      if (childResult.status !== "ok") {
+        return { step_id: step.step_id, status: childResult.status, output: null, retries: 0, error: childResult.error };
+      }
+    }
+    return { step_id: step.step_id, status: "ok", output: null, retries: 0 };
+  }
+  // ─── Flow step ──────────────────────────────────────────
+  executeFlow(step, scope) {
+    if (step.flow_action === "exit") {
+      const output = Object.fromEntries(
+        Object.keys(step.outputs).map((k) => [k, scope.get(k)])
+      );
+      throw new ExitSignal(step.exit_id, output);
+    }
+    if (step.flow_action === "continue" || step.flow_action === "break") {
+      throw new LoopSignal(step.flow_action, step.exit_id);
+    }
+    return Promise.resolve({
+      step_id: step.step_id,
+      status: "ok",
+      output: null,
+      retries: 0
+    });
+  }
+  // ─── Call step ──────────────────────────────────────────
+  executeCall(step, scope, _stats) {
+    for (const key of Object.keys(step.outputs)) {
+      scope.set(key, `[call:${step.call_target}:${key}]`);
+    }
+    return Promise.resolve({
+      step_id: step.step_id,
+      status: "ok",
+      output: Object.fromEntries(
+        Object.keys(step.outputs).map((k) => [k, scope.get(k)])
+      ),
+      retries: 0
+    });
+  }
+  // ─── Subtask step ───────────────────────────────────────
+  async executeSubtask(step, scope, stats) {
+    if (step.expand_mode === "static" || !step.expand_mode) {
+      for (const child of step.children) {
+        stats.total_steps++;
+        const childResult = await this.executeStep(child, scope, stats);
+        if (childResult.status !== "ok") {
+          return { step_id: step.step_id, status: childResult.status, output: null, retries: 0, error: childResult.error };
+        }
+      }
+      return { step_id: step.step_id, status: "ok", output: null, retries: 0 };
+    }
+    for (const key of Object.keys(step.outputs)) {
+      scope.set(key, `[subtask:${step.expand_mode}:${key}]`);
+    }
+    return {
+      step_id: step.step_id,
+      status: "ok",
+      output: Object.fromEntries(
+        Object.keys(step.outputs).map((k) => [k, scope.get(k)])
+      ),
+      retries: 0
+    };
+  }
+  // ─── Helpers ────────────────────────────────────────────
+  buildPrompt(step, scope) {
+    const parts = [];
+    if (step.task) parts.push(`Task: ${step.task}`);
+    if (step.description) parts.push(`Description: ${step.description}`);
+    const inputs = Object.keys(step.inputs);
+    if (inputs.length > 0) {
+      parts.push("Context:");
+      for (const key of inputs) {
+        const val = scope.get(key);
+        parts.push(`  ${key}: ${JSON.stringify(val)}`);
+      }
+    }
+    if (step.return_format) {
+      parts.push(`Output format: ${step.return_format}`);
+    }
+    return parts.join("\n");
+  }
+  storeOutputs(step, result, scope) {
+    const outputKeys = Object.keys(step.outputs);
+    if (outputKeys.length === 0) return;
+    if (typeof result === "object" && result !== null && !Array.isArray(result)) {
+      const obj = result;
+      for (const key of outputKeys) {
+        if (key in obj) {
+          scope.set(key, obj[key]);
+        }
+      }
+    } else if (outputKeys.length === 1) {
+      scope.set(outputKeys[0], result);
+    }
+  }
+};
+var HopJIT = class {
+  llm;
+  verifier;
+  maxRetries;
+  grammar;
+  // Resume state
+  _liveExecutor;
+  _liveSpec;
+  _liveValidationErrors = [];
+  _pendingNeedInput;
+  constructor(options) {
+    this.llm = options.llm;
+    this.verifier = options.verifier;
+    this.maxRetries = options.maxRetries ?? 3;
+    this.grammar = options.grammar;
+  }
+  /**
+   * Parse and execute a HopSpec markdown document.
+   *
+   * Flow: parse → validate → execute
+   * Returns a JITResult with execution output, stats, and validation info.
+   */
+  async runSpec(markdown, input, options) {
+    const parsed = parseFullSpec(markdown, this.grammar);
+    const steps = parsed.steps;
+    const sections = parsed.sections;
+    const mode = options?.mode ?? "jit";
+    let validationErrors = [];
+    if (!options?.skipValidation) {
+      validationErrors = validateSpec(steps, mode, sections, this.grammar);
+    }
+    this._liveSpec = steps;
+    this._liveValidationErrors = validationErrors;
+    if (steps.length === 0) {
+      this._liveExecutor = void 0;
+      return {
+        status: "fail",
+        output: null,
+        steps: [],
+        stats: { total_steps: 0, completed_steps: 0, failed_steps: 0, total_retries: 0, llm_calls: 0, verify_calls: 0 },
+        spec: steps,
+        validationErrors
+      };
+    }
+    const executorOpts = {
+      llm: this.llm,
+      verifier: this.verifier,
+      maxRetries: this.maxRetries
+    };
+    const executor = new SpecExecutor(executorOpts);
+    this._liveExecutor = executor;
+    const result = await executor.execute(steps, input);
+    this._liveExecutor = void 0;
+    this._pendingNeedInput = void 0;
+    return {
+      status: result.status,
+      output: result.output,
+      steps: result.steps,
+      stats: result.stats,
+      spec: steps,
+      validationErrors
+    };
+  }
+  /**
+   * Resume execution from a NEED_INPUT checkpoint.
+   * Injects feedback and continues from the interrupted step.
+   *
+   * @throws Error if no pending execution to resume
+   */
+  async resume(feedback) {
+    if (!this._liveExecutor || !this._liveSpec) {
+      throw new Error("No pending execution to resume");
+    }
+    const input = { _feedback: feedback };
+    const result = await this._liveExecutor.execute(this._liveSpec, input);
+    this._liveExecutor = void 0;
+    this._pendingNeedInput = void 0;
+    return {
+      status: result.status,
+      output: result.output,
+      steps: result.steps,
+      stats: result.stats,
+      spec: this._liveSpec,
+      validationErrors: this._liveValidationErrors
+    };
+  }
+  /** Cancel any pending execution and clear resume state. */
+  cancel() {
+    this._liveExecutor = void 0;
+    this._liveSpec = void 0;
+    this._liveValidationErrors = [];
+    this._pendingNeedInput = void 0;
+  }
+  /** Whether there is a pending execution that can be resumed. */
+  get hasPending() {
+    return this._liveExecutor !== void 0 && this._liveSpec !== void 0;
+  }
+};
+
+// src/llm-protocol.ts
+function isSuccess(status) {
+  return status === "ok";
+}
+function isTerminal(status) {
+  return status === "ok" || status === "fail";
+}
+
+export { HopJIT, SpecExecutor, createDataSchema, createEmptyStats, createResponseFormat, formatVerifier, forwardCrossVerify, isSuccess, isTerminal, parseReturnFormat, reverseVerify };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map