# Cyclium v0.3.0 - Table of Contents

> Cyclium is a framework for building and orchestrating long-running, stateful processes ("actors") in Elixir.

## Pages

- [Cyclium](readme.md)

- Guides
  - [Actors and Strategies](actors_and_strategies.md)
  - [Findings, Outputs, and the Bus](findings_and_outputs.md)
  - [Workflows](workflows.md)
  - [Dynamic Actors](dynamic_actors.md)
  - [Observability](observability.md)
  - [Distributed Operations](distributed_ops.md)
  - [Advanced Topics](advanced.md)
  - [Building Interactive Actors](interactive_actors.md)
  - [Conversation UI Guide](conversation_ui.md)

## Modules

- [Cyclium](Cyclium.md): Cyclium — an Elixir library for event-driven, expectation-based agent orchestration.
- [Cyclium.Actor](Cyclium.Actor.md): Macro and GenServer for Cyclium actors.
- [Cyclium.Actor.Server](Cyclium.Actor.Server.md): GenServer logic for Cyclium actors. Extracted from the macro to keep
the Actor module clean and testable.

- [Cyclium.ActorRegistry](Cyclium.ActorRegistry.md): Convenience functions for starting and managing actor GenServers
under the Cyclium.ActorSupervisor.

- [Cyclium.AdaptiveBudget](Cyclium.AdaptiveBudget.md): ETS-backed advisory budget tracking.
- [Cyclium.AtomGuard](Cyclium.AtomGuard.md): Bounded string-to-atom conversion for data sourced from outside the codebase
(DB-defined dynamic actor/workflow definitions, persisted workflow results,
and LLM-produced tool/output names).
- [Cyclium.Batch](Cyclium.Batch.md): Helpers for strategies that process data in grouped batches.
- [Cyclium.Bus](Cyclium.Bus.md): Event pub/sub that connects actors without coupling.
- [Cyclium.CheckpointSchema](Cyclium.CheckpointSchema.md): Macro for defining versioned checkpoint schemas with migration support.
- [Cyclium.CircuitBreaker](Cyclium.CircuitBreaker.md): ETS-backed per-expectation circuit breaker.
- [Cyclium.ConvergeResult](Cyclium.ConvergeResult.md): Returned by Strategy.converge/2. Contains outputs, findings, summary,
classification, and confidence for post-converge processing.

- [Cyclium.Conversations](Cyclium.Conversations.md): Context module for managing interactive conversations.
Provides start, claim, resolve, abandon, and query operations.

- [Cyclium.Conversations.Dispatch](Cyclium.Conversations.Dispatch.md): Creates and enqueues interactive episodes for conversation turns.
- [Cyclium.Conversations.LiveHelpers](Cyclium.Conversations.LiveHelpers.md): Reusable helpers for conversation LiveViews.
- [Cyclium.Cron](Cyclium.Cron.md): Minimal **UTC** cron expression parser and next-occurrence calculator, backing
the native `{:cron, spec}` expectation trigger.
- [Cyclium.DryRun.FindingPrefixer](Cyclium.DryRun.FindingPrefixer.md): Rewrites finding actions with prefixed keys for dry run persistence.
- [Cyclium.DynamicActor](Cyclium.DynamicActor.md): Generic actor module for DB-defined agents.
- [Cyclium.DynamicActor.Lifecycle](Cyclium.DynamicActor.Lifecycle.md): Safe lifecycle operations for dynamic actors.
- [Cyclium.DynamicActor.Loader](Cyclium.DynamicActor.Loader.md): Loads DB-defined agent definitions and starts them as `DynamicActor`
processes under `Cyclium.ActorSupervisor`.
- [Cyclium.DynamicActor.Watcher](Cyclium.DynamicActor.Watcher.md): Optional GenServer that subscribes to Bus events and automatically
refreshes dynamic actors and dynamic workflows when their DB definitions change.
- [Cyclium.DynamicWorkflow.InputResolver](Cyclium.DynamicWorkflow.InputResolver.md): Resolves declarative input_map paths against trigger and prior step data.
- [Cyclium.DynamicWorkflow.Loader](Cyclium.DynamicWorkflow.Loader.md): Loads DB-defined workflow definitions and registers them with WorkflowEngine.
- [Cyclium.Env](Cyclium.Env.md): Optional per-node **dedup identity** for sharing one database across otherwise
independent nodes that run the same actors.
- [Cyclium.EpisodeRunner](Cyclium.EpisodeRunner.md): Executes the episode loop: calls strategy callbacks, enforces budgets,
journals steps, and runs the post-converge sequence.
- [Cyclium.EpisodeRunner.Strategy](Cyclium.EpisodeRunner.Strategy.md): Behaviour for episode strategies. A strategy defines the investigation logic
for a specific expectation — how to gather data, classify, and produce outputs.

