Struct RalphConfig 

pub struct RalphConfig {

    pub event_loop: EventLoopConfig,
    pub cli: CliConfig,
    pub core: CoreConfig,
    pub hats: HashMap<String, HatConfig>,
    pub events: HashMap<String, EventMetadata>,
    pub agent: Option<String>,
    pub agent_priority: Vec<String>,
    pub prompt_file: Option<String>,
    pub completion_promise: Option<String>,
    pub max_iterations: Option<u32>,
    pub max_runtime: Option<u64>,
    pub max_cost: Option<f64>,
    pub verbose: bool,
    pub archive_prompts: bool,
    pub enable_metrics: bool,
    pub max_tokens: Option<u32>,
    pub retry_delay: Option<u32>,
    pub adapters: AdaptersConfig,
    pub suppress_warnings: bool,
    pub tui: TuiConfig,
    pub memories: MemoriesConfig,
    pub tasks: TasksConfig,
    pub hooks: HooksConfig,
    pub skills: SkillsConfig,
    pub features: FeaturesConfig,
    pub robot: RobotConfig,
}

Top-level configuration for Ralph Orchestrator.

Supports both v1.x flat format and v2.0 nested format:

• v1: agent: claude, max_iterations: 100
• v2: cli: { backend: claude }, event_loop: { max_iterations: 100 }

Fields

event_loop: EventLoopConfig

Event loop configuration (v2 nested style).

cli: CliConfig

CLI backend configuration (v2 nested style).

core: CoreConfig

Core paths and settings shared across all hats.

hats: HashMap<String, HatConfig>

Custom hat definitions (optional). If empty, default planner and builder hats are used.

events: HashMap<String, EventMetadata>

Event metadata definitions (optional). Defines what each event topic means, enabling auto-derived instructions. If a hat uses custom events, define them here for proper behavior injection.

agent: Option<String>

V1 field: Backend CLI (maps to cli.backend). Values: “claude”, “kiro”, “gemini”, “codex”, “amp”, “pi”, “auto”, or “custom”.

agent_priority: Vec<String>

V1 field: Fallback order for auto-detection.

prompt_file: Option<String>

V1 field: Path to prompt file (maps to event_loop.prompt_file).

completion_promise: Option<String>

V1 field: Completion detection string (maps to event_loop.completion_promise).

max_iterations: Option<u32>

V1 field: Maximum loop iterations (maps to event_loop.max_iterations).

max_runtime: Option<u64>

V1 field: Maximum runtime in seconds (maps to event_loop.max_runtime_seconds).

max_cost: Option<f64>

V1 field: Maximum cost in USD (maps to event_loop.max_cost_usd).

verbose: bool

Enable verbose output.

archive_prompts: bool

Archive prompts after completion (DEFERRED: warn if enabled).

enable_metrics: bool

Enable metrics collection (DEFERRED: warn if enabled).

max_tokens: Option<u32>

V1 field: Token limits (DROPPED: controlled by CLI tool).

retry_delay: Option<u32>

V1 field: Retry delay (DROPPED: handled differently in v2).

adapters: AdaptersConfig

V1 adapter settings (partially supported).

suppress_warnings: bool

Suppress all warnings (for CI environments).

tui: TuiConfig

TUI configuration.

memories: MemoriesConfig

Memories configuration for persistent learning across sessions.

tasks: TasksConfig

Tasks configuration for runtime work tracking.

hooks: HooksConfig

Lifecycle hooks configuration.

skills: SkillsConfig

Skills configuration for the skill discovery and injection system.

features: FeaturesConfig

Feature flags for optional capabilities.

robot: RobotConfig

RObot (Ralph-Orchestrator bot) configuration for Telegram-based interaction.

Implementations

impl RalphConfig

pub fn from_file(path: impl AsRef<Path>) -> Result<Self, ConfigError>

Loads configuration from a YAML file.

pub fn parse_yaml(content: &str) -> Result<Self, ConfigError>

Parses configuration from a YAML string.

pub fn normalize(&mut self)

Normalizes v1 flat fields into v2 nested structure.

V1 flat fields take precedence over v2 nested fields when both are present. This allows users to use either format or mix them.

pub fn validate(&self) -> Result<Vec<ConfigWarning>, ConfigError>

Validates the configuration and returns warnings.

This method checks for:

• Deferred features that are enabled (archive_prompts, enable_metrics)
• Dropped fields that are present (max_tokens, retry_delay, tool_permissions)
• Ambiguous trigger routing across custom hats
• Mutual exclusivity of prompt and prompt_file

Returns a list of warnings that should be displayed to the user.

pub fn effective_backend(&self) -> &str

Gets the effective backend name, resolving “auto” using the priority list.

pub fn get_agent_priority(&self) -> Vec<&str>

Returns the agent priority list for auto-detection. If empty, returns the default priority order.

pub fn adapter_settings(&self, backend: &str) -> &AdapterSettings

Gets the adapter settings for a specific backend.

Trait Implementations

impl Clone for RalphConfig

fn clone(&self) -> RalphConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RalphConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for RalphConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for RalphConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for RalphConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.