PraisonAI 4.6.64__tar.gz → 4.6.67__tar.gz

{praisonai-4.6.64 → praisonai-4.6.67}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.6.64
+Version: 4.6.67
 Summary: PraisonAI is an AI Agents Framework with Self Reflection. PraisonAI application combines PraisonAI Agents, AutoGen, and CrewAI into a low-code solution for building and managing multi-agent LLM systems, focusing on simplicity, customisation, and efficient human-agent collaboration.
 Author: Mervin Praison
 License: MIT
@@ -11,7 +11,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: rich>=13.7
 Requires-Dist: markdown>=3.5
 Requires-Dist: pyparsing>=3.0.0
-Requires-Dist: praisonaiagents>=1.6.64
+Requires-Dist: praisonaiagents>=1.6.67
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0

{praisonai-4.6.64 → praisonai-4.6.67}/PraisonAI.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.6.64
+Version: 4.6.67
 Summary: PraisonAI is an AI Agents Framework with Self Reflection. PraisonAI application combines PraisonAI Agents, AutoGen, and CrewAI into a low-code solution for building and managing multi-agent LLM systems, focusing on simplicity, customisation, and efficient human-agent collaboration.
 Author: Mervin Praison
 License: MIT
@@ -11,7 +11,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: rich>=13.7
 Requires-Dist: markdown>=3.5
 Requires-Dist: pyparsing>=3.0.0
-Requires-Dist: praisonaiagents>=1.6.64
+Requires-Dist: praisonaiagents>=1.6.67
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0

{praisonai-4.6.64 → praisonai-4.6.67}/PraisonAI.egg-info/SOURCES.txt

@@ -70,19 +70,21 @@ praisonai/bots/_commands.py
 praisonai/bots/_config_schema.py
 praisonai/bots/_debounce.py
 praisonai/bots/_defaults.py
-praisonai/bots/_delivery.py
 praisonai/bots/_discord_approval.py
 praisonai/bots/_dlq.py
+praisonai/bots/_durable_adapter.py
 praisonai/bots/_email_utils.py
 praisonai/bots/_http_approval.py
 praisonai/bots/_ingress.py
 praisonai/bots/_mirror.py
+praisonai/bots/_outbox.py
 praisonai/bots/_pairing_ui.py
 praisonai/bots/_presentation_approval.py
 praisonai/bots/_presentation_renderer.py
 praisonai/bots/_protocol_mixin.py
 praisonai/bots/_rate_limit.py
 praisonai/bots/_registry.py
+praisonai/bots/_reset_policy.py
 praisonai/bots/_resilience.py
 praisonai/bots/_run_control.py
 praisonai/bots/_session.py
@@ -153,19 +155,20 @@ praisonai/claw/__init__.py
 praisonai/claw/default_app.py
 praisonai/cli/__init__.py
 praisonai/cli/_paths.py
+praisonai/cli/_warnings.py
 praisonai/cli/app.py
 praisonai/cli/approval_backend.py
 praisonai/cli/branding.py
 praisonai/cli/config_loader.py
 praisonai/cli/fallback_schema.py
 praisonai/cli/langfuse_client.py
-praisonai/cli/legacy.py
 praisonai/cli/main.py
 praisonai/cli/schedule_cli.py
 praisonai/cli/schema_provider.py
 praisonai/cli/unified_schema.py
 praisonai/cli/commands/__init__.py
 praisonai/cli/commands/acp.py
+praisonai/cli/commands/agent.py
 praisonai/cli/commands/agents.py
 praisonai/cli/commands/app.py
 praisonai/cli/commands/audit.py
@@ -178,6 +181,7 @@ praisonai/cli/commands/call.py
 praisonai/cli/commands/chat.py
 praisonai/cli/commands/claw.py
 praisonai/cli/commands/code.py
+praisonai/cli/commands/command.py
 praisonai/cli/commands/commit.py
 praisonai/cli/commands/completion.py
 praisonai/cli/commands/config.py
