Crucible.TraceIntegration (CrucibleFramework v0.5.2)

View Source

Integration module for crucible_trace within the experiment pipeline.

This module provides helpers for managing trace chains throughout the experiment lifecycle, including:

  • Creating and initializing trace chains
  • Emitting stage transition events
  • Capturing decision points and alternatives
  • Persisting and exporting traces

Usage

Traces are automatically managed when enabled in the experiment configuration. Each stage can emit trace events to capture its decision-making process.

Event Types

The following event types are emitted by the pipeline:

  • :stage_start - When a stage begins execution
  • :stage_complete - When a stage completes successfully
  • :stage_failed - When a stage encounters an error
  • :hypothesis_formed - When forming a hypothesis about approach
  • :pattern_applied - When applying a known pattern
  • :alternative_considered - When considering alternatives
  • :decision_made - When making a final decision

Example

# In a stage implementation
ctx = TraceIntegration.emit_event(
  ctx,
  :hypothesis_formed,
  "Use ensemble for improved accuracy",
  "Multiple models can provide better consensus",
  alternatives: ["Single model", "Sequential cascade"],
  confidence: 0.85
)

Summary

Types

trace_chain()
trace_event()

Functions

confidence_stats(arg1)

Calculate confidence statistics from the trace.

emit_decision(ctx, decision, reasoning, alternatives, confidence)

Emit a decision event with alternatives.

emit_event(ctx, type, decision, reasoning)

Emit a trace event to the current chain.

emit_event(ctx, type, decision, reasoning, opts)
emit_stage_complete(ctx, stage_name, results \\ %{})

Emit a stage completion event.

emit_stage_failed(ctx, stage_name, error)

Emit a stage failure event.

emit_stage_start(ctx, stage_name, stage_opts \\ %{})

Emit a stage start event.

event_count(arg1)

Get event count from the trace chain.

export_html(arg1)

Generate an HTML visualization of the trace.

export_json(arg1)

Export the trace chain to JSON.

filter_events(arg1, type)

Filter trace events by type.

init_trace(ctx, experiment_name)

Initialize a new trace chain for an experiment.

last_event(arg1)

Get the most recent event from the trace.

load_trace(path)

Load a trace from disk.

save_trace(arg1, path)

Save the trace to disk.

tracing_enabled?(arg1)

Check if tracing is enabled for the context.

Types

trace_chain()

@type trace_chain() :: CrucibleTrace.Chain.t()

trace_event()

@type trace_event() :: CrucibleTrace.Event.t()

Functions

confidence_stats(arg1)

@spec confidence_stats(Crucible.Context.t()) :: map()

Calculate confidence statistics from the trace.

Returns statistics about confidence levels across all decisions.

emit_decision(ctx, decision, reasoning, alternatives, confidence)

@spec emit_decision(
  Crucible.Context.t(),
  String.t(),
  String.t(),
  [String.t()],
  float()
) ::
  Crucible.Context.t()

Emit a decision event with alternatives.

Captures a decision point where alternatives were considered.

emit_event(ctx, type, decision, reasoning)

Emit a trace event to the current chain.

If tracing is not enabled (trace is nil), returns the context unchanged.

Parameters

  • ctx - The current context
  • type - Event type atom
  • decision - What was decided
  • reasoning - Why this decision was made
  • opts - Additional event options

Options

  • :alternatives - List of alternatives considered
  • :confidence - Confidence level (0.0-1.0)
  • :metadata - Additional metadata map
  • :code_section - Related code section
  • :spec_reference - Related specification reference

emit_event(ctx, type, decision, reasoning, opts)

@spec emit_event(Crucible.Context.t(), atom(), String.t(), String.t(), keyword()) ::
  Crucible.Context.t()

emit_stage_complete(ctx, stage_name, results \\ %{})

@spec emit_stage_complete(Crucible.Context.t(), atom(), map()) :: Crucible.Context.t()

Emit a stage completion event.

Captures successful completion of a pipeline stage.

emit_stage_failed(ctx, stage_name, error)

@spec emit_stage_failed(Crucible.Context.t(), atom(), term()) :: Crucible.Context.t()

Emit a stage failure event.

Captures when a pipeline stage encounters an error.

emit_stage_start(ctx, stage_name, stage_opts \\ %{})

@spec emit_stage_start(Crucible.Context.t(), atom(), map()) :: Crucible.Context.t()

Emit a stage start event.

Captures the beginning of a pipeline stage execution.

event_count(arg1)

@spec event_count(Crucible.Context.t()) :: non_neg_integer()

Get event count from the trace chain.

export_html(arg1)

@spec export_html(Crucible.Context.t()) :: String.t() | nil

Generate an HTML visualization of the trace.

Returns the HTML content for visualizing the trace chain, or nil if tracing is not enabled.

export_json(arg1)

@spec export_json(Crucible.Context.t()) :: String.t() | nil

Export the trace chain to JSON.

Returns the JSON representation of the trace chain, or nil if tracing is not enabled.

filter_events(arg1, type)

@spec filter_events(Crucible.Context.t(), atom()) :: [trace_event()]

Filter trace events by type.

Returns all events of a specific type from the trace chain.

init_trace(ctx, experiment_name)

@spec init_trace(Crucible.Context.t(), String.t()) :: Crucible.Context.t()

Initialize a new trace chain for an experiment.

Creates a new trace chain and adds it to the context.

last_event(arg1)

@spec last_event(Crucible.Context.t()) :: trace_event() | nil

Get the most recent event from the trace.

load_trace(path)

@spec load_trace(String.t()) ::
  {:ok, trace_chain()}
  | {:error, {:missing_dependency, :crucible_trace} | term()}

Load a trace from disk.

Loads a previously saved trace chain from the filesystem.

save_trace(arg1, path)

@spec save_trace(Crucible.Context.t(), String.t()) :: :ok | {:error, term()}

Save the trace to disk.

Persists the trace chain to the filesystem.

tracing_enabled?(arg1)

@spec tracing_enabled?(Crucible.Context.t()) :: boolean()

Check if tracing is enabled for the context.