{"_id":"@aid-on/iteratop","_rev":"7-34ae61286a73cb80ae0e1b255a0f7c2c","name":"@aid-on/iteratop","dist-tags":{"latest":"0.3.5"},"versions":{"0.1.1":{"name":"@aid-on/iteratop","version":"0.1.1","keywords":["llm","iteration","convergence","agent","research","fact-check","ooda-loop","scrum","typescript","ai","refinement","builder-pattern"],"author":{"name":"Aid-On Team"},"license":"MIT","_id":"@aid-on/iteratop@0.1.1","maintainers":[{"name":"aid-on","email":"hiromi.motodera@aid-on.org"}],"homepage":"https://github.com/Aid-On/iteratop#readme","bugs":{"url":"https://github.com/Aid-On/iteratop/issues"},"dist":{"shasum":"a286cc4c4e8468287d915c77dd2fa7b70703f9a8","tarball":"https://registry.npmjs.org/@aid-on/iteratop/-/iteratop-0.1.1.tgz","fileCount":24,"integrity":"sha512-tNR1b7xuK6sI+jHSoFWiyeErmC5TSXB1UEOlbNjddIUwpQeW/Shqx7EWd5rzR20BmjlegiFcFYUblODfJ6RpXg==","signatures":[{"sig":"MEYCIQC+ZftDhLaR3DifimXalJqzsvaGG2EaQ9AczifkPjSe1wIhALhR2DqW63sOmM1r1FeEEkGminPPU8RBInMDvoPXVTUe","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":111708},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=16.0.0"},"scripts":{"test":"vitest run","build":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"aid-on","email":"hiromi.motodera@aid-on.org"},"repository":{"url":"git+https://github.com/Aid-On/iteratop.git","type":"git"},"_npmVersion":"10.8.2","description":"Iteration Processor for convergent loops with LLMs - Inspired by Scrum and OODA loops","directories":{},"_nodeVersion":"20.19.6","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","typescript":"^5.0.0","@vitest/coverage-v8":"^2.1.9"},"_npmOperationalInternal":{"tmp":"tmp/iteratop_0.1.1_1766723864743_0.6900897623572833","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@aid-on/iteratop","version":"0.2.0","keywords":["llm","iteration","convergence","agent","research","fact-check","ooda-loop","scrum","typescript","ai","refinement","builder-pattern"],"author":{"name":"Aid-On Team"},"license":"MIT","_id":"@aid-on/iteratop@0.2.0","maintainers":[{"name":"aid-on","email":"hiromi.motodera@aid-on.org"}],"homepage":"https://github.com/Aid-On/iteratop#readme","bugs":{"url":"https://github.com/Aid-On/iteratop/issues"},"dist":{"shasum":"a2a93e8c1003ec01b31402c83c57efb9ab6190c7","tarball":"https://registry.npmjs.org/@aid-on/iteratop/-/iteratop-0.2.0.tgz","fileCount":28,"integrity":"sha512-ZMk2JeOHKj7oylOzINBc34h6MDluljA9WAI5OZOoncZLTuDxtWop6QtI3xX5FuOoiD3TgqSir0ZfmRtfPNGxHQ==","signatures":[{"sig":"MEYCIQCuPlhgF4qqs0Scwu+3OEhXE0xwTH+IbmkPyUuVNCJ36gIhAJjVnaUJnzRBcyWk8zGwFdIwPTPYtTPxj6gZiMRD0aTX","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":130959},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=16.0.0"},"scripts":{"test":"vitest run","build":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"aid-on","email":"hiromi.motodera@aid-on.org"},"repository":{"url":"git+https://github.com/Aid-On/iteratop.git","type":"git"},"_npmVersion":"10.8.2","description":"Iteration Processor for convergent loops with LLMs - Inspired by Scrum and OODA loops","directories":{},"_nodeVersion":"20.19.6","dependencies":{"@aid-on/nagare":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","vitest":"^2.0.0","typescript":"^5.0.0","@vitest/coverage-v8":"^2.1.9"},"_npmOperationalInternal":{"tmp":"tmp/iteratop_0.2.0_1766725083952_0.8482873651995158","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@aid-on/iteratop","version":"0.2.1","keywords":["llm","iteration","convergence","agent","research","fact-check","ooda-loop","scrum","typescript","ai","refinement","builder-pattern"],"author":{"name":"Aid-On Team"},"license":"MIT","_id":"@aid-on/iteratop@0.2.1","maintainers":[{"name":"aid-on","email":"hiromi.motodera@aid-on.org"}],"homepage":"https://github.com/Aid-On/iteratop#readme","bugs":{"url":"https://github.com/Aid-On/iteratop/issues"},"dist":{"shasum":"3b9f9f48af47c1d5956b98ba4090f43a59b6ed82","tarball":"https://registry.npmjs.org/@aid-on/iteratop/-/iteratop-0.2.1.tgz","fileCount":28,"integrity":"sha512-NdZQZN/pHizBrhad2d+u5jdtny29mre43daiq7R+jJe428JrttgyGC7MpgDL2JmK+gSvy9v2gl/EsQf/uyTZmA==","signatures":[{"sig":"MEUCIQDQXcoLgtR8ZW2l90QQ9AmKN4JqXbadw9L3lmCXgyqQGgIgAgX19JQOZ0/yLwObiwb1PdF/h3ISAWlMz+uSDzZpW2o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":134594},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=16.0.0"},"scripts":{"test":"vitest run","build":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"aid-on","email":"hiromi.motodera@aid-on.org"},"repository":{"url":"git+https://github.com/Aid-On/iteratop.git","type":"git"},"_npmVersion":"10.8.2","description":"Iteration Processor for convergent loops with LLMs - Inspired by Scrum and OODA loops","directories":{},"_nodeVersion":"20.19.6","dependencies":{"@aid-on/nagare":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","vitest":"^2.0.0","typescript":"^5.0.0","@vitest/coverage-v8":"^2.1.9"},"_npmOperationalInternal":{"tmp":"tmp/iteratop_0.2.1_1766725601148_0.5332256916753386","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@aid-on/iteratop","version":"0.3.1","keywords":["llm","iteration","convergence","agent","research","fact-check","ooda-loop","scrum","typescript","ai","refinement","builder-pattern"],"author":{"name":"Aid-On Team"},"license":"MIT","_id":"@aid-on/iteratop@0.3.1","maintainers":[{"name":"aid-on","email":"hiromi.motodera@aid-on.org"}],"homepage":"https://github.com/Aid-On/iteratop#readme","bugs":{"url":"https://github.com/Aid-On/iteratop/issues"},"dist":{"shasum":"ce4b5cc90b7a94212519fa23030df5eae3e58a39","tarball":"https://registry.npmjs.org/@aid-on/iteratop/-/iteratop-0.3.1.tgz","fileCount":10,"integrity":"sha512-IbTDSwW//P1sIpxYufFSET4jUR33S11co4PAOyD4Tj5ZEmLdO7xFyMFz8mRYfxYUyhuXiLjjGKbnfj9b1WaXmA==","signatures":[{"sig":"MEUCIQDR9rtMtv0lII8f1FQYJ34hP6hIhmLH/iKMj65GRsq3SwIgRNhpDfMqJF950YCLZ6Ds0elg0JD0s7BLlMbYyJgHgGQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":241959},"main":"dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=16.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"test":"vitest run","build":"tsup","build:tsc":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"aid-on","email":"hiromi.motodera@aid-on.org"},"repository":{"url":"git+https://github.com/Aid-On/iteratop.git","type":"git"},"_npmVersion":"10.8.2","description":"Iteration Processor for convergent loops with LLMs - Inspired by Scrum and OODA loops","directories":{},"sideEffects":false,"_nodeVersion":"20.19.6","dependencies":{"@aid-on/nagare":"^0.2.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","tsup":"^8.5.1","vitest":"^2.0.0","typescript":"^5.0.0","@vitest/coverage-v8":"^2.1.9"},"_npmOperationalInternal":{"tmp":"tmp/iteratop_0.3.1_1767191190936_0.30471560876198023","host":"s3://npm-registry-packages-npm-production"}},"0.3.2":{"name":"@aid-on/iteratop","version":"0.3.2","keywords":["llm","iteration","convergence","agent","research","fact-check","ooda-loop","scrum","typescript","ai","refinement","builder-pattern"],"author":{"name":"Aid-On Team"},"license":"MIT","_id":"@aid-on/iteratop@0.3.2","maintainers":[{"name":"aid-on","email":"hiromi.motodera@aid-on.org"}],"homepage":"https://github.com/Aid-On/iteratop#readme","bugs":{"url":"https://github.com/Aid-On/iteratop/issues"},"dist":{"shasum":"604ce58a9ec6fbaeb8391bcb5430f34e54bef15f","tarball":"https://registry.npmjs.org/@aid-on/iteratop/-/iteratop-0.3.2.tgz","fileCount":10,"integrity":"sha512-rJ08Qe74QGoB/mf6YrOSf1lkldPk2NvFxXvffOi3olYQfBo3IwYP/HFaa6+dyfFTS9z1ItdRstfeGZQKz372yg==","signatures":[{"sig":"MEQCIBW5Gog3Lb8NcZiLtvQ6zhAmcLpUMCn0XmY2IwBm3033AiAJ5xvCybFDDnuxDZ7FVUgKqommYZXvvWjweIC1T61vbw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":249229},"main":"dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=16.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"test":"vitest run","build":"tsup","build:tsc":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"aid-on","email":"hiromi.motodera@aid-on.org"},"repository":{"url":"git+https://github.com/Aid-On/iteratop.git","type":"git"},"_npmVersion":"10.8.2","description":"Iteration Processor for convergent loops with LLMs - Inspired by Scrum and OODA loops","directories":{},"sideEffects":false,"_nodeVersion":"20.19.6","dependencies":{"@aid-on/nagare":"^0.2.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","tsup":"^8.5.1","vitest":"^2.0.0","typescript":"^5.0.0","@vitest/coverage-v8":"^2.1.9"},"_npmOperationalInternal":{"tmp":"tmp/iteratop_0.3.2_1771341585820_0.5289696322292305","host":"s3://npm-registry-packages-npm-production"}},"0.3.3":{"name":"@aid-on/iteratop","version":"0.3.3","keywords":["llm","iteration","convergence","agent","research","fact-check","ooda-loop","scrum","typescript","ai","refinement","builder-pattern"],"author":{"name":"Aid-On Team"},"license":"MIT","_id":"@aid-on/iteratop@0.3.3","maintainers":[{"name":"aid-on","email":"hiromi.motodera@aid-on.org"}],"homepage":"https://github.com/Aid-On/iteratop#readme","bugs":{"url":"https://github.com/Aid-On/iteratop/issues"},"dist":{"shasum":"26cb044da13325cb82d97799ca1d01fb7a3ccb93","tarball":"https://registry.npmjs.org/@aid-on/iteratop/-/iteratop-0.3.3.tgz","fileCount":10,"integrity":"sha512-Jn8ZHS0aQQzVi7Esi2F2q1g9mNloKzFkXG+sc0qdd5FMOe5Mev+tbOKuGUmhh20jbwe3tZzHKE8SuPnWeQWf5Q==","signatures":[{"sig":"MEQCIFlgmVU1uRsbr/NXXXcSPjrvwrPahXkl/pF+u/5cDUr5AiBxvmFSMZJNP3BRZVtRNntQBHYijSvVNZNszt3m30xHPA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":249229},"main":"dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=16.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"test":"vitest run","build":"tsup","build:tsc":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"aid-on","email":"hiromi.motodera@aid-on.org"},"repository":{"url":"git+https://github.com/Aid-On/iteratop.git","type":"git"},"_npmVersion":"10.8.2","description":"Iteration Processor for convergent loops with LLMs - Inspired by Scrum and OODA loops","directories":{},"sideEffects":false,"_nodeVersion":"20.19.6","dependencies":{"@aid-on/nagare":"^0.2.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","tsup":"^8.5.1","vitest":"^2.0.0","typescript":"^5.0.0","@vitest/coverage-v8":"^2.1.9"},"_npmOperationalInternal":{"tmp":"tmp/iteratop_0.3.3_1771343140503_0.18586282709669044","host":"s3://npm-registry-packages-npm-production"}},"0.3.5":{"name":"@aid-on/iteratop","version":"0.3.5","description":"Iteration Processor for convergent loops with LLMs - Inspired by Scrum and OODA loops","type":"module","main":"dist/index.cjs","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"sideEffects":false,"scripts":{"build":"tsup","build:tsc":"tsc","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm test"},"keywords":["llm","iteration","convergence","agent","research","fact-check","ooda-loop","scrum","typescript","ai","refinement","builder-pattern"],"author":{"name":"Aid-On Team"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Aid-On/iteratop.git"},"bugs":{"url":"https://github.com/Aid-On/iteratop/issues"},"homepage":"https://github.com/Aid-On/iteratop#readme","devDependencies":{"@vitest/coverage-v8":"^2.1.9","tsup":"^8.5.1","tsx":"^4.21.0","typescript":"^5.0.0","vitest":"^2.0.0"},"engines":{"node":">=16.0.0"},"publishConfig":{"access":"public"},"dependencies":{"@aid-on/nagare":"^0.2.5"},"_id":"@aid-on/iteratop@0.3.5","_nodeVersion":"20.19.6","_npmVersion":"10.8.2","dist":{"integrity":"sha512-RLlrzbH55hxNaiEJKL53YfjJq1VUi7CDImB+JkpLnqobhd3d+oaxe5fMOyrCMWbidHO2Bm/uYiKpgCbmKucMEw==","shasum":"c0c39d153b2e99199681ccf764a9eacd0ef28996","tarball":"https://registry.npmjs.org/@aid-on/iteratop/-/iteratop-0.3.5.tgz","fileCount":10,"unpackedSize":249390,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCmG0mnPX85DfqqCp4R6U/9B00KNL0IP8e6CerkTvFX6QIgfWPMKk/yxisnGQGUznu+eV+bjcMtG5KCxmoNb5JdVP8="}]},"_npmUser":{"name":"aid-on","email":"hiromi.motodera@aid-on.org"},"directories":{},"maintainers":[{"name":"aid-on","email":"hiromi.motodera@aid-on.org"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/iteratop_0.3.5_1771435188621_0.5993558939537129"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-26T04:37:44.660Z","modified":"2026-02-18T17:19:48.904Z","0.1.1":"2025-12-26T04:37:44.886Z","0.2.0":"2025-12-26T04:58:04.112Z","0.2.1":"2025-12-26T05:06:41.306Z","0.3.1":"2025-12-31T14:26:31.096Z","0.3.2":"2026-02-17T15:19:46.004Z","0.3.3":"2026-02-17T15:45:40.710Z","0.3.5":"2026-02-18T17:19:48.774Z"},"bugs":{"url":"https://github.com/Aid-On/iteratop/issues"},"author":{"name":"Aid-On Team"},"license":"MIT","homepage":"https://github.com/Aid-On/iteratop#readme","keywords":["llm","iteration","convergence","agent","research","fact-check","ooda-loop","scrum","typescript","ai","refinement","builder-pattern"],"repository":{"type":"git","url":"git+https://github.com/Aid-On/iteratop.git"},"description":"Iteration Processor for convergent loops with LLMs - Inspired by Scrum and OODA loops","maintainers":[{"name":"aid-on","email":"hiromi.motodera@aid-on.org"}],"readme":"# IteratoP\n\n> A powerful TypeScript library for building convergent iteration loops with LLMs, inspired by Scrum iterations and OODA loops.\n\n## Name Origin\n\nIteratoP = **Iterat**i**o**n **P**rocessor\n\nThe name reflects the library's core purpose: processing iterations until convergence. The \"P\" suffix follows the Aid-On platform's naming convention for processor libraries (like FractoP for fractal processing).\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Test Coverage](https://img.shields.io/badge/Coverage-99%25-brightgreen)]()\n\n[日本語](README.ja.md) | English\n\n## Features\n\n- **Convergent Loops** - Automatically iterate until quality targets are reached\n- **Flexible Configuration** - Multiple ways to configure: Builder pattern, presets, dynamic updates\n- **Built-in Metrics** - Track costs, performance, and convergence scores\n- **Builder Pattern** - Fluent API for intuitive setup\n- **Presets** - Pre-configured settings for common use cases\n- **Event System** - Hook into iteration lifecycle events\n- **Type Safe** - Full TypeScript support with generics\n- **Error Recovery** - Built-in error handling and fallback mechanisms\n- **Performance Optimized** - Efficient iteration with early stopping\n\n## Installation\n\n```bash\nnpm install @aid-on/iteratop\n# or\nyarn add @aid-on/iteratop\n# or\npnpm add @aid-on/iteratop\n```\n\n## What's New in v0.2.0\n\n- **Nagare Streaming Support**: Integration with [@aid-on/nagare](https://github.com/Aid-On/nagare) for real-time iteration streaming\n- **StreamingIteratoP**: Stream iteration states as they happen\n- **Full Backward Compatibility**: All existing code continues to work\n\n## Quick Start\n\n### Basic Usage\n\n```typescript\nimport { createIterator, createActionResult, createEvaluation } from '@aid-on/iteratop';\n\nconst processor = createIterator({\n  initialize: async (input) => ({ \n    query: input, \n    results: [] \n  }),\n  \n  act: async (state) => {\n    const data = await searchAPI(state.query);\n    return createActionResult(data, { cost: 0.01 });\n  },\n  \n  evaluate: async (state, actionResult) => {\n    const score = calculateRelevance(actionResult.data);\n    return createEvaluation(score, {\n      shouldContinue: score < 70,\n      feedback: `Relevance: ${score}%`,\n    });\n  },\n  \n  transition: async (state, actionResult, evaluation) => ({\n    ...state,\n    results: [...state.results, actionResult.data],\n    query: refineQuery(state.query, evaluation.feedback),\n  }),\n  \n  finalize: async (state) => ({\n    answer: synthesizeAnswer(state.results),\n  }),\n});\n\nconst result = await processor.run(\"What is quantum computing?\");\nconsole.log(`Answer: ${result.result.answer}`);\nconsole.log(`Converged in ${result.iterations} iterations`);\n```\n\n### Using Builder Pattern\n\n```typescript\nimport { iterationBuilder } from '@aid-on/iteratop';\n\nconst result = await iterationBuilder()\n  .initialize(async (input) => ({ value: input }))\n  .act(async (state) => createActionResult(state.value * 2))\n  .evaluate(async (_, result) => createEvaluation(result.data))\n  .transition(async (_, result) => ({ value: result.data }))\n  .finalize(async (state) => state.value)\n  .preset('balanced')\n  .maxIterations(5)\n  .targetScore(80)\n  .run(10);\n```\n\n## Concepts\n\n### Iteration Flow\n\nIteratoP follows a structured iteration flow inspired by Scrum and OODA loops:\n\n```mermaid\ngraph TD\n    Start([Input]) --> Initialize[Initialize State]\n    Initialize --> Act[Act: Execute Action]\n    Act --> Evaluate[Evaluate: Score & Feedback]\n    Evaluate --> Check{Converged?}\n    Check -->|No| Transition[Transition: Update State]\n    Transition --> Act\n    Check -->|Yes| Finalize[Finalize: Generate Result]\n    Finalize --> End([Output])\n```\n\n1. **Initialize** (Sprint Planning) - Set up initial state from input\n2. **Act** (Sprint Execution) - Execute actions based on current state\n3. **Evaluate** (Sprint Review) - Assess progress and generate feedback\n4. **Transition** (Retrospective) - Update state for next iteration\n5. **Finalize** (Release) - Generate final result from converged state\n\n## Configuration\n\n### Streaming Iterations (v0.2.0+)\n\nStream iteration states in real-time using nagare Stream<T>:\n\n```typescript\nimport { createStreamingIterator } from '@aid-on/iteratop';\nimport { createActionResult, createEvaluation } from '@aid-on/iteratop';\n\nconst processor = createStreamingIterator({\n  initialize: async (input) => ({ query: input, confidence: 0 }),\n  \n  act: async (state, context) => \n    createActionResult({ \n      data: await searchDatabase(state.query) \n    }),\n  \n  evaluate: async (state, actionResult, context) => \n    createEvaluation(calculateConfidence(actionResult.data), {\n      shouldContinue: state.confidence < 80,\n      feedback: 'Refining search...'\n    }),\n  \n  transition: async (state, actionResult, evaluation) => ({\n    ...state,\n    query: refineQuery(state.query, evaluation.feedback),\n    confidence: evaluation.score\n  })\n});\n\n// Stream all iteration states\nconst stream = await processor.executeStream(\"LLM optimization techniques\");\nfor await (const state of stream) {\n  console.log(`Iteration ${state.iteration}: ${state.converged ? 'Converged!' : 'Processing...'}`);\n  if (state.evaluation) {\n    console.log(`  Score: ${state.evaluation.score}`);\n  }\n}\n\n// Or stream just evaluations\nconst evaluations = await processor.evaluationStream(\"LLM optimization\");\nfor await (const evaluation of evaluations) {\n  console.log(`Score: ${evaluation.score} - ${evaluation.feedback}`);\n}\n```\n\n### Available Presets\n\n```typescript\nimport { DEFAULT_PRESETS } from '@aid-on/iteratop';\n\n// View all available presets and their values\nconsole.log(DEFAULT_PRESETS);\n\n// Available presets:\n// - 'fast': Quick convergence, minimal iterations (3 max, score 60)\n// - 'thorough': Higher quality, more iterations (10 max, score 90)\n// - 'balanced': Default balanced approach (5 max, score 70)\n// - 'cost-optimized': Minimize API calls and costs (3 max, skip min)\n\n// Use a preset\nconst processor = iterationBuilder()\n  .preset('thorough')\n  // ... other configurations\n  .build();\n```\n\n### Custom Configuration\n\n```typescript\nconst processor = createIterator(options, {\n  // Iteration Control\n  maxIterations: 5,          // Maximum iterations (default: 5)\n  targetScore: 70,           // Target convergence score (default: 70)\n  earlyStopScore: 95,        // Early termination score (default: 95)\n  minIterations: 1,          // Minimum iterations before stopping (default: 1)\n  \n  // Performance\n  timeout: 10000,            // Overall timeout in ms (optional)\n  skipMinIterations: false,  // Allow early stop before minIterations\n  \n  // State Management\n  alwaysRunTransition: true, // Run transition on final iteration\n  \n  // Debugging\n  verbose: true,             // Enable logging (default: false)\n  logger: {                  // Custom logger\n    error: console.error,\n    log: console.log,\n  },\n});\n```\n\n### Dynamic Configuration\n\n```typescript\n// Update configuration after creation\nprocessor\n  .updateConfig({ maxIterations: 10 })\n  .updateConfig({ verbose: true });\n\n// Create variant with different config\nconst processor2 = processor.withConfig({ targetScore: 90 });\n\n// Reset to defaults\nprocessor.resetConfig();\n```\n\n## Advanced Usage\n\n### Event Handling\n\n```typescript\nprocessor.on((event) => {\n  switch (event.type) {\n    case 'iteration_start':\n      console.log(`Starting iteration ${event.iteration + 1}`);\n      break;\n    case 'evaluation_complete':\n      console.log(`Score: ${event.evaluation.score}`);\n      break;\n    case 'converged':\n      console.log(`Converged at iteration ${event.iteration + 1}`);\n      break;\n    case 'complete':\n      console.log(`Final: ${JSON.stringify(event.result)}`);\n      break;\n  }\n});\n```\n\n### Error Handling\n\n```typescript\nconst processor = createIterator({\n  // ... other options ...\n  onError: async (error, state, context) => {\n    console.error(`Error at iteration ${context.iteration}:`, error);\n    // Return fallback result\n    return { \n      fallback: true, \n      partialData: state?.results || [],\n      error: error.message \n    };\n  },\n});\n```\n\n### Custom Termination\n\n```typescript\nconst processor = createIterator({\n  // ... other options ...\n  shouldTerminate: (state, evaluation, context) => {\n    // Custom termination logic\n    return (\n      state.attempts > 3 || \n      evaluation.score > 90 ||\n      state.costs > 1.00\n    );\n  },\n});\n```\n\n## Utilities\n\n### Result Analysis\n\n```typescript\nimport {\n  calculateTotalCost,\n  calculateAverageScore,\n  getScoreProgression,\n  isImproving,\n} from '@aid-on/iteratop';\n\n// Analyze iteration history\nconst totalCost = calculateTotalCost(result.history);\nconst avgScore = calculateAverageScore(result.history);\nconst scores = getScoreProgression(result.history);\nconst improving = isImproving(result.history, windowSize = 2);\n```\n\n### Merging Results\n\n```typescript\nimport {\n  mergeActionResults,\n  mergeArrayActionResults,\n  mergeObjectActionResults,\n} from '@aid-on/iteratop';\n\n// Merge array results with deduplication\nconst merged = mergeArrayActionResults(\n  [result1, result2],\n  item => item.id  // Deduplication key\n);\n\n// Deep merge objects\nconst merged = mergeObjectActionResults(results, 'deep');\n\n// Custom merge strategy\nconst merged = mergeActionResults(results, items => \n  items.reduce((acc, item) => ({ ...acc, ...item }), {})\n);\n```\n\n### Async Utilities\n\n```typescript\nimport { withRetry, withTimeout, sleep } from '@aid-on/iteratop';\n\n// Retry with exponential backoff\nconst data = await withRetry(\n  () => fetchData(url),\n  { \n    maxRetries: 3, \n    initialDelay: 1000,\n    backoffFactor: 2 \n  }\n);\n\n// Add timeout\nconst result = await withTimeout(\n  longOperation(),\n  5000,\n  'Operation timed out'\n);\n```\n\n## Real-World Examples\n\n### LLM Chain with Quality Refinement\n\n```typescript\nconst refiner = iterationBuilder()\n  .initialize(async (prompt) => ({\n    prompt,\n    response: '',\n    history: [],\n  }))\n  .act(async (state) => {\n    const response = await llm.generate(state.prompt);\n    return createActionResult(response, { \n      cost: 0.002 * response.tokens / 1000 \n    });\n  })\n  .evaluate(async (state, result) => {\n    const quality = await evaluateQuality(result.data);\n    const issues = await findIssues(result.data);\n    \n    return createEvaluation(quality.score, {\n      shouldContinue: quality.score < 80,\n      feedback: quality.feedback,\n      missingInfo: issues,\n    });\n  })\n  .transition(async (state, result, evaluation) => ({\n    ...state,\n    response: result.data,\n    history: [...state.history, result.data],\n    prompt: improvePrompt(state.prompt, evaluation.feedback),\n  }))\n  .finalize(async (state) => ({\n    finalAnswer: state.response,\n    iterations: state.history.length,\n    quality: await evaluateQuality(state.response),\n  }))\n  .preset('thorough')\n  .build();\n```\n\n### Multi-Source Research Agent\n\n```typescript\nconst researcher = iterationBuilder()\n  .initialize(async (topic) => ({\n    topic,\n    sources: [],\n    knowledge: {},\n    gaps: [],\n  }))\n  .act(async (state) => {\n    // Parallel searches\n    const searches = await Promise.all([\n      searchWeb(state.topic),\n      searchAcademic(state.topic),\n      searchNews(state.topic),\n    ]);\n    \n    return createActionResult(searches.flat(), { \n      cost: 0.05,\n      sources: searches.map(s => s.url),\n    });\n  })\n  .evaluate(async (state, results) => {\n    const coverage = assessCoverage(state.knowledge, state.topic);\n    const reliability = assessReliability(results.data);\n    const score = (coverage * 0.7 + reliability * 0.3);\n    \n    return createEvaluation(score, {\n      shouldContinue: score < 85,\n      missingInfo: identifyGaps(state.knowledge, state.topic),\n    });\n  })\n  .transition(async (state, results, evaluation) => ({\n    ...state,\n    sources: [...state.sources, ...results.data],\n    knowledge: mergeKnowledge(state.knowledge, results.data),\n    gaps: evaluation.missingInfo || [],\n    topic: refineTopic(state.topic, evaluation.missingInfo),\n  }))\n  .finalize(async (state) => ({\n    report: generateReport(state.knowledge),\n    sources: rankSources(state.sources),\n    confidence: calculateConfidence(state.knowledge),\n    gaps: state.gaps,\n  }))\n  .preset('thorough')\n  .verbose(true)\n  .build();\n```\n\n### Fact-Checking System\n\n```typescript\nconst factChecker = createIterator({\n  initialize: async (claim) => ({\n    claim,\n    evidence: [],\n    queries: [claim],\n    verdict: 'UNKNOWN',\n  }),\n\n  act: async (state, context) => {\n    const query = state.queries[context.iteration] || state.claim;\n    const evidence = await gatherEvidence(query);\n    return createActionResult(evidence, {\n      cost: 0.01 * evidence.length,\n      sources: evidence.map(e => e.source),\n    });\n  },\n\n  evaluate: async (state, actionResult) => {\n    const allEvidence = [...state.evidence, ...actionResult.data];\n    const analysis = await analyzeClaim(state.claim, allEvidence);\n    \n    return createEvaluation(analysis.confidence, {\n      shouldContinue: analysis.confidence < 70 && state.queries.length < 5,\n      feedback: analysis.reasoning,\n      missingInfo: analysis.missingEvidence,\n    });\n  },\n\n  transition: async (state, actionResult, evaluation) => ({\n    ...state,\n    evidence: [...state.evidence, ...actionResult.data],\n    queries: evaluation.missingInfo ? \n      [...state.queries, ...generateQueries(evaluation.missingInfo)] :\n      state.queries,\n    verdict: determineVerdict(evaluation.score),\n  }),\n\n  finalize: async (state, history) => ({\n    claim: state.claim,\n    verdict: state.verdict,\n    confidence: history[history.length - 1]?.evaluation.score || 0,\n    evidence: rankEvidence(state.evidence),\n    reasoning: generateReasoning(state),\n  }),\n}, {\n  maxIterations: 5,\n  targetScore: 70,\n  earlyStopScore: 90,\n});\n```\n\n## Performance Tips\n\n1. **Use Presets** - Start with presets and adjust as needed\n2. **Set Appropriate Timeouts** - Prevent infinite loops\n3. **Monitor Costs** - Track API costs with metadata\n4. **Use Early Stopping** - Set `earlyStopScore` to avoid unnecessary iterations\n5. **Batch Operations** - Perform parallel operations in `act` when possible\n6. **Cache Results** - Implement caching in your action functions\n7. **Use Events Wisely** - Don't perform heavy operations in event listeners\n\n## License\n\nMIT © Aid-On\n\n---\n\nBuilt by the Aid-On team","readmeFilename":"README.md"}