@hoplogic/engine 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# @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
+
+```bash
+npm install @hoplogic/engine
+```
+
+## Usage
+
+### Basic: Execute a HopSpec
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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