# Engine Reference

Parameter catalogs for the engine classes in `lionagi.engines`.
All engines inherit from `Engine` (base parameters documented first).

## Engine (base)

Stateless event-driven engine base.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `model` | `None` | Default model string for every stage. |
| `models` | `{}` | Per-stage model overrides: `{"stage": "provider/model", ...}`. |
| `max_depth` | `3` | Maximum recursion depth or cycle generation. |
| `max_concurrent` | `5` | Concurrency semaphore width (simultaneous agent slots). |
| `max_agents` | `50` | Hard cap on total agents the run may create. |
| `deadline_s` | `None` | Wall-clock cap in seconds; `None` = unbounded. |
| `judge_model` | `None` | If set, a cheap gate agent runs at expansion points. `None` = no gate (fail-open). |
| `judge_role` | `"critic"` | Casts role for the judge agent. |

On budget exhaustion `Engine.run()` calls `_partial_export()` (override in subclasses to return a partial result) instead of raising. Caller-initiated cancellation still propagates as `CancelledError`.

---

## CodingEngine

Gated implement/test/fix-loop engine (`lionagi.engines.coding`).

Extends `Engine` with:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `plan_role` | `"analyst"` | Casts role that writes the implementation plan (`WorkPlanned`). |
| `implement_role` | `"implementer"` | Casts role that writes code using `coding_tools`. |
| `verify_role` | `"critic"` | Casts role that issues the `VerifyResult` verdict. |
| `coding_tools` | `("coding",)` | Tool names granted to the implementer agent. |
| `implement_permissions` | `"safe"` | Permission preset for the implementer. |
| `max_fix_rounds` | `3` | Maximum test-fail re-prompt rounds before concluding. |
| `test_timeout_s` | `600.0` | Wall-clock cap for each subprocess test run. |
| `repair_retries` | `1` | Emission-repair turns per stage when the model emits no valid event. |

Per-stage model routing keys: `"plan"`, `"implement"`, `"verify"`.

Pipeline shape: plan → implement → test → [fix loop, up to `max_fix_rounds`] → verify → `CodeResultRecorded`.

---

## HypothesisEngine

Evidence-chain engine for hypothesis-driven development (`lionagi.engines.hypothesis`).

Extends `Engine` with one casts role per stage:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `question_role` | `"analyst"` | Extracts `QuestionRaised` events from findings. |
| `research_role` | `"researcher"` | Gathers `EvidenceCollected` for a question. |
| `hypothesis_role` | `"analyst"` | Forms `HypothesisFormed` or direct `ConclusionDrawn` from evidence. |
| `design_role` | `"evaluator"` | Designs the decisive `ExperimentDesigned`. |
| `validate_role` | `"analyst"` | Executes experiments and records `ResultRecorded`. |
| `conclude_role` | `"critic"` | Draws `ConclusionDrawn` from a result. |
| `apply_role` | `"architect"` | Maps conclusions onto decisions as `ApplicationMapped`. |
| `synthesis_role` | `"synthesizer"` | Writes the final evidence report. |
| `executable_methods` | `("analysis", "comparison", "proof")` | Experiment methods the validator runs inline. Others queue on `run.pending`. |
| `validate_tools` | `()` | Tool names granted to the validator agent for real measurements. |
| `validate_cwd` | `None` | Workspace the validator is path-guarded to. |
| `validate_permissions` | `"safe"` | Permission preset for the validator. |
| `max_questions` | `8` | Per-extraction cap threaded into the prompt (soft; judge and budget are the hard bounds). |
| `repair_retries` | `1` | Re-prompt turns when an expected emission did not arrive. |

`max_depth` (from `Engine`) bounds back-edge cycles: follow-up questions and findings raised at `gen > max_depth` are recorded but not expanded.

Per-stage model routing keys: `"extract"`, `"research"`, `"hypothesize"`, `"design"`, `"validate"`, `"conclude"`, `"apply"`, `"synthesize"`.

Pipeline shape: seed findings → extract questions → gather evidence → form hypotheses → design experiments → validate → draw conclusions → apply to decisions → synthesize report.

---

## PlanningEngine

Plan-then-execute engine over the reactive DAG executor (`lionagi.engines.planning`).

This is the engine `li o flow` uses as its CLI front-end.

Extends `Engine` with:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `orchestrator_role` | `"orchestrator"` | Casts role that decomposes the prompt into a `list[TaskAssignment]`. |
| `roles` | `("researcher", "analyst", "critic", "architect", "synthesizer")` | Roster the orchestrator may assign workers to. |
| `synthesis_role` | `"synthesizer"` | Casts role that writes the final deliverable from worker outputs. |
| `reactive` | `True` | When `True`, every worker is granted `SpawnRequest` so the live DAG self-expands. `False` runs a flat, fully-planned DAG. |

Pipeline shape: orchestrate (produce DAG) → execute reactively → synthesize outputs into deliverable.

---

## ResearchEngine

Recursive, reaction-driven research engine (`lionagi.engines.research`).

Extends `Engine` with:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `novelty_threshold` | `0.7` | A `FindingEmitted` above this novelty spawns a deeper exploration node. |
| `roles` | `("researcher", "analyst", "critic")` | Casts roles forming each exploration team (run in sequence, sharing output). Each is granted the research emissions. |
| `synthesis_role` | `"synthesizer"` | Casts role that writes the final synthesis from the emission store. |
| `repair_retries` | `1` | Re-prompt turns when an exploration node's whole team emitted no finding. |

`max_depth` (from `Engine`) bounds recursive depth; `max_agents` and `deadline_s` bound cost.

Pipeline shape: explore topic (team of agents) → spawn deeper nodes on high-novelty findings → quiesce → synthesize.

---

## ReviewEngine

Dimensional review engine (`lionagi.engines.review`).

Extends `Engine` with:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `dimensions` | `("correctness", "security", "performance", "maintainability")` | Review lenses; each runs one reviewer agent in parallel. |
| `reviewer_role` | `"critic"` | Casts role for dimension reviewers. |
| `verifier_role` | `"critic"` | Casts role for adversarial verifiers. |
| `synthesis_role` | `"synthesizer"` | Casts role that issues the terminal `ReviewVerdict`. |
| `verify_severities` | `("critical", "major")` | Issue severities that reactively spawn an adversarial verifier. |
| `repair_retries` | `1` | Re-prompt turns when a reviewer or verifier emits no valid event. |

Pipeline shape: fan-out (one reviewer per dimension, parallel) → adversarial verify high-severity issues → quiesce → `ReviewVerdict`.