- [Cyclium.EpisodeTask](Cyclium.EpisodeTask.md): Task wrapper for episode execution. Started by the OTP runner
under Cyclium.EpisodeSupervisor (DynamicSupervisor).

- [Cyclium.Episodes](Cyclium.Episodes.md): Context for episode CRUD operations and lifecycle management.

- [Cyclium.Expectation](Cyclium.Expectation.md): Declarative configuration for a single expectation.
- [Cyclium.Exports](Cyclium.Exports.md): Durable, downloadable artifacts an actor produces for a principal (e.g. a
CSV). An export is a blob persisted to `cyclium_exports`, fetched on demand
via a signed, expiring link — scoped to the principal that requested it.
- [Cyclium.Findings](Cyclium.Findings.md): Context for finding queries and lifecycle operations.
- [Cyclium.Findings.Config](Cyclium.Findings.Config.md): ETS-backed registry for per-expectation finding configuration.
- [Cyclium.Findings.Escalation](Cyclium.Findings.Escalation.md): Time-based severity escalation rules for active findings.
- [Cyclium.Findings.FindingSweep](Cyclium.Findings.FindingSweep.md): Periodic GenServer that maintains finding health: clears expired findings
and escalates active findings based on time-based severity rules.
- [Cyclium.Gatherer](Cyclium.Gatherer.md): Behaviour for data-gathering modules used by strategy templates.
- [Cyclium.Intent.ActionPlan](Cyclium.Intent.ActionPlan.md): A structured output the synthesizer returns when interpreting user intent.
Describes what the interactive actor should do next.

- [Cyclium.Intent.AudienceTarget](Cyclium.Intent.AudienceTarget.md): For non-user-initiated conversations: who is this conversation for?

- [Cyclium.Intent.ConstraintChecks](Cyclium.Intent.ConstraintChecks.md): Evaluates generic constraints from tool signatures against tool call args.

- [Cyclium.Intent.ConversationHook](Cyclium.Intent.ConversationHook.md): Post-converge hook for interactive episodes. Called after an interactive episode
converges to
- [Cyclium.Intent.GoalEvaluator](Cyclium.Intent.GoalEvaluator.md): Called after each interactive episode converges within a conversation.
Returns whether the conversation should continue, resolve, or abandon.

- [Cyclium.Intent.GoalEvaluator.RequiredFields](Cyclium.Intent.GoalEvaluator.RequiredFields.md): Built-in evaluator: checks if all required fields have been collected
across conversation turns.

- [Cyclium.Intent.GoalEvaluator.StrategyDecides](Cyclium.Intent.GoalEvaluator.StrategyDecides.md): Built-in evaluator: the strategy/synthesizer signals resolution via
the ConvergeResult's classification or meta fields.

- [Cyclium.Intent.GoalSpec](Cyclium.Intent.GoalSpec.md): Defines what a conversation is trying to accomplish and how we know it's done.
Set at conversation creation time by a workflow step, the consuming app, or implicitly.

- [Cyclium.Intent.Origin](Cyclium.Intent.Origin.md): Describes how and why a conversation was created.