@@ -256,6 +260,8 @@ praisonai/cli/execution/profiler.py
 praisonai/cli/execution/request.py
 praisonai/cli/execution/result.py
 praisonai/cli/features/__init__.py
+praisonai/cli/features/_endpoint_registry.py
+praisonai/cli/features/_search_registry.py
 praisonai/cli/features/acp.py
 praisonai/cli/features/action_orchestrator.py
 praisonai/cli/features/agent_scheduler.py
@@ -281,6 +287,7 @@ praisonai/cli/features/config_hierarchy.py
 praisonai/cli/features/context_manager.py
 praisonai/cli/features/cost_tracker.py
 praisonai/cli/features/csv_test_runner.py
+praisonai/cli/features/custom_definitions.py
 praisonai/cli/features/debug.py
 praisonai/cli/features/deploy.py
 praisonai/cli/features/diag.py
@@ -367,6 +374,7 @@ praisonai/cli/features/doctor/checks/bot_checks.py
 praisonai/cli/features/doctor/checks/config_checks.py
 praisonai/cli/features/doctor/checks/db_checks.py
 praisonai/cli/features/doctor/checks/env_checks.py
+praisonai/cli/features/doctor/checks/gateway_checks.py
 praisonai/cli/features/doctor/checks/lsp_checks.py
 praisonai/cli/features/doctor/checks/mcp_checks.py
 praisonai/cli/features/doctor/checks/memory_checks.py
@@ -442,6 +450,7 @@ praisonai/cli/ui/events.py
 praisonai/cli/ui/mg_backend.py
 praisonai/cli/ui/plain.py
 praisonai/cli/ui/rich_backend.py
+praisonai/cli/utils/env_utils.py
 praisonai/cli/utils/project.py
 praisonai/cli_backends/__init__.py
 praisonai/cli_backends/claude.py
@@ -483,6 +492,7 @@ praisonai/deploy/main.py
 praisonai/deploy/models.py
 praisonai/deploy/schema.py
 praisonai/deploy/providers/__init__.py
+praisonai/deploy/providers/_registry.py
 praisonai/deploy/providers/aws.py
 praisonai/deploy/providers/azure.py
 praisonai/deploy/providers/base.py
@@ -651,7 +661,6 @@ praisonai/persistence/conversation/async_sqlite.py
 praisonai/persistence/conversation/base.py
 praisonai/persistence/conversation/json_store.py
 praisonai/persistence/conversation/mysql.py
-praisonai/persistence/conversation/mysql_new.py
 praisonai/persistence/conversation/postgres.py
 praisonai/persistence/conversation/singlestore.py
 praisonai/persistence/conversation/sqlite.py
@@ -726,6 +735,7 @@ praisonai/replay/storage.py
 praisonai/replay/writer.py
 praisonai/sandbox/__init__.py
 praisonai/sandbox/_compat.py
+praisonai/sandbox/_registry.py
 praisonai/sandbox/_shell.py
 praisonai/sandbox/daytona.py
 praisonai/sandbox/docker.py

{praisonai-4.6.64 → praisonai-4.6.67}/PraisonAI.egg-info/requires.txt

@@ -1,7 +1,7 @@
 rich>=13.7
 markdown>=3.5
 pyparsing>=3.0.0
-praisonaiagents>=1.6.64
+praisonaiagents>=1.6.67
 python-dotenv>=0.19.0
 litellm<2,>=1.83.14
 PyYAML>=6.0

{praisonai-4.6.64 → praisonai-4.6.67}/praisonai/bots/__init__.py

@@ -17,7 +17,6 @@ if TYPE_CHECKING:
     from .agentmail import AgentMailBot
     from .bot import Bot
     from .botos import BotOS
-    from .delivery import DeliveryRouter, ChannelDirectory, SessionSource
     from ._session import BotSessionManager
     from ._dlq import InboundDLQ, DLQEntry
     from ._ingress import InboundJournal, JournalEntry
