Modules
Cyclium — an Elixir library for event-driven, expectation-based agent orchestration.
Macro and GenServer for Cyclium actors.
GenServer logic for Cyclium actors. Extracted from the macro to keep the Actor module clean and testable.
Convenience functions for starting and managing actor GenServers under the Cyclium.ActorSupervisor.
ETS-backed advisory budget tracking.
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).
Raised when the atom table is too full to safely mint a new atom.
Helpers for strategies that process data in grouped batches.
Event pub/sub that connects actors without coupling.
Macro for defining versioned checkpoint schemas with migration support.
ETS-backed per-expectation circuit breaker.
Returned by Strategy.converge/2. Contains outputs, findings, summary, classification, and confidence for post-converge processing.
Context module for managing interactive conversations. Provides start, claim, resolve, abandon, and query operations.
Creates and enqueues interactive episodes for conversation turns.
Reusable helpers for conversation LiveViews.
Minimal UTC cron expression parser and next-occurrence calculator, backing
the native {:cron, spec} expectation trigger.
Rewrites finding actions with prefixed keys for dry run persistence.
Generic actor module for DB-defined agents.
Safe lifecycle operations for dynamic actors.
Loads DB-defined agent definitions and starts them as DynamicActor
processes under Cyclium.ActorSupervisor.
Optional GenServer that subscribes to Bus events and automatically refreshes dynamic actors and dynamic workflows when their DB definitions change.
Resolves declarative input_map paths against trigger and prior step data.
Loads DB-defined workflow definitions and registers them with WorkflowEngine.
Optional per-node dedup identity for sharing one database across otherwise independent nodes that run the same actors.
Executes the episode loop: calls strategy callbacks, enforces budgets, journals steps, and runs the post-converge sequence.
Behaviour for episode strategies. A strategy defines the investigation logic for a specific expectation — how to gather data, classify, and produce outputs.
Task wrapper for episode execution. Started by the OTP runner under Cyclium.EpisodeSupervisor (DynamicSupervisor).
Context for episode CRUD operations and lifecycle management.
Declarative configuration for a single expectation.
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.
Context for finding queries and lifecycle operations.
ETS-backed registry for per-expectation finding configuration.
Time-based severity escalation rules for active findings.
Periodic GenServer that maintains finding health: clears expired findings and escalates active findings based on time-based severity rules.
Behaviour for data-gathering modules used by strategy templates.
A structured output the synthesizer returns when interpreting user intent. Describes what the interactive actor should do next.
For non-user-initiated conversations: who is this conversation for?
Evaluates generic constraints from tool signatures against tool call args.
Post-converge hook for interactive episodes. Called after an interactive episode converges to
Called after each interactive episode converges within a conversation. Returns whether the conversation should continue, resolve, or abandon.
Built-in evaluator: checks if all required fields have been collected across conversation turns.
Built-in evaluator: the strategy/synthesizer signals resolution via the ConvergeResult's classification or meta fields.
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.
Describes how and why a conversation was created.
Orchestrates structural validation, signature matching, constraint checks, and app policy callbacks for an action plan.
Behaviour for app-owned plan policy. The consuming app implements this to control what interactive actors are allowed to do.
Structural validation for ActionPlans. Runtime-owned checks only.
Matches a tool call from an action plan against allowed tool signatures.
A single tool invocation within an action plan.
Declared in strategy config by the consuming app. The runtime matches plan tool calls against these.
Sub-struct for action plans that start workflows.
Structured logging helpers for Cyclium.
Materializes human-readable logs from episode steps.
Migration dispatcher. Consumer apps create thin wrappers that delegate here.
V1: Core Phase 1 tables — episodes, steps, checkpoints, findings, outputs.
V10: Findings causality and TTL support.
V11: Episode timestamp precision and workflow ordering.
V12: Add expectation_id to findings for scoped escalation rules.
V13: Replace findings unique index with a partial index excluding superseded.
V14: Add cyclium_trigger_requests table for deferred episode execution.
V15: Interactive actors — conversations table, conversation_id on episodes and workflow_instances, parent_episode_id on episodes, plan_preview step kind.
V16: Add principal_type to conversations, add principal columns to agent_definitions.
V17: Upgrade timestamp columns to microsecond precision.
V18: Add source_stack to cyclium_episodes and cyclium_workflow_instances.
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.
V2: Episode logs table for LogProjector.
V20: Add subject_value column to cyclium_workflow_instances.
V21: Add fence (monotonic ownership generation) to cyclium_work_claims.
V22: Add an env dimension for cordoning work across nodes that share a DB
and a stack slug.
V23: Record which interactive expectation a conversation uses.
V24: Downloadable exports (cyclium_exports).
V25: Add an open metadata bag (:map → nvarchar(max) via TDS) to
cyclium_episodes and cyclium_episode_steps.
V4: Add archived_at to episodes and findings for soft-archive support.
V5: Unique index on episodes dedupe_key for multi-node coordination.
V6: Work claims table for lease-based distributed coordination.
V7: Dynamic agent definitions table and dry run support.
V8: Dynamic workflow definitions table.
V9: Dry run support for workflow instances.
Runtime mode management for cyclium nodes.
Resolves the identity of the current node for work claiming and trigger requests.
Behaviour for output delivery adapters (email, Slack, issues, etc.). The consuming app provides implementations per output type.
Deduplicates and dispatches output proposals to adapters.
A proposed output from a strategy's converge phase.
Detects spec changes and reconciles running actors.
Recovers orphaned episodes after server restarts.
Behaviour for episode execution backends.
Default is Cyclium.Runner.OTP. Can be swapped for Oban-backed runner.
Runner for trigger-only mode. Instead of executing episodes locally, writes a trigger request row for a full-mode node to pick up.
OTP-native episode runner. Uses DynamicSupervisor to run episodes as Tasks. No Oban required — the cyclium_episodes table is itself a durable work queue.
Schema for DB-stored actor definitions. These are hydrated into
running Cyclium.DynamicActor processes at runtime by the Loader.
Schema for the cyclium_conversations table.
A conversation is the container for a multi-turn interactive session.
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.
ETS-backed performance objectives tracking per expectation.
Reads the current stack slug from application config.
Lightweight retry helper for strategies.
Data-driven strategy template: Gather entities → Broadcast events.
Strategy template for interactive actors. Implements the intent interpretation loop
Data-driven strategy template: Gather → Classify (rules) → Converge.
Data-driven strategy template: Gather → Synthesize → Converge.
Maps strategy template names (stored in AgentDefinition.strategy_template)
to compiled strategy modules.
Behaviour for LLM synthesis integration. The consuming app provides the implementation.
Default synthesizer for interactive actors.
Behaviour for LLM clients used by the Interactive synthesizer.
Builds system prompts for interactive actors from strategy_config.
Telemetry integration for Cyclium.
Provides configurable display labels for rendered logs and UI text.
Test helpers for validating actor module definitions.
Test helpers for property-based testing of checkpoint schema migrations.
In-memory fake output adapter for testing. Records deliveries and returns configurable responses.
In-memory fake synthesizer for strategy testing. Records calls and returns configured responses.
Test helpers for verifying output adapter contract compliance and
a FakeOutputAdapter for use in integration tests.
Test helpers for verifying strategy contract compliance.
Test helpers for verifying synthesizer contract compliance and
a FakeSynthesizer for use in strategy tests.
Test helpers for validating workflow definitions.
Behaviour for tool implementations. Tools are provided by the consuming app and wrapped by ToolExec.
Wraps every tool call with: capability check, caching, redaction, journaling.
Typed trigger ref structs — one per trigger_type.
Strategies pattern-match on trigger type in init/2.
Context module for deferred trigger requests.
Polls cyclium_trigger_requests for pending rows and dispatches them
to Runner.OTP for local execution.
Clock-aligned dedupe bucket helpers.
Behaviour for lease-based distributed work claiming.
Default Ecto-based work claims implementation. Works with any Ecto adapter.
In-memory work claims implementation for tests.
Periodically renews a work claim lease while an episode is executing.
Macro for defining multi-actor workflows.
Parsed workflow configuration generated by use Cyclium.Workflow.
Shared DAG validation for workflow step dependencies.
Configuration for a single workflow step, accumulated by the Workflow DSL.
GenServer that coordinates multi-actor workflows.
Context for workflow instance CRUD operations.