Configuration

MAS-Aviary is configured through a set of YAML files in the config/ directory. This page documents every configuration file and its fields.

aviary_run.yaml

The primary runtime configuration file. Controls LLM settings, MCP server connection, and general run parameters.

# LLM Configuration
llm:
  model_id: "..."          # HuggingFace model ID or API model name
  max_new_tokens: 4096     # Maximum tokens per LLM response
  temperature: 0.7         # Sampling temperature
  provider: "transformers" # LLM provider backend

# MCP Server Configuration
mcp:
  url: "http://localhost:8600"  # Aviary MCP server URL
  transport: "streamable-http"  # MCP transport protocol
  timeout: 120                  # Request timeout in seconds
  retries: 3                    # Number of retry attempts

# Run Configuration
run:
  combination: "aviary_sequential_iterative_feedback"
  output_dir: "results/"
  log_level: "INFO"

LLM section:

model_id – The model identifier. For local models, this is a HuggingFace repo path. For API models, the provider’s model name.
max_new_tokens – Upper bound on generated tokens per call.
temperature – Controls randomness. Lower values produce more deterministic outputs.
provider – Backend to use (transformers, openai, etc.).

MCP section:

url – Full URL to the Aviary MCP server.
transport – Protocol transport. Use streamable-http for HTTP-based MCP.
timeout – Per-request timeout in seconds.
retries – Automatic retry count for transient failures.

aviary_sequential.yaml

Configuration for the Sequential organizational structure.

pipeline:
  template: "default"
  stages:
    - name: "initial_sizing"
      agent: "sizing_agent"
      max_steps: 10
    - name: "aerodynamic_analysis"
      agent: "aero_agent"
      max_steps: 15
    - name: "propulsion_optimization"
      agent: "propulsion_agent"
      max_steps: 15
    - name: "final_evaluation"
      agent: "eval_agent"
      max_steps: 10

context:
  pass_full_history: true   # Each stage sees all prior outputs
  summarize_prior: false    # If true, summarize instead of full pass

pipeline.template – Named template that defines the stage ordering.
pipeline.stages – Ordered list of stages. Each has a name, assigned agent, and max_steps limit.
context.pass_full_history – When true, each stage receives the concatenated outputs of all preceding stages.
context.summarize_prior – When true, prior outputs are summarized before being passed to the next stage.

aviary_networked.yaml

Configuration for the Networked organizational structure.

workflow:
  phases:
    - name: "explore"
      max_rounds: 5
      agents: ["sizing_agent", "aero_agent", "propulsion_agent"]
    - name: "refine"
      max_rounds: 10
      agents: ["sizing_agent", "aero_agent", "propulsion_agent"]
    - name: "converge"
      max_rounds: 3
      agents: ["eval_agent"]

blackboard:
  claiming_mode: "shared"    # "shared" or "exclusive"
  sections:
    - "parameters"
    - "evaluation"
    - "proposals"
    - "consensus"

termination:
  max_total_rounds: 30
  convergence_threshold: 0.01

workflow.phases – Named phases executed in order. Each phase lists participating agents and a max_rounds limit.
blackboard.claiming_mode – Controls task ownership:
- shared – Multiple agents can read and act on the same entry.
- exclusive – An entry is claimed by one agent; others skip it.
blackboard.sections – Named sections of the blackboard. Agents post and read from specific sections.
termination.max_total_rounds – Hard limit on total rounds across all phases.
termination.convergence_threshold – If metric change between rounds drops below this value, the workflow terminates early.

aviary_graph.yaml

Configuration for the Graph-Routed operational handler.

graph:
  initial_state: "start"
  states:
    - name: "start"
      agent: "sizing_agent"
      action: "initial_sizing"
    - name: "refine_aero"
      agent: "aero_agent"
      action: "refine_aerodynamics"
    - name: "refine_propulsion"
      agent: "propulsion_agent"
      action: "refine_propulsion"
    - name: "evaluate"
      agent: "eval_agent"
      action: "evaluate_design"
    - name: "done"
      terminal: true

  transitions:
    - from: "start"
      to: "refine_aero"
      condition: "fuel_burned > 15000"
    - from: "start"
      to: "refine_propulsion"
      condition: "fuel_burned <= 15000"
    - from: "refine_aero"
      to: "evaluate"
      condition: "always"
    - from: "refine_propulsion"
      to: "evaluate"
      condition: "always"
    - from: "evaluate"
      to: "refine_aero"
      condition: "not converged"
    - from: "evaluate"
      to: "done"
      condition: "converged"

resources:
  per_state_max_steps: 10
  per_state_timeout: 300     # seconds
  global_max_transitions: 50

graph.initial_state – The entry-point state.
graph.states – List of states. Each maps to an agent and action. A state with terminal: true ends the workflow.
graph.transitions – Directed edges between states. Each has a condition expression evaluated by the ConditionEvaluator.
resources.per_state_max_steps – Maximum LLM steps per state visit.
resources.per_state_timeout – Wall-clock timeout per state in seconds.
resources.global_max_transitions – Hard limit on total state transitions.

aviary_staged_pipeline.yaml

Configuration for the Staged Pipeline operational handler.

stages:
  - name: "exploration"
    agents: ["sizing_agent", "aero_agent"]
    max_steps: 20
    completion_criteria:
      metric: "fuel_burned"
      threshold: 20000
      direction: "below"

  - name: "refinement"
    agents: ["propulsion_agent", "aero_agent"]
    max_steps: 30
    completion_criteria:
      metric: "gross_takeoff_weight"
      threshold: 80000
      direction: "below"

  - name: "finalization"
    agents: ["eval_agent"]
    max_steps: 10
    completion_criteria:
      all_metrics_within_threshold: true

gates:
  strict: true              # Fail the run if a gate is not passed
  retry_on_failure: 2       # Retries before failing a gate

stages – Ordered list of stages. Each stage declares:
- name – Human-readable stage label.
- agents – List of agents active during this stage.
- max_steps – Maximum total LLM steps for the stage.
- completion_criteria – Quality gate that must be satisfied to advance. Can reference a single metric with a threshold and direction, or use all_metrics_within_threshold for the final stage.
gates.strict – When true, a failed gate aborts the entire run.
gates.retry_on_failure – Number of times to retry a stage before declaring gate failure.

eval_thresholds.yaml

Defines the evaluation thresholds used to classify optimization results as pass or fail.

thresholds:
  fuel_burned_kg:
    target: 12000
    acceptable: 14000
    unit: "kg"

  gross_takeoff_weight_kg:
    target: 75000
    acceptable: 82000
    unit: "kg"

  wing_mass_kg:
    target: 4200
    acceptable: 5000
    unit: "kg"

classification:
  excellent: "all metrics at or below target"
  acceptable: "all metrics at or below acceptable"
  failed: "any metric above acceptable"

thresholds – Per-metric definitions:
- target – The ideal value. Results at or below this are classified as excellent.
- acceptable – The upper bound for a passing result.
- unit – Display unit for reporting.
classification – Rules for mapping metric values to overall result labels.