- [Cyclium.Intent.PlanGate](Cyclium.Intent.PlanGate.md): Orchestrates structural validation, signature matching, constraint checks,
and app policy callbacks for an action plan.

- [Cyclium.Intent.PlanPolicy](Cyclium.Intent.PlanPolicy.md): Behaviour for app-owned plan policy. The consuming app implements this
to control what interactive actors are allowed to do.

- [Cyclium.Intent.PlanValidator](Cyclium.Intent.PlanValidator.md): Structural validation for ActionPlans. Runtime-owned checks only.

- [Cyclium.Intent.SignatureMatcher](Cyclium.Intent.SignatureMatcher.md): Matches a tool call from an action plan against allowed tool signatures.

- [Cyclium.Intent.ToolCallStep](Cyclium.Intent.ToolCallStep.md): A single tool invocation within an action plan.

- [Cyclium.Intent.ToolSignature](Cyclium.Intent.ToolSignature.md): Declared in strategy config by the consuming app.
The runtime matches plan tool calls against these.

- [Cyclium.Intent.WorkflowTrigger](Cyclium.Intent.WorkflowTrigger.md): Sub-struct for action plans that start workflows.

- [Cyclium.Log](Cyclium.Log.md): Structured logging helpers for Cyclium.
- [Cyclium.LogProjector](Cyclium.LogProjector.md): Materializes human-readable logs from episode steps.
- [Cyclium.Migrations](Cyclium.Migrations.md): Migration dispatcher. Consumer apps create thin wrappers that delegate here.
- [Cyclium.Migrations.V1](Cyclium.Migrations.V1.md): V1: Core Phase 1 tables — episodes, steps, checkpoints, findings, outputs.
- [Cyclium.Migrations.V10](Cyclium.Migrations.V10.md): V10: Findings causality and TTL support.
- [Cyclium.Migrations.V11](Cyclium.Migrations.V11.md): V11: Episode timestamp precision and workflow ordering.
- [Cyclium.Migrations.V12](Cyclium.Migrations.V12.md): V12: Add expectation_id to findings for scoped escalation rules.
- [Cyclium.Migrations.V13](Cyclium.Migrations.V13.md): V13: Replace findings unique index with a partial index excluding superseded.
- [Cyclium.Migrations.V14](Cyclium.Migrations.V14.md): V14: Add cyclium_trigger_requests table for deferred episode execution.
- [Cyclium.Migrations.V15](Cyclium.Migrations.V15.md): V15: Interactive actors — conversations table, conversation_id on episodes
and workflow_instances, parent_episode_id on episodes, plan_preview step kind.

- [Cyclium.Migrations.V16](Cyclium.Migrations.V16.md): V16: Add principal_type to conversations, add principal columns to agent_definitions.

- [Cyclium.Migrations.V17](Cyclium.Migrations.V17.md): V17: Upgrade timestamp columns to microsecond precision.
- [Cyclium.Migrations.V18](Cyclium.Migrations.V18.md): V18: Add `source_stack` to `cyclium_episodes` and `cyclium_workflow_instances`.
- [Cyclium.Migrations.V19](Cyclium.Migrations.V19.md): V19: Convert legacy SQL Server `TEXT` columns to `nvarchar(max)` so emoji and
other non-CP1252 characters round-trip correctly. No-op on Postgres/SQLite.
- [Cyclium.Migrations.V2](Cyclium.Migrations.V2.md): V2: Episode logs table for LogProjector.
- [Cyclium.Migrations.V20](Cyclium.Migrations.V20.md): V20: Add `subject_value` column to `cyclium_workflow_instances`.
- [Cyclium.Migrations.V21](Cyclium.Migrations.V21.md): V21: Add `fence` (monotonic ownership generation) to `cyclium_work_claims`.
- [Cyclium.Migrations.V22](Cyclium.Migrations.V22.md): V22: Add an `env` dimension for cordoning work across nodes that share a DB
*and* a stack slug.
- [Cyclium.Migrations.V23](Cyclium.Migrations.V23.md): V23: Record which interactive expectation a conversation uses.
- [Cyclium.Migrations.V24](Cyclium.Migrations.V24.md): V24: Downloadable exports (`cyclium_exports`).
- [Cyclium.Migrations.V25](Cyclium.Migrations.V25.md): V25: Add an open `metadata` bag (`:map` → nvarchar(max) via TDS) to
`cyclium_episodes` and `cyclium_episode_steps`.
- [Cyclium.Migrations.V4](Cyclium.Migrations.V4.md): V4: Add archived_at to episodes and findings for soft-archive support.

