marla.config

The experiment YAML schema and its loader/validator. See Configuration reference for a narrative field-by-field reference.

Pydantic models for the MARLA experiment configuration schema.

These models are the authoritative, validated representation of an experiment YAML file (see spec section 19). Every field name mirrors the YAML key exactly. Unknown keys are rejected (extra="forbid") so typos fail fast instead of being silently ignored.

class marla.config.models.ActionEncoderConfig(*, hidden_size, action_type_embedding_size)[source]

Bases: MarlaBaseModel

Parameters:

hidden_size (int)
action_type_embedding_size (int)

action_type_embedding_size: int

hidden_size: int

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class marla.config.models.AgentIdentityConfig(*, alias, jid, password_env=None)[source]

Bases: MarlaBaseModel

Identity of a SPADE agent: alias, JID, and where to find its password.

Parameters:

alias (str)
jid (str)
password_env (str | None)

alias: str

jid: str

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

password_env: str | None

class marla.config.models.Config(*, schema_version, experiment, execution, device='auto', xmpp, environment, objective, policy, consultation, rl_orchestrator, gatekeeper=None, agents=<factory>, metrics=<factory>, reproducibility=<factory>)[source]

Bases: MarlaBaseModel

Parameters:

schema_version (str)
experiment (ExperimentConfig)
execution (ExecutionConfig)
device (Literal['cpu', 'gpu', 'auto'])
xmpp (XmppConfig)
environment (EnvironmentConfig)
objective (ObjectiveConfig)
policy (PolicyConfig)
consultation (ConsultationConfig)
rl_orchestrator (AgentIdentityConfig)
gatekeeper (AgentIdentityConfig | None)
agents (list[PlanMakerAgentConfig])
metrics (MetricsConfig)
reproducibility (ReproducibilityConfig)

agents: list[PlanMakerAgentConfig]

consultation: ConsultationConfig

device: Literal['cpu', 'gpu', 'auto']

environment: EnvironmentConfig

execution: ExecutionConfig

experiment: ExperimentConfig

gatekeeper: AgentIdentityConfig | None

metrics: MetricsConfig

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

objective: ObjectiveConfig

policy: PolicyConfig

reproducibility: ReproducibilityConfig

rl_orchestrator: AgentIdentityConfig

schema_version: str

xmpp: XmppConfig

class marla.config.models.ConsultationConfig(*, mode, cost=0.0, max_schema_revisions=None)[source]

Bases: MarlaBaseModel

Parameters:

mode (Literal['disabled', 'learned'])
cost (float)
max_schema_revisions (int | None)

cost: float

max_schema_revisions: int | None

mode: Literal['disabled', 'learned']

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class marla.config.models.EnvironmentConfig(*, mode='simulation', scenario, max_episode_steps)[source]

Bases: MarlaBaseModel

Parameters:

mode (Literal['simulation'])
scenario (str)
max_episode_steps (int)

max_episode_steps: int

mode: Literal['simulation']

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

scenario: str

class marla.config.models.ExecutionConfig(*, mode)[source]

Bases: MarlaBaseModel

Parameters:: mode (Literal['local', 'distributed'])

mode: Literal['local', 'distributed']

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class marla.config.models.ExperimentConfig(*, name, run_id=None, phase='training', seed)[source]

Bases: MarlaBaseModel

Parameters:

name (str)
run_id (str | None)
phase (Literal['training', 'evaluation'])
seed (int)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

phase: Literal['training', 'evaluation']

run_id: str | None

seed: int

class marla.config.models.GraphEncoderConfig(*, type='graphsage', hidden_size, layers)[source]

Bases: MarlaBaseModel

Parameters:

type (Literal['graphsage'])
hidden_size (int)
layers (int)

hidden_size: int

layers: int

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

type: Literal['graphsage']

class marla.config.models.MarlaBaseModel[source]

Bases: BaseModel

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class marla.config.models.MetricsConfig(*, output_directory='runs', record_decisions=True, eval_episodes=0, eval_every_rollouts=1)[source]

Bases: MarlaBaseModel

Parameters:

output_directory (str)
record_decisions (bool)
eval_episodes (Annotated[int, Ge(ge=0)])
eval_every_rollouts (Annotated[int, Gt(gt=0)])

eval_episodes: int

eval_every_rollouts: int

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_directory: str

record_decisions: bool

class marla.config.models.ObjectiveConfig(*, type, description, completion_reward=1.0, premature_finish_penalty=-1.0)[source]

Bases: MarlaBaseModel

Parameters:

type (Literal['capture_target'])
description (str)
completion_reward (float)
premature_finish_penalty (float)

completion_reward: float

description: str

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

premature_finish_penalty: float

type: Literal['capture_target']

class marla.config.models.PPOConfig(*, total_environment_steps, rollout_steps, epochs, minibatch_sequences, gamma, gae_lambda, clip_epsilon, value_coefficient, query_entropy_coefficient, action_entropy_coefficient, max_grad_norm, learning_rate)[source]

Bases: MarlaBaseModel

Parameters:

total_environment_steps (Annotated[int, Gt(gt=0)])
rollout_steps (Annotated[int, Gt(gt=0)])
epochs (Annotated[int, Gt(gt=0)])
minibatch_sequences (Annotated[int, Gt(gt=0)])
gamma (Annotated[float, Gt(gt=0), Le(le=1)])
gae_lambda (Annotated[float, Ge(ge=0), Le(le=1)])
clip_epsilon (Annotated[float, Gt(gt=0)])
value_coefficient (Annotated[float, Ge(ge=0)])
query_entropy_coefficient (Annotated[float, Ge(ge=0)])
action_entropy_coefficient (Annotated[float, Ge(ge=0)])
max_grad_norm (Annotated[float, Gt(gt=0)])
learning_rate (Annotated[float, Gt(gt=0)])

action_entropy_coefficient: float

clip_epsilon: float

epochs: int

gae_lambda: float

gamma: float

learning_rate: float

max_grad_norm: float

minibatch_sequences: int

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

query_entropy_coefficient: float

rollout_steps: int

total_environment_steps: int

value_coefficient: float

class marla.config.models.PlanMakerAgentConfig(*, alias, jid, password_env=None, role, model, prompt_version, knowledge)[source]

Bases: MarlaBaseModel

Parameters:

alias (str)
jid (str)
password_env (str | None)
role (Literal['plan_maker'])
model (PlanMakerModelConfig)
prompt_version (str)
knowledge (PlanMakerKnowledgeConfig)

alias: str

jid: str

knowledge: PlanMakerKnowledgeConfig

model: PlanMakerModelConfig

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

password_env: str | None

prompt_version: str

role: Literal['plan_maker']

class marla.config.models.PlanMakerKnowledgeConfig(*, path, version)[source]

Bases: MarlaBaseModel

Parameters:

path (str)
version (str)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

path: str

version: str

class marla.config.models.PlanMakerModelConfig(*, backend, name, max_new_tokens=512)[source]

Bases: MarlaBaseModel

Parameters:

backend (Literal['local', 'remote'])
name (str)
max_new_tokens (int)

backend: Literal['local', 'remote']

max_new_tokens: int

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

class marla.config.models.PolicyConfig(*, algorithm='recurrent_ppo', graph_encoder, action_encoder, recurrent, ppo)[source]

Bases: MarlaBaseModel

Parameters:

algorithm (Literal['recurrent_ppo'])
graph_encoder (GraphEncoderConfig)
action_encoder (ActionEncoderConfig)
recurrent (RecurrentConfig)
ppo (PPOConfig)

action_encoder: ActionEncoderConfig

algorithm: Literal['recurrent_ppo']

graph_encoder: GraphEncoderConfig

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ppo: PPOConfig

recurrent: RecurrentConfig

class marla.config.models.RecurrentConfig(*, hidden_size, sequence_length)[source]

Bases: MarlaBaseModel

Parameters:

hidden_size (Annotated[int, Gt(gt=0)])
sequence_length (Annotated[int, Gt(gt=0)])

hidden_size: int

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sequence_length: int

class marla.config.models.ReproducibilityConfig(*, deterministic_torch=True)[source]

Bases: MarlaBaseModel

Parameters:: deterministic_torch (bool)

deterministic_torch: bool

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class marla.config.models.XmppConfig(*, server)[source]

Bases: MarlaBaseModel

Parameters:: server (str)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

server: str

Load, parse, and hash MARLA experiment configuration files.

exception marla.config.loader.ConfigError(problems)[source]

Bases: Exception

Raised when an experiment configuration file is invalid.

Carries the full list of problems (Pydantic validation errors and/or semantic validation problems) so callers such as marla validate can print them all at once instead of failing on the first one.

Parameters:: problems (list[str])

marla.config.loader.config_hash(config)[source]

Stable SHA-256 hash of the resolved configuration, for metadata.json.

Parameters:: config (Config)
Return type:: str

marla.config.loader.load_config(path)[source]

Load and validate an experiment configuration file.

Performs both Pydantic schema validation and the semantic checks in marla.config.validation (e.g. scenario file existence).

Parameters:: path (str | Path)
Return type:: Config

marla.config.loader.parse_config(raw)[source]

Parse an already-loaded YAML dict into a validated Config.

Parameters:: raw (dict[str, Any])
Return type:: Config

marla.config.loader.redacted_config_dict(config)[source]

Return a plain-dict dump of the config with any secret-shaped keys redacted.

MARLA never stores actual secrets in configuration (only environment variable names via password_env), so this is a defensive measure against future fields rather than something expected to trigger today.

Parameters:: config (Config)
Return type:: dict[str, Any]

Validation helpers that go beyond what Pydantic field types can express.

Structural/schema validation lives in marla.config.models. This module covers cross-cutting or filesystem-dependent checks (e.g. does the scenario file actually exist) that are still worth surfacing to marla validate but are not part of the Pydantic schema itself.

marla.config.validation.validate_config_semantics(config, config_dir)[source]

Run all filesystem/cross-cutting checks and return combined problems.

Parameters:

config (Config)
config_dir (Path)

Return type:

list[str]

marla.config.validation.validate_knowledge_references(config)[source]

Sanity-check agents[].knowledge.path values.

Accepted forms: package://<path-inside-marla-package> or a plain filesystem path. Actual resolution/loading happens in marla.knowledge.retriever (Milestone 8); here we only reject obviously malformed references early.

Parameters:: config (Config)
Return type:: list[str]

marla.config.validation.validate_scenario_reference(config, config_dir)[source]

Return a list of human-readable warnings/errors about the scenario reference.

NASimEmu treats a scenario ending in .yaml as a path to a static scenario file, and any other string as the name of a procedurally generated benchmark looked up at runtime. We can only meaningfully check existence for the file case here.

Parameters:

config (Config)
config_dir (Path)

Return type:

list[str]

Starter configuration templates for marla init (see marla.cli).

These are deliberately scaled down from examples/ (which mirror the spec’s production-realistic settings): the goal here is a fast first run that proves the platform works end-to-end, not a real research result.

marla.config.templates.find_nasimemu_scenario(start, max_levels=5)[source]

Search start and its ancestors for the bundled NASimEmu scenario used by the templates.

NASimEmu is a separate checked-out project alongside this repo, not part of the installed marla package, so there is no fixed path to it – this mirrors how a developer would locate it by eye, starting from the current working directory.

Parameters:

start (Path)
max_levels (int)

Return type:

Path | None

marla.config.templates.render_templates(scenario_path)[source]

Render every template with scenario_path substituted in.

Parameters:: scenario_path (str)
Return type:: dict[str, str]