@@ -27,6 +26,9 @@ if TYPE_CHECKING:
     from ._webhook_approval import WebhookApproval
     from ._http_approval import HTTPApproval
     from ._streaming import StreamingConfig, StreamingMode, DraftStreamer
+    from ._outbox import OutboundQueue, OutboundEntry
+    from ._delivery import DurableDelivery, deliver_with_retry
+    from ._durable_adapter import DurableAdapterMixin
 
 def __getattr__(name: str):
     """Lazy loading of bot components."""
@@ -103,16 +105,25 @@ def __getattr__(name: str):
     if name == "DraftStreamer":
         from ._streaming import DraftStreamer
         return DraftStreamer
-    # Delivery routing components
-    if name == "DeliveryRouter":
-        from .delivery import DeliveryRouter
-        return DeliveryRouter
-    if name == "ChannelDirectory":
-        from .delivery import ChannelDirectory
-        return ChannelDirectory
-    if name == "SessionSource":
-        from .delivery import SessionSource
-        return SessionSource
+    # Outbound delivery components
+    if name == "OutboundQueue":
+        from ._outbox import OutboundQueue
+        return OutboundQueue
+    if name == "OutboundEntry":
+        from ._outbox import OutboundEntry
+        return OutboundEntry
+    if name == "DurableDelivery":
+        from ._delivery import DurableDelivery
+        return DurableDelivery
+    if name == "deliver_with_retry":
+        from ._delivery import deliver_with_retry
+        return deliver_with_retry
+    if name == "deliver_chunked":
+        from ._delivery import deliver_chunked
+        return deliver_chunked
+    if name == "DurableAdapterMixin":
+        from ._durable_adapter import DurableAdapterMixin
+        return DurableAdapterMixin
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 __all__ = [
@@ -121,12 +132,13 @@ __all__ = [
     "BotSessionManager",
     "InboundDLQ", "DLQEntry",
     "InboundJournal", "JournalEntry",
+    "OutboundQueue", "OutboundEntry",
+    "DurableDelivery", "deliver_with_retry", "deliver_chunked",
+    "DurableAdapterMixin",
     "SlackApproval", "TelegramApproval", "DiscordApproval",
     "WebhookApproval", "HTTPApproval",
     # Streaming
     "StreamingConfig", "StreamingMode", "DraftStreamer",
-    # Delivery routing
-    "DeliveryRouter", "ChannelDirectory", "SessionSource",
     # W1
-    "mirror_to_session", "BotSessionManager",
+    "mirror_to_session",
 ]

praisonai-4.6.67/praisonai/bots/_config_schema.py

@@ -0,0 +1,469 @@
+"""
+Pydantic-based config schema validation for bot.yaml / gateway.yaml.
+
+Provides clear, human-friendly error messages when configuration is invalid.
+This is the canonical configuration schema for all bot/gateway configurations.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+logger = logging.getLogger(__name__)
+
+
+class AgentConfigSchema(BaseModel):
+    """Schema for agent configuration in bot.yaml."""
+    name: str = "assistant"
+    instructions: str = ""
+    model: Optional[str] = "gpt-4o-mini"
+    llm: Optional[str] = None  # Alias for model
+    memory: bool = False
+    tools: List[str] = Field(default_factory=list)
+    knowledge: Union[bool, List[str]] = False
+    web_search: bool = False
+    web_search_provider: str = "duckduckgo"
+    auto_approve: bool = False
+    
+    @model_validator(mode="after")
+    def handle_model_aliases(self):
+        """Handle model/llm aliases."""
+        # Use llm if provided and model wasn't explicitly set
+        if self.llm and "model" not in self.model_fields_set:
+            self.model = self.llm
+        return self
+
+
+class SessionResetConfigSchema(BaseModel):
+    """Schema for session reset policy configuration."""
+    mode: str = "none"  # none | idle | daily | both
+    idle_minutes: int = 60  # Reset after N minutes of inactivity
+    at_hour: Optional[int] = None  # Daily reset hour (0-23)
+    
+    @field_validator("mode")
+    @classmethod
+    def validate_mode(cls, v: str) -> str:
+        allowed = {"none", "idle", "daily", "both"}
+        if v not in allowed:
+            raise ValueError(
+                f"Invalid reset mode '{v}'. Must be one of: {', '.join(sorted(allowed))}"
+            )
+        return v
+    
+    @field_validator("idle_minutes")
+    @classmethod
+    def validate_idle_minutes(cls, v: int) -> int:
+        if v < 1:
+            raise ValueError("idle_minutes must be at least 1")
+        return v
+    
+    @field_validator("at_hour")
+    @classmethod
+    def validate_at_hour(cls, v: Optional[int]) -> Optional[int]:
+        if v is not None and not (0 <= v <= 23):
+            raise ValueError("at_hour must be between 0 and 23")
+        return v
+    
+    @model_validator(mode="after")
+    def validate_config_consistency(self):
+        """Ensure at_hour is set when mode requires it."""
+        if self.mode in ("daily", "both") and self.at_hour is None:
+            raise ValueError(f"at_hour is required when mode is '{self.mode}'")
+        return self
+
+
+class SessionConfigSchema(BaseModel):
+    """Schema for session configuration."""
+    max_history: int = 100
+    reset: Optional[SessionResetConfigSchema] = None
+
+
+class StreamingConfigSchema(BaseModel):
+    """Schema for streaming reply configuration."""
+    mode: str = "off"  # off | draft | progress
+    min_interval: float = 1.5  # Minimum seconds between edits
+    min_delta: int = 120  # Minimum character delta before edit
+    placeholder_text: str = "🤔 Thinking..."
+    progress_prefix: str = "🤔 "
+    
+    @field_validator("mode")
+    @classmethod
+    def validate_streaming_mode(cls, v: str) -> str:
+        allowed = {"off", "draft", "progress"}
+        if v not in allowed:
+            raise ValueError(
+                f"Invalid streaming mode '{v}'. Must be one of: {', '.join(sorted(allowed))}"
+            )
+        return v
+    
+    @field_validator("min_interval")
+    @classmethod
+    def validate_min_interval(cls, v: float) -> float:
+        if v < 0.1:
+            raise ValueError("min_interval must be at least 0.1 seconds")
+        return v
+    
+    @field_validator("min_delta")
+    @classmethod
+    def validate_min_delta(cls, v: int) -> int:
+        if v < 1:
+            raise ValueError("min_delta must be at least 1 character")
+        return v
+
+
+class OutboundResilienceSchema(BaseModel):
+    """Schema for outbound message retry configuration."""
+    enabled: bool = True
+    initial_ms: float = 1000.0  # Initial retry delay in ms
+    max_ms: float = 10000.0  # Maximum retry delay in ms
+    factor: float = 1.5  # Exponential backoff factor
+    max_attempts: int = 3  # Maximum retry attempts
+    jitter: float = 0.25  # Random jitter fraction
+    dlq_path: Optional[str] = None  # Path to outbound DLQ database
+    
+    @field_validator("initial_ms")
+    @classmethod
+    def validate_initial_ms(cls, v: float) -> float:
+        if v < 100:
+            raise ValueError("initial_ms must be at least 100ms")
+        return v
+    
+    @field_validator("max_attempts")
+    @classmethod
+    def validate_max_attempts(cls, v: int) -> int:
+        if v < 1 or v > 10:
+            raise ValueError("max_attempts must be between 1 and 10")
+        return v
+
+
+class ChannelConfigSchema(BaseModel):
+    """Schema for a single channel configuration."""
+    platform: Optional[str] = None
+    token: str = ""
+    app_token: Optional[str] = None  # For Slack Socket Mode
+    mode: str = "poll"  # poll | ws | webhook | hybrid
+    group_policy: str = "mention_only"  # Default to secure: respond_all, mention_only, command_only
+    allowlist: List[str] = Field(default_factory=list)
+    blocklist: List[str] = Field(default_factory=list)
+    allowed_users: List[str] = Field(default_factory=list)  # Changed to List for consistency
+    admin_users: Optional[str] = None  # Comma-separated list of admin user IDs
+    user_allowed_commands: Optional[str] = None  # Comma-separated list of allowed commands
+    routes: Dict[str, str] = Field(default_factory=dict)  # Context -> agent_id mapping
+    routing: Optional[Dict[str, str]] = None  # Alias for routes
+    webhook_url: Optional[str] = None
+    webhook_port: int = 8080
+    streaming: Optional[StreamingConfigSchema] = None
+    home_channel: Optional[str] = None  # Default channel for this platform
+    aliases: Dict[str, str] = Field(default_factory=dict)  # Friendly name -> channel_id mapping
+    outbound_resilience: Optional[OutboundResilienceSchema] = None
+    session: Optional[SessionConfigSchema] = None
+    max_history: Optional[int] = None  # Backward compatibility
+    
+    # Platform-specific fields
+    phone_number_id: Optional[str] = None  # WhatsApp
+    verify_token: Optional[str] = None  # WhatsApp
+    whatsapp_mode: Optional[str] = None  # WhatsApp-specific mode: "cloud" or "web"
+    creds_dir: Optional[str] = None  # WhatsApp web mode credentials directory
+    email_address: Optional[str] = None  # Email
+    imap_server: Optional[str] = None  # Email  
+    smtp_server: Optional[str] = None  # Email
+    inbox_id: Optional[str] = None  # AgentMail
+    domain: Optional[str] = None  # AgentMail
+    
+    @field_validator("mode")
+    @classmethod
+    def validate_mode(cls, v: str) -> str:
+        allowed = {"poll", "ws", "webhook", "hybrid"}
+        if v not in allowed:
+            raise ValueError(
+                f"Invalid mode '{v}'. Must be one of: {', '.join(sorted(allowed))}"
+            )
+        return v
+    
+    @field_validator("token")
+    @classmethod
+    def resolve_env_var(cls, v: str) -> str:
+        """Resolve ${ENV_VAR} references in token."""
+        if v.startswith("${") and v.endswith("}"):
+            env_key = v[2:-1]
+            resolved = os.environ.get(env_key, "")
+            if not resolved:
+                raise ValueError(
+                    f"Environment variable '{env_key}' not set. "
+                    f"Set it with: export {env_key}=your_token"
+                )
+            return resolved
+        return v
+    
+    @field_validator("group_policy")
+    @classmethod
+    def validate_group_policy(cls, v: str) -> str:
+        allowed = {"respond_all", "mention_only", "command_only"}
+        if v not in allowed:
+            raise ValueError(
+                f"Invalid group_policy '{v}'. Must be one of: {', '.join(sorted(allowed))}"
+            )
+        return v
+    
+    @model_validator(mode="after")
+    def validate_security(self):
+        """Validate security settings and warn about unsafe configurations."""
+        # Merge routing and routes
+        if self.routing and not self.routes:
+            self.routes = self.routing
+            
+        # Warn about empty allowed_users (open to everyone)
+        if not self.allowed_users and not self.allowlist and not self.blocklist:
+            logger.warning(
+                "Channel has no user restrictions (allowed_users/allowlist/blocklist). "
+                "Bot will respond to EVERYONE. Consider adding allowed_users for security."
+            )
+            
+        # Warn about respond_all in production
+        if self.group_policy == "respond_all":
+            logger.warning(
+                "Channel uses 'respond_all' group_policy. "
+                "Consider 'mention_only' for better security."
+            )
+        return self
+
+
+class RoutingConfigSchema(BaseModel):
+    """Schema for agent routing configuration."""
+    default: str = "assistant"
+    rules: Dict[str, str] = Field(default_factory=dict)
+
+
+class DaemonConfigSchema(BaseModel):
+    """Schema for daemon/service configuration."""
+    enabled: bool = False
+    restart: str = "always"  # always, on_failure, never
+    
+    @field_validator("restart")
+    @classmethod
+    def validate_restart(cls, v: str) -> str:
+        allowed = {"always", "on_failure", "never"}
+        if v not in allowed:
+            raise ValueError(f"Invalid restart policy '{v}'. Must be one of: {', '.join(sorted(allowed))}")
+        return v
+
+
+class GatewayConfigSchema(BaseModel):
+    """Unified schema for gateway.yaml/bot.yaml configuration.
+    
+    This is the canonical schema that supports all configuration patterns:
+    - Single-bot bot.yaml (platform + token + agent)
+    - Gateway gateway.yaml (agents dict + channels dict with routing)
+    - BotOS config (agent + platforms dict)
+    """
+    # Top-level fields for single-bot compatibility
+    platform: Optional[str] = None
+    token: Optional[str] = None
+    
+    # Agent configuration (single or multiple)
+    agent: Optional[AgentConfigSchema] = None
+    agents: Optional[Dict[str, AgentConfigSchema]] = None
+    
+    # Channel configuration
+    channels: Dict[str, ChannelConfigSchema] = Field(default_factory=dict)
+    
+    # Platform dict for BotOS compatibility
+    platforms: Optional[Dict[str, Dict[str, Any]]] = None
+    
+    # Routing and daemon config
+    routing: Optional[RoutingConfigSchema] = None
+    daemon: Optional[DaemonConfigSchema] = None
+    
+    @model_validator(mode="after")
+    def normalize_and_validate(self):
+        """Normalize different config formats to canonical form and validate."""
+        # Migrate single-bot format (platform + token at top level)
+        if self.platform and self.token and not self.channels:
+            self.channels = {
+                self.platform: ChannelConfigSchema(
+                    platform=self.platform,
+                    token=self.token
+                )
+            }
+            
+        # Migrate BotOS platforms format to channels
+        if self.platforms and not self.channels:
+            for platform_name, platform_config in self.platforms.items():
+                self.channels[platform_name] = ChannelConfigSchema(
+                    platform=platform_name,
+                    **platform_config
+                )
+                
+        # Ensure at least one channel is configured
+        if not self.channels:
+            raise ValueError(
+                "No channels configured. Add at least one channel "
+                "(telegram, discord, slack, whatsapp) to your config"
+            )
+            
+        # Validate platform names
+        valid_platforms = {"telegram", "discord", "slack", "whatsapp", "email", "agentmail", "linear"}
+        for name, channel in self.channels.items():
+            platform = (channel.platform or name).lower()
+            if platform not in valid_platforms:
+                raise ValueError(
+                    f"Unknown channel '{name}' (platform '{platform}'). "
+                    f"Supported platforms: {', '.join(sorted(valid_platforms))}"
+                )
+                
+        # Set platform if not explicitly set
+        for name, channel in self.channels.items():
+            if not channel.platform:
+                channel.platform = name
+                
+        return self
+
+
+# Legacy alias for backward compatibility
+BotYamlSchema = GatewayConfigSchema
+
+
+def validate_gateway_config(raw: Dict[str, Any], apply_env_substitution: bool = True) -> GatewayConfigSchema:
+    """Validate a raw YAML dict against the unified gateway config schema.
+    
+    Args:
+        raw: Parsed YAML dictionary
+        apply_env_substitution: Whether to apply ${VAR} substitution
+        
+    Returns:
+        Validated GatewayConfigSchema
+        
+    Raises:
+        ValueError: With human-friendly error messages
+    """
+    # Apply environment variable substitution if requested
+    if apply_env_substitution:
+        from ..cli.utils.env_utils import substitute_env_vars
+        raw = substitute_env_vars(raw)
+        
+    try:
+        return GatewayConfigSchema(**raw)
+    except Exception as e:
+        # Re-raise with user-friendly message
+        msg = str(e)
+        # Strip pydantic internals for cleaner output
+        if "validation error" in msg.lower():
+            lines = msg.split("\n")
+            clean_lines = [line for line in lines if line.strip() and not line.strip().startswith("For further")]
+            msg = "\n".join(clean_lines)
+        raise ValueError(f"Invalid gateway/bot configuration:\n{msg}") from None
+
+
+def validate_bot_config(raw: Dict[str, Any]) -> GatewayConfigSchema:
+    """Validate a raw YAML dict against the bot config schema.
+    
+    Legacy function for backward compatibility.
+    
+    Args:
+        raw: Parsed YAML dictionary
+        
+    Returns:
+        Validated GatewayConfigSchema
+        
+    Raises:
+        ValueError: With human-friendly error messages
+    """
+    return validate_gateway_config(raw)
+
+
+def load_and_validate_gateway_yaml(path: str, apply_env_substitution: bool = True) -> GatewayConfigSchema:
+    """Load and validate a gateway.yaml or bot.yaml file.
+    
+    This is the canonical loader for all bot/gateway configurations.
+    
+    Args:
+        path: Path to the YAML file
+        apply_env_substitution: Whether to apply ${VAR} substitution
+        
+    Returns:
+        Validated config schema
+        
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        ValueError: If config is invalid
+    """
+    import yaml
+    
+    if not os.path.exists(path):
+        raise FileNotFoundError(
+            f"Config file not found: {path}\n"
+            f"Run 'praisonai onboard' to create one, or create it manually."
+        )
+    
+    # Load env file if not already loaded
+    from ..cli.utils.env_utils import load_env_file
+    load_env_file()
+    
+    with open(path) as f:
+        raw = yaml.safe_load(f) or {}
+    
+    return validate_gateway_config(raw, apply_env_substitution)
+
+
+def load_and_validate_bot_yaml(path: str) -> GatewayConfigSchema:
+    """Load and validate a bot.yaml file.
+    
+    Legacy function for backward compatibility.
+    
+    Args:
+        path: Path to the YAML file
+        
+    Returns:
+        Validated config schema
+        
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        ValueError: If config is invalid
+    """
+    return load_and_validate_gateway_yaml(path)
+
+
+def migrate_legacy_config(raw: Dict[str, Any]) -> Dict[str, Any]:
+    """Migrate legacy configuration formats to the canonical schema.
+    
+    Handles migration from:
+    - Old single-bot format (top-level platform/token)
+    - Old BotOS format (platforms dict)
+    - Old gateway format (missing security defaults)
+    
+    Args:
+        raw: Raw configuration dictionary
+        
+    Returns:
+        Migrated configuration dictionary
+    """
+    migrated = dict(raw)
+    
+    # Log migrations for transparency
+    migrations = []
+    
+    # Migrate old allowed_users string to list
+    if "channels" in migrated:
+        for channel_name, channel in migrated["channels"].items():
+            if isinstance(channel.get("allowed_users"), str):
+                old_value = channel["allowed_users"]
+                if old_value:
+                    channel["allowed_users"] = [u.strip() for u in old_value.split(",") if u.strip()]
+                else:
+                    channel["allowed_users"] = []
+                migrations.append(f"Migrated {channel_name}.allowed_users from string to list")
+                
+            # Set secure defaults if not specified
+            if "group_policy" not in channel:
+                channel["group_policy"] = "mention_only"
+                migrations.append(f"Set {channel_name}.group_policy to secure default 'mention_only'")
+                
+    # Log any migrations performed
+    if migrations:
+        logger.info(f"Config migrations applied: {'; '.join(migrations)}")
+        
+    return migrated