CrucibleTrace.Chain (CrucibleTrace v0.3.1)
View SourceManages a collection of causal reasoning events forming a decision chain.
A chain represents the complete reasoning trace for a single code generation task, containing all decisions, alternatives, and reasoning steps taken by the LLM.
Summary
Functions
Adds an event to the chain.
Adds multiple events to the chain.
Filters events in a chain based on a predicate function.
Finds decision points where alternatives were rejected.
Finds low confidence decisions (below threshold).
Creates a chain from a map (e.g., from JSON parsing).
Gets child events of a given event.
Gets an event by ID from the chain.
Gets all events for a given experiment_id.
Gets all events for a given stage_id.
Gets all events of a specific type from the chain.
Gets events within a time range.
Gets leaf events (events with no children).
Gets the parent event of a given event.
Gets root events (events with no parent).
Merges two chains together, combining their events.
Creates a new chain with the given name and options.
Sorts events in a chain by timestamp.
Calculates statistics about the chain.
Converts the chain to a map suitable for JSON encoding.
Validates that no circular dependencies exist in the chain.
Types
@type t() :: %CrucibleTrace.Chain{ created_at: DateTime.t(), description: String.t() | nil, events: [CrucibleTrace.Event.t()], id: String.t(), metadata: map(), name: String.t(), updated_at: DateTime.t() }
Functions
Adds an event to the chain.
Returns the updated chain with the event appended.
Adds multiple events to the chain.
Filters events in a chain based on a predicate function.
Finds decision points where alternatives were rejected.
Returns events of type :alternative_rejected with their associated decisions.
Finds low confidence decisions (below threshold).
Creates a chain from a map (e.g., from JSON parsing).
@spec get_children(t(), String.t()) :: {:ok, [CrucibleTrace.Event.t()]} | {:error, String.t()}
Gets child events of a given event.
Returns {:ok, children} with the list of child events,
or {:error, reason} if the parent event is not found.
Gets an event by ID from the chain.
Returns {:ok, event} if found, :error otherwise.
@spec get_events_by_experiment(t(), String.t()) :: [CrucibleTrace.Event.t()]
Gets all events for a given experiment_id.
@spec get_events_by_stage(t(), String.t()) :: [CrucibleTrace.Event.t()]
Gets all events for a given stage_id.
Gets all events of a specific type from the chain.
Gets events within a time range.
@spec get_leaf_events(t()) :: [CrucibleTrace.Event.t()]
Gets leaf events (events with no children).
@spec get_parent(t(), String.t()) :: {:ok, CrucibleTrace.Event.t() | nil} | {:error, String.t()}
Gets the parent event of a given event.
Returns {:ok, parent} where parent is the parent event or nil if no parent,
or {:error, reason} if the event is not found.
@spec get_root_events(t()) :: [CrucibleTrace.Event.t()]
Gets root events (events with no parent).
Merges two chains together, combining their events.
Creates a new chain with the given name and options.
Examples
iex> CrucibleTrace.Chain.new("API Endpoint Implementation")
%CrucibleTrace.Chain{name: "API Endpoint Implementation"}Sorts events in a chain by timestamp.
Calculates statistics about the chain.
Returns a map with:
- total_events: total number of events
- event_type_counts: count per event type
- avg_confidence: average confidence across all events
- duration_seconds: time from first to last event
Converts the chain to a map suitable for JSON encoding.
Validates that no circular dependencies exist in the chain.
Returns {:ok, chain} if valid, {:error, reason} otherwise.