- [Cyclium.Migrations.V5](Cyclium.Migrations.V5.md): V5: Unique index on episodes dedupe_key for multi-node coordination.
- [Cyclium.Migrations.V6](Cyclium.Migrations.V6.md): V6: Work claims table for lease-based distributed coordination.
- [Cyclium.Migrations.V7](Cyclium.Migrations.V7.md): V7: Dynamic agent definitions table and dry run support.
- [Cyclium.Migrations.V8](Cyclium.Migrations.V8.md): V8: Dynamic workflow definitions table.
- [Cyclium.Migrations.V9](Cyclium.Migrations.V9.md): V9: Dry run support for workflow instances.
- [Cyclium.Mode](Cyclium.Mode.md): Runtime mode management for cyclium nodes.
- [Cyclium.NodeIdentity](Cyclium.NodeIdentity.md): Resolves the identity of the current node for work claiming and trigger requests.
- [Cyclium.Output.Adapter](Cyclium.Output.Adapter.md): Behaviour for output delivery adapters (email, Slack, issues, etc.).
The consuming app provides implementations per output type.
- [Cyclium.Output.Router](Cyclium.Output.Router.md): Deduplicates and dispatches output proposals to adapters.
- [Cyclium.OutputProposal](Cyclium.OutputProposal.md): A proposed output from a strategy's converge phase.
- [Cyclium.Reconciler](Cyclium.Reconciler.md): Detects spec changes and reconciles running actors.
- [Cyclium.Recovery](Cyclium.Recovery.md): Recovers orphaned episodes after server restarts.
- [Cyclium.Runner](Cyclium.Runner.md): Behaviour for episode execution backends.
Default is `Cyclium.Runner.OTP`. Can be swapped for Oban-backed runner.

- [Cyclium.Runner.Deferred](Cyclium.Runner.Deferred.md): Runner for trigger-only mode. Instead of executing episodes locally,
writes a trigger request row for a full-mode node to pick up.

- [Cyclium.Runner.OTP](Cyclium.Runner.OTP.md): OTP-native episode runner. Uses DynamicSupervisor to run episodes as Tasks.
No Oban required — the cyclium_episodes table is itself a durable work queue.

- [Cyclium.Schemas.AgentDefinition](Cyclium.Schemas.AgentDefinition.md): Schema for DB-stored actor definitions. These are hydrated into
running `Cyclium.DynamicActor` processes at runtime by the Loader.

- [Cyclium.Schemas.Conversation](Cyclium.Schemas.Conversation.md): Schema for the `cyclium_conversations` table.
A conversation is the container for a multi-turn interactive session.

- [Cyclium.Schemas.Episode](Cyclium.Schemas.Episode.md)
- [Cyclium.Schemas.EpisodeCheckpoint](Cyclium.Schemas.EpisodeCheckpoint.md)
- [Cyclium.Schemas.EpisodeLog](Cyclium.Schemas.EpisodeLog.md)
- [Cyclium.Schemas.EpisodeStep](Cyclium.Schemas.EpisodeStep.md)
- [Cyclium.Schemas.Export](Cyclium.Schemas.Export.md): Schema for the `cyclium_exports` table — a durable, downloadable artifact an
actor produced for a principal (e.g. a CSV). Fetched on demand via a signed
link and expiring after a TTL. See `Cyclium.Exports`.

