Gateway Admin API

Repair and provision a PraisonAI gateway config from Python — non-interactive, typed, and CI-friendly

Repair and provision a gateway config from Python — no shell-out, no interactive wizard, and a typed result you can assert on.

Quick Start

1. Repair a broken config

   from praisonai_bot import repair_gateway_config
   
   result = repair_gateway_config("~/.praisonai/bot.yaml", fix=True)
   assert result.config_version_migrated is True or result.auth_token_minted is True
   assert not result.remaining_degraded_owners

2. Provision a config from scratch

   from praisonai_bot import provision_gateway_config
   
   path = provision_gateway_config(
       platform="telegram",
       token="${TELEGRAM_BOT_TOKEN}",   # persisted to ~/.praisonai/.env
       agents=["assistant"],
   )
   print(path)   # ~/.praisonai/bot.yaml

3. Detect without repairing

   result = repair_gateway_config("~/.praisonai/bot.yaml")   # fix=False by default
   for owner in result.remaining_degraded_owners:
       print(owner["owner_id"], "->", owner["reason"])

How It Works

Both entry points share the detect → repair → re-validate lifecycle behind praisonai gateway doctor --fix.

When to use which

API Reference

Four symbols make up the whole public surface.

from praisonai_bot import (
    repair_gateway_config,
    provision_gateway_config,
    edit_gateway_channel,
    GatewayRepairResult,
)

repair_gateway_config

repair_gateway_config(config_path, *, fix=False, dry_run=False) -> GatewayRepairResult

Runs the same detect → repair → re-validate lifecycle as praisonai gateway doctor --fix: forward-migrate an out-of-date config_version and mint/persist a strong gateway.auth_token when the configured one is weak or missing.

provision_gateway_config

provision_gateway_config(*, platform, token, agents=None, config_path=None) -> Path

edit_gateway_channel

edit_gateway_channel(config_path, name, settings=None, *, remove=False) -> dict

Add, update, or remove one channels: entry in place. Other channels and top-level keys are untouched, and the edited document is validated against GatewayConfigSchema before the atomic write, so an invalid edit is rejected rather than persisted.

Returns the resulting channel block ({} when remove=True). Raises FileNotFoundError, KeyError (removing a missing channel), or ValueError (unknown platform, bad types, or no enabled channel left).

GatewayRepairResult

@dataclass(frozen=True) — the closed result shape returned by repair_gateway_config.

.to_dict() returns a shallow JSON-safe copy of all four fields.

result = repair_gateway_config("~/.praisonai/bot.yaml", fix=True)
print(result.to_dict())

Precedence & Fallbacks

The auth-token repair interacts with ${ENV} references and explicit YAML tokens as follows.

CLI parity

The Python API, CLI, and YAML surfaces run the same helpers.

Common Patterns

CI-driven per-tenant provisioning

from praisonai_bot import provision_gateway_config, repair_gateway_config

tenants = {
    "acme": "${ACME_TELEGRAM_TOKEN}",
    "globex": "${GLOBEX_TELEGRAM_TOKEN}",
}

for tenant, token in tenants.items():
    path = provision_gateway_config(
        platform="telegram",
        token=token,
        agents=["assistant"],
        config_path=f"/etc/praisonai/{tenant}/bot.yaml",
    )
    result = repair_gateway_config(path, fix=True)
    assert not result.remaining_degraded_owners, (tenant, result.remaining_degraded_owners)

Post-deploy self-healing check

import sys
from praisonai_bot import repair_gateway_config

result = repair_gateway_config("~/.praisonai/bot.yaml", fix=False)
if result.remaining_degraded_owners:
    for owner in result.remaining_degraded_owners:
        print(owner["owner_id"], "->", owner["reason"], file=sys.stderr)
    sys.exit(1)

Testing the fixed gateway in pytest

from praisonai_bot import repair_gateway_config

def test_gateway_self_heals(tmp_path):
    config = tmp_path / "bot.yaml"
    config.write_text("gateway:\n  auth_token: changeme\n  bind_host: 0.0.0.0\n")

    result = repair_gateway_config(config, fix=True)

    assert result.auth_token_minted or result.config_version_migrated
    assert not result.remaining_degraded_owners

Explicit path vs default location

from praisonai_bot import provision_gateway_config

# Default location: ~/.praisonai/bot.yaml
default_path = provision_gateway_config(platform="telegram", token="${TELEGRAM_BOT_TOKEN}")

# Explicit override
custom_path = provision_gateway_config(
    platform="telegram",
    token="${TELEGRAM_BOT_TOKEN}",
    config_path="/etc/praisonai/bot.yaml",
)

Best Practices

Related