@hoplogic/engine

HopSpec execution engine for TypeScript — step orchestration, LLM verification, retry loops.

Bring your own LLM: the engine uses Protocol interfaces (HopLLM, HopVerifier) so you can plug in any LLM SDK (Vercel AI SDK, OpenAI, Anthropic, etc.).

Install

npm install @hoplogic/engine

Usage

Basic: Execute a HopSpec

import { HopJIT } from "@hoplogic/engine"
import type { HopLLM, LLMResult } from "@hoplogic/engine"

// Implement the HopLLM protocol with your preferred SDK
const llm: HopLLM = {
  async query(prompt, options): Promise<LLMResult> {
    // Call your LLM here
    const response = await myLLM.generate(prompt)
    return { success: true, content: response }
  }
}

const jit = new HopJIT({ llm, maxRetries: 3 })
const result = await jit.runSpec(hopspecMarkdown, { question: "What is 1+1?" })

console.log(result.status)  // "ok" | "fail" | "need_input"
console.log(result.output)  // execution output
console.log(result.stats)   // { llm_calls: 2, verify_calls: 1, retries: 0 }

With Verification

import type { HopVerifier, VerifyResult } from "@hoplogic/engine"

const verifier: HopVerifier = {
  async verify(task, context, result): Promise<VerifyResult> {
    // Independent LLM call to verify the result
    return { passed: true, reason: "Result is correct" }
  }
}

const jit = new HopJIT({ llm, verifier, maxRetries: 3 })

Low-level: SpecExecutor

import { SpecExecutor } from "@hoplogic/engine"
import type { StepInfo } from "@hoplogic/spec"

const executor = new SpecExecutor({ llm, verifier, maxRetries: 3 })
const result = await executor.execute(steps, inputContext)

Protocols

HopLLM

interface HopLLM {
  query(prompt: string, options?: LLMOptions): Promise<LLMResult>
}

interface LLMOptions {
  systemPrompt?: string
  responseFormat?: ZodSchema  // for structured output
}

interface LLMResult {
  success: boolean
  content: string
}

HopVerifier

interface HopVerifier {
  verify(task: string, context: string, result: string): Promise<VerifyResult>
}

interface VerifyResult {
  passed: boolean
  reason: string
}

Step Types

The engine executes 7 step types:

| Type | Description | |------|-------------| | LLM | LLM inference with optional verification | | code | JavaScript expression evaluation (sandboxed via new Function) | | loop | For-each or while loops with break/continue | | branch | Conditional execution | | flow | Control flow: exit, continue, break | | call | External function calls | | subtask | Grouped sub-steps |

License

MIT