- [Cyclium.Schemas.Finding](Cyclium.Schemas.Finding.md)
- [Cyclium.Schemas.Output](Cyclium.Schemas.Output.md)
- [Cyclium.Schemas.TriggerRequest](Cyclium.Schemas.TriggerRequest.md)
- [Cyclium.Schemas.WorkClaim](Cyclium.Schemas.WorkClaim.md)
- [Cyclium.Schemas.WorkflowDefinition](Cyclium.Schemas.WorkflowDefinition.md)
- [Cyclium.Schemas.WorkflowInstance](Cyclium.Schemas.WorkflowInstance.md)
- [Cyclium.ServiceLevels](Cyclium.ServiceLevels.md): ETS-backed performance objectives tracking per expectation.
- [Cyclium.StackSlug](Cyclium.StackSlug.md): Reads the current stack slug from application config.
- [Cyclium.Strategy.Retry](Cyclium.Strategy.Retry.md): Lightweight retry helper for strategies.
- [Cyclium.Strategy.Template.Agentic.Loop](Cyclium.Strategy.Template.Agentic.Loop.md): The shared agentic loop that powers the interactive and autonomous strategy
templates. It owns the middle of the state machine — the phases neither
template needs to customize
- [Cyclium.Strategy.Template.AgenticTask](Cyclium.Strategy.Template.AgenticTask.md): Strategy template for an **autonomous, tool-calling episode** — the same
interpret → validate → execute → summarize loop as
`Cyclium.Strategy.Template.Interactive`, but with no human in the loop.
- [Cyclium.Strategy.Template.Dispatch](Cyclium.Strategy.Template.Dispatch.md): Data-driven strategy template: Gather entities → Broadcast events.
- [Cyclium.Strategy.Template.Interactive](Cyclium.Strategy.Template.Interactive.md): Strategy template for interactive actors. Implements the intent interpretation loop
- [Cyclium.Strategy.Template.ObserveClassifyConverge](Cyclium.Strategy.Template.ObserveClassifyConverge.md): Data-driven strategy template: Gather → Classify (rules) → Converge.
- [Cyclium.Strategy.Template.ObserveSynthesizeConverge](Cyclium.Strategy.Template.ObserveSynthesizeConverge.md): Data-driven strategy template: Gather → Synthesize → Converge.
- [Cyclium.Strategy.TemplateRegistry](Cyclium.Strategy.TemplateRegistry.md): Maps strategy template names (stored in `AgentDefinition.strategy_template`)
to compiled strategy modules.
- [Cyclium.Supervisor](Cyclium.Supervisor.md)
- [Cyclium.Synthesizer](Cyclium.Synthesizer.md): Behaviour for LLM synthesis integration.
The consuming app provides the implementation.

- [Cyclium.Synthesizer.Interactive](Cyclium.Synthesizer.Interactive.md): Default synthesizer for interactive actors.
- [Cyclium.Synthesizer.Interactive.LLM](Cyclium.Synthesizer.Interactive.LLM.md): Behaviour for LLM clients used by the Interactive synthesizer.
- [Cyclium.Synthesizer.PromptBuilder](Cyclium.Synthesizer.PromptBuilder.md): Builds system prompts for interactive actors from strategy_config.
- [Cyclium.Telemetry](Cyclium.Telemetry.md): Telemetry integration for Cyclium.
- [Cyclium.Terminology](Cyclium.Terminology.md): Provides configurable display labels for rendered logs and UI text.
- [Cyclium.Test.ActorCase](Cyclium.Test.ActorCase.md): Test helpers for validating actor module definitions.
- [Cyclium.Test.CheckpointMigration](Cyclium.Test.CheckpointMigration.md): Test helpers for property-based testing of checkpoint schema migrations.
- [Cyclium.Test.FakeOutputAdapter](Cyclium.Test.FakeOutputAdapter.md): In-memory fake output adapter for testing. Records deliveries
and returns configurable responses.
- [Cyclium.Test.FakeSynthesizer](Cyclium.Test.FakeSynthesizer.md): In-memory fake synthesizer for strategy testing.
Records calls and returns configured responses.
- [Cyclium.Test.OutputCase](Cyclium.Test.OutputCase.md): Test helpers for verifying output adapter contract compliance and
a `FakeOutputAdapter` for use in integration tests.
- [Cyclium.Test.StrategyCase](Cyclium.Test.StrategyCase.md): Test helpers for verifying strategy contract compliance.
- [Cyclium.Test.SynthesizerCase](Cyclium.Test.SynthesizerCase.md): Test helpers for verifying synthesizer contract compliance and
a `FakeSynthesizer` for use in strategy tests.
- [Cyclium.Test.WorkflowCase](Cyclium.Test.WorkflowCase.md): Test helpers for validating workflow definitions.
- [Cyclium.Tool](Cyclium.Tool.md): Behaviour for tool implementations.
Tools are provided by the consuming app and wrapped by ToolExec.
- [Cyclium.ToolExec](Cyclium.ToolExec.md): Wraps every tool call with: capability check, caching, redaction, journaling.
- [Cyclium.Trigger](Cyclium.Trigger.md): Typed trigger ref structs — one per trigger_type.
Strategies pattern-match on trigger type in `init/2`.

- [Cyclium.Trigger.Event](Cyclium.Trigger.Event.md)
- [Cyclium.Trigger.Interactive](Cyclium.Trigger.Interactive.md)
- [Cyclium.Trigger.Manual](Cyclium.Trigger.Manual.md)
- [Cyclium.Trigger.Schedule](Cyclium.Trigger.Schedule.md)
- [Cyclium.Trigger.Workflow](Cyclium.Trigger.Workflow.md)
- [Cyclium.TriggerRequests](Cyclium.TriggerRequests.md): Context module for deferred trigger requests.
- [Cyclium.TriggerRequests.Poller](Cyclium.TriggerRequests.Poller.md): Polls `cyclium_trigger_requests` for pending rows and dispatches them
to `Runner.OTP` for local execution.
- [Cyclium.Window](Cyclium.Window.md): Clock-aligned dedupe bucket helpers.
- [Cyclium.WorkClaims](Cyclium.WorkClaims.md): Behaviour for lease-based distributed work claiming.
- [Cyclium.WorkClaims.EctoClaims](Cyclium.WorkClaims.EctoClaims.md): Default Ecto-based work claims implementation. Works with any Ecto adapter.
- [Cyclium.WorkClaims.FakeClaims](Cyclium.WorkClaims.FakeClaims.md): In-memory work claims implementation for tests.
- [Cyclium.WorkClaims.Heartbeat](Cyclium.WorkClaims.Heartbeat.md): Periodically renews a work claim lease while an episode is executing.
- [Cyclium.Workflow](Cyclium.Workflow.md): Macro for defining multi-actor workflows.
- [Cyclium.Workflow.Config](Cyclium.Workflow.Config.md): Parsed workflow configuration generated by `use Cyclium.Workflow`.

- [Cyclium.Workflow.DAG](Cyclium.Workflow.DAG.md): Shared DAG validation for workflow step dependencies.
- [Cyclium.Workflow.StepConfig](Cyclium.Workflow.StepConfig.md): Configuration for a single workflow step, accumulated by the Workflow DSL.

- [Cyclium.WorkflowEngine](Cyclium.WorkflowEngine.md): GenServer that coordinates multi-actor workflows.
- [Cyclium.WorkflowInstances](Cyclium.WorkflowInstances.md): Context for workflow instance CRUD operations.

- Exceptions
  - [Cyclium.AtomGuard.LimitError](Cyclium.AtomGuard.LimitError.md): Raised when the atom table is too full to safely mint a new atom.