Runtime Config Migration

Migrate legacy cli_backend YAML to model-scoped runtime config with praisonai doctor

praisonai doctor runtime detects legacy cli_backend fields in your agent YAML and migrates them to the new models.default.runtime field.

from praisonaiagents import Agent

# After migration, runtime lives under models.default in agents.yaml
agent = Agent(name="coder", instructions="Write code.")
# praisonai doctor fix --execute  (or: praisonai doctor runtime --fix --execute)

The user runs praisonai doctor runtime; the scan finds legacy cli_backend fields and migrates them to model-scoped runtime config.

Quick Start

1. Scan only

   Run a scan to detect legacy configuration without making any changes:

   praisonai doctor runtime

   Output:

   ⚠ WARN: Found 2 legacy configuration(s) using cli_backend.
     Run `praisonai doctor runtime --fix` to preview changes.

2. Preview fix (dry-run)

   Preview what changes will be made before applying them:

   praisonai doctor runtime --fix

   Output:

   --- agents.yaml (original)
   +++ agents.yaml (migrated)
   @@ -1,4 +1,6 @@
   -cli_backend: claude-code
   +models:
   +  default:
   +    runtime: claude-code
    roles:
      researcher:
   -    cli_backend: openai-gpt
   +    models:
   +      default:
   +        runtime: openai-gpt
   
   Run with --fix --execute to apply changes.

3. Apply fix with backup

   Apply the migration and create a timestamped backup:

   praisonai doctor runtime --fix --execute

   A backup is created at agents.backup.20240115_143022.yaml alongside your original file.

4. Shorter equivalent: doctor fix

   The doctor fix subcommand runs the same migration with a simpler flag shape:

   # Apply with a .bak backup (different format from runtime --fix)
   praisonai doctor fix --execute
   
   # Skip backup creation
   praisonai doctor fix --execute --no-backup

5. Target a specific file

   praisonai doctor runtime --fix --execute --file my-agents.yaml
   # or equivalently:
   praisonai doctor fix --execute --file my-agents.yaml

What Gets Migrated

The cli_backend field at the top level and inside roles.<role_name> is migrated to models.default.runtime.

cli_backend: claude-code
roles:
  researcher:
    cli_backend: openai-gpt
    role: Research specialist
    goal: Find information
    backstory: Expert researcher
    tasks:
      research:
        description: Research the topic
        expected_output: Summary

models:
  default:
    runtime: claude-code
roles:
  researcher:
    models:
      default:
        runtime: openai-gpt
    role: Research specialist
    goal: Find information
    backstory: Expert researcher
    tasks:
      research:
        description: Research the topic
        expected_output: Summary

Known backend ID mapping:

How It Works

Flags Reference

doctor fix flag equivalents — use either command; they share the same migration logic:

doctor runtime flags:

Behavior summary:

• Without --fix: Reports WARN with count of legacy configs found.
• With --fix (dry-run): Shows a preview diff; suggests --fix --execute.
• With --fix --execute: Writes migrated YAML and leaves a <stem>.backup.<YYYYMMDD_HHMMSS>.yaml backup.
• If --file is specified but file does not exist: ERROR, severity HIGH.
• If no config file is found: SKIP.

Writing a Custom Rule

Implement DoctorContractProtocol to add your own migration rules:

from praisonaiagents.runtime import DoctorContractProtocol, Finding, register_rule

class MyRule:
    @property
    def rule_id(self) -> str:
        return "my_org.deprecate_foo"

    def collect_findings(self, config):
        if "foo" in config:
            return [Finding(
                rule_id=self.rule_id,
                severity="warning",
                message="`foo` is deprecated, use `bar` instead",
                fix_description="Rename foo → bar"
            )]
        return []

    def apply_fix(self, config):
        if "foo" in config:
            config["bar"] = config.pop("foo")
        return config

register_rule(MyRule())

Plugin Registration via Entry Point

For distribution as a package, register via the praisonai.doctor_contracts entry-point group:

[project.entry-points."praisonai.doctor_contracts"]
my_org_foo = "my_pkg.rules:MyRule"

Plugins registered this way are auto-discovered when get_rules() is called — no manual register_rule() needed.

Finding Dataclass

from praisonaiagents.runtime import Finding

Finding(
    rule_id="my_org.rule",
    severity="warning",          # "warning" | "error" | "info"
    message="Description of the issue",
    fix_description="What the fix will do",  # optional
    context={"key": "value"},                # optional metadata
)

Programmatic API

import yaml
from praisonaiagents.runtime import collect_findings, apply_fixes

with open("agents.yaml") as f:
    config = yaml.safe_load(f)

# Inspect findings
findings = collect_findings(config)
for finding in findings:
    print(f"[{finding.severity}] {finding.rule_id}: {finding.message}")

# Apply all fixes
migrated = apply_fixes(config)

with open("agents.yaml", "w") as f:
    yaml.dump(migrated, f)

Best Practices

Related