Beamlens.Coordinator (beamlens v0.3.1)

View Source

GenServer that correlates notifications from operators into insights.

Static Supervision

The Coordinator is started as a static, always-running supervised process. It waits in :idle status until invoked, then runs its LLM loop.

Notification States

  • :unread - New notification, not yet processed
  • :acknowledged - Currently being analyzed
  • :resolved - Processed (correlated into insight or dismissed)

Running Analysis with run/2

For one-shot analysis, use run/2 which invokes the static coordinator:

{:ok, result} = Beamlens.Coordinator.run(%{reason: "memory alert triggered"})

# result contains:
# %{insights: [...], operator_results: [...]}

Status

Coordinator has a run status:

  • :idle - Waiting for invocation
  • :running - LLM loop is active

Summary

Functions

await(server, timeout \\ 300_000)

Blocks until the coordinator completes its analysis.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

run(opts)

Runs a one-shot coordinator analysis and returns results.

run(context, opts)
run(pid, context, opts)

Invokes the static coordinator process directly.

start_link(opts)

Starts the coordinator process.

status(server)

Returns the current coordinator status.

Functions

await(server, timeout \\ 300_000)

Blocks until the coordinator completes its analysis.

Returns

  • {:ok, result} - Analysis completed
  • {:error, :already_awaiting} - Another process is already awaiting

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

run(opts)

Runs a one-shot coordinator analysis and returns results.

Invokes the static coordinator and blocks until analysis is complete. Raises ArgumentError if the coordinator is not started.

Arguments

  • context - Map with context for the investigation (e.g., %{reason: "memory alert"})
  • opts - Options passed to coordinator

Options

  • :context - Map with context (alternative to first argument)
  • :notifications - List of Notification structs to analyze (default: [])
  • :puck_client - Optional Puck.Client to use instead of BAML
  • :max_iterations - Maximum iterations before stopping (default: 25)
  • :timeout - Timeout for await in milliseconds (default: 300_000)
  • :skills - List of skill atoms to make available (default: configured operators)

Returns

  • {:ok, result} - Analysis completed successfully
  • {:error, reason} - Analysis failed

Result Structure

%{
  insights: [Insight.t()],
  operator_results: [map()]
}

Examples

# With specific skills (no pre-configuration needed)
{:ok, result} = Beamlens.Coordinator.run(%{reason: "memory alert"},
  skills: [Beamlens.Skill.Beam, Beamlens.Skill.Ets, Beamlens.Skill.Os]
)

# Use all builtins when no operators configured
{:ok, result} = Beamlens.Coordinator.run(%{reason: "health check"})

# Context in opts
{:ok, result} = Beamlens.Coordinator.run(context: %{reason: "memory alert"})

# With existing notifications
{:ok, result} = Beamlens.Coordinator.run(%{reason: "investigating spike"},
  notifications: existing_notifications
)

# With custom LLM provider
{:ok, result} = Beamlens.Coordinator.run(%{reason: "health check"},
  client_registry: %{primary: "Ollama", clients: [...]}
)

run(context, opts)

run(pid, context, opts)

Invokes the static coordinator process directly.

Use this when you have a reference to the coordinator and want to run analysis on it. The coordinator queues the request if already running.

start_link(opts)

Starts the coordinator process.

Options

  • :name - Optional process name for registration (default: nil, no registration)
  • :client_registry - Optional LLM provider configuration map
  • :puck_client - Optional Puck.Client to use instead of BAML
  • :compaction_max_tokens - Token threshold for compaction (default: 50_000)
  • :compaction_keep_last - Messages to keep verbatim after compaction (default: 5)

status(server)

Returns the current coordinator status.