PraisonAI 4.6.70__tar.gz → 4.6.72__tar.gz

{praisonai-4.6.70 → praisonai-4.6.72}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.6.70
+Version: 4.6.72
 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,13 +11,14 @@ 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.70
+Requires-Dist: praisonaiagents>=1.6.72
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: mcp>=1.20.0
 Requires-Dist: typer>=0.9.0
 Requires-Dist: textual>=0.47.0
+Requires-Dist: pydantic>=2.0.0
 Provides-Extra: ui
 Requires-Dist: aiui<0.4,>=0.3.121; extra == "ui"
 Provides-Extra: gradio

{praisonai-4.6.70 → praisonai-4.6.72}/PraisonAI.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.6.70
+Version: 4.6.72
 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,13 +11,14 @@ 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.70
+Requires-Dist: praisonaiagents>=1.6.72
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: mcp>=1.20.0
 Requires-Dist: typer>=0.9.0
 Requires-Dist: textual>=0.47.0
+Requires-Dist: pydantic>=2.0.0
 Provides-Extra: ui
 Requires-Dist: aiui<0.4,>=0.3.121; extra == "ui"
 Provides-Extra: gradio

{praisonai-4.6.70 → praisonai-4.6.72}/PraisonAI.egg-info/SOURCES.txt

@@ -76,6 +76,7 @@ praisonai/bots/_dlq.py
 praisonai/bots/_durable_adapter.py
 praisonai/bots/_email_utils.py
 praisonai/bots/_http_approval.py
+praisonai/bots/_identity.py
 praisonai/bots/_ingress.py
 praisonai/bots/_mirror.py
 praisonai/bots/_outbox.py
@@ -201,6 +202,8 @@ praisonai/cli/commands/flow.py
 praisonai/cli/commands/gateway.py
 praisonai/cli/commands/github.py
 praisonai/cli/commands/hooks.py
+praisonai/cli/commands/identity.py
+praisonai/cli/commands/init.py
 praisonai/cli/commands/kanban.py
 praisonai/cli/commands/knowledge.py
 praisonai/cli/commands/langextract.py
@@ -248,6 +251,7 @@ praisonai/cli/commands/tracker.py
 praisonai/cli/commands/train.py
 praisonai/cli/commands/ui.py
 praisonai/cli/commands/up.py
+praisonai/cli/commands/validate.py
 praisonai/cli/commands/version.py
 praisonai/cli/commands/workflow.py
 praisonai/cli/configuration/__init__.py
@@ -386,6 +390,7 @@ praisonai/cli/features/doctor/checks/packaging_checks.py
 praisonai/cli/features/doctor/checks/performance_checks.py
 praisonai/cli/features/doctor/checks/permissions_checks.py
 praisonai/cli/features/doctor/checks/runtime_checks.py
+praisonai/cli/features/doctor/checks/runtime_migration_checks.py
 praisonai/cli/features/doctor/checks/selftest_checks.py
 praisonai/cli/features/doctor/checks/serve_checks.py
 praisonai/cli/features/doctor/checks/skills_checks.py
@@ -472,6 +477,9 @@ praisonai/code/utils/__init__.py
 praisonai/code/utils/file_utils.py
 praisonai/code/utils/ignore_utils.py
 praisonai/code/utils/text_utils.py
+praisonai/config/__init__.py
+praisonai/config/schema.py
+praisonai/config/validator.py
 praisonai/context/__init__.py
 praisonai/context/_storage_path.py
 praisonai/context/artifact_store.py
@@ -761,6 +769,7 @@ praisonai/scheduler/daemon_manager.py
 praisonai/scheduler/deployment.py
 praisonai/scheduler/enhanced_executor.py
 praisonai/scheduler/executor.py
+praisonai/scheduler/run_policy.py
 praisonai/scheduler/shared.py
 praisonai/scheduler/state_manager.py
 praisonai/scheduler/yaml_loader.py

{praisonai-4.6.70 → praisonai-4.6.72}/PraisonAI.egg-info/requires.txt

@@ -1,13 +1,14 @@
 rich>=13.7
 markdown>=3.5
 pyparsing>=3.0.0
-praisonaiagents>=1.6.70
+praisonaiagents>=1.6.72
 python-dotenv>=0.19.0
 litellm<2,>=1.83.14
 PyYAML>=6.0
 mcp>=1.20.0
 typer>=0.9.0
 textual>=0.47.0
+pydantic>=2.0.0
 
 [acp]
 agent-client-protocol>=0.7.0

{praisonai-4.6.70 → praisonai-4.6.72}/praisonai/_dev/parity/docs_generator.py

@@ -184,6 +184,40 @@ FEATURE_CATEGORIES = {
     'resource': 'Sandbox',  # ResourceLimits is part of sandbox execution
 }
 
+# Doc categories excluded from Python "Documentation Without Features" orphan reporting.
+# These pages document infra, other SDKs, or user-facing tooling outside praisonaiagents exports.
+PYTHON_DOC_ORPHAN_EXCLUSIONS = frozenset({
+    'Deployment',  # docs/deploy — CI/infra guidance, not Python SDK feature exports
+    'AI SDK',      # TypeScript SDK pages; tracked in docs/js/ parity separately
+})
+
+# Map doc-only category display names to SDK feature display names for parity matching.
+DOC_FEATURE_CATEGORY_ALIASES = {
+    'Callbacks': 'Hooks',
+    'Middleware': 'Hooks',
+    'Vector Store': 'Knowledge',
+    'Token Management': 'Context Management',
+    'Jobs': 'Workflows',
+    'Chat': 'Agent',
+    'Streaming': 'LLM',
+    'Scheduler': 'Tools',
+    'Storage': 'Database',
+    'Process': 'Workflows',
+}
+
+# Module-path hints when export names do not match FEATURE_CATEGORIES prefixes.
+MODULE_PATH_CATEGORY = (
+    ('deep_research_agent', 'deep-research'),
+    ('hooks', 'hook'),
+    ('streaming', 'stream'),
+    ('scheduler', 'scheduler'),
+    ('storage', 'storage'),
+    ('process', 'process'),
+    ('context.tokens', 'token'),
+    ('chat_handler', 'chat'),
+    ('chat_mixin', 'chat'),
+)
+
 
 # Minimum lines for a doc to be considered "real" (not a stub)
 MIN_DOC_LINES = 50
@@ -257,8 +291,14 @@ class DocsParityGenerator:
             current = current.parent
         return Path("/Users/praison/praisonai-package")
     
-    def _categorize_feature(self, feature_name: str) -> str:
-        """Map a feature name to its category."""
+    def _categorize_feature(self, feature_name: str, module_path: str = '') -> str:
+        """Map a feature name (and optional module path) to its category."""
+        if module_path:
+            path = module_path.replace('praisonaiagents.', '')
+            for hint, prefix in MODULE_PATH_CATEGORY:
+                if hint in path:
+                    return prefix
+
         normalized = normalize_topic(feature_name)
         
         # Try to find a matching prefix
@@ -305,7 +345,8 @@ class DocsParityGenerator:
         
         for export in exports:
             name = export.name if hasattr(export, 'name') else str(export)
-            category = self._categorize_feature(name)
+            module_path = export.module_path if hasattr(export, 'module_path') else ''
+            category = self._categorize_feature(name, module_path)
             if category not in groups:
                 groups[category] = []
             groups[category].append(name)
@@ -357,6 +398,9 @@ class DocsParityGenerator:
                 if prefix == 'other':
                     continue
                 display_name = FEATURE_CATEGORIES.get(prefix, prefix.title())
+                if display_name in PYTHON_DOC_ORPHAN_EXCLUSIONS:
+                    continue
+                display_name = DOC_FEATURE_CATEGORY_ALIASES.get(display_name, display_name)
                 if display_name not in result:
                     result[display_name] = ([], 0)
                 existing_names, existing_lines = result[display_name]

{praisonai-4.6.70 → praisonai-4.6.72}/praisonai/agents_generator.py

@@ -1,25 +1,41 @@
 # praisonai/agents_generator.py
 
 import sys
-from typing import Dict, Any, Optional, List
-from .version import __version__
-import yaml, os
-from rich import print
-import inspect
-from pathlib import Path
-import importlib
-import importlib.util
 import os
+import inspect
 import logging
 import re
 import keyword
 import difflib
+import importlib
+import importlib.util
+from pathlib import Path
+from typing import Dict, Any, Optional, List
+
+from .version import __version__
 
 # Import new architecture components
 from .framework_adapters.base import FrameworkAdapter
-from .framework_adapters.registry import FrameworkAdapterRegistry, get_default_registry
 from .tool_registry import ToolRegistry
 
+
+def _rich_print(*args, **kwargs):
+    """Lazy alias for rich.print — pays the import cost only on first use."""
+    from rich import print as _rp
+    return _rp(*args, **kwargs)
+
+
+def _yaml_safe_load(stream):
+    """Lazy alias for yaml.safe_load."""
+    import yaml
+    return yaml.safe_load(stream)
+
+
+def _get_default_adapter_registry():
+    """Lazy import for the adapter registry — defers entry-point discovery."""
+    from .framework_adapters.registry import get_default_registry
+    return get_default_registry()
+
 # Import availability flags
 # Compatibility imports - now handled by centralized detection
 # (inbuilt_tools still defines these but they're read-only compatibility)
@@ -233,11 +249,16 @@ class AgentsGenerator:
         
         # DI-friendly: tests/multi-tenant runtimes pass their own registry;
         # CLI users get the process default.
-        self._adapter_registry = adapter_registry or get_default_registry()
+        self._adapter_registry = adapter_registry or _get_default_adapter_registry()
         
         # Defer framework adapter creation until YAML is loaded
         # This fixes the issue where empty framework string fails before YAML framework is read
         self.framework_adapter = None
+        
+        # Only autogen-family adapters need the autogen tool shim
+        # Note: autogen_v2 is also part of the autogen family
+        if framework and framework in {"autogen", "autogen_v2", "autogen_v4", "ag2"}:
+            self.tool_registry.register_builtin_autogen_adapters()
 
     def _get_framework_adapter(self, framework: str) -> FrameworkAdapter:
         """
@@ -493,111 +514,60 @@ class AgentsGenerator:
 
     def _validate_agents_config(self, config):
         """
-        Validate agent configuration for typos in field names and provide suggestions.
+        Validate agent configuration with fail-fast validation and aggregated errors.
         
         Args:
             config (dict): The parsed YAML configuration
+            
+        Raises:
+            ValueError: If configuration has validation errors
         """
-        known_fields = {
-            'role', 'goal', 'instructions', 'backstory', 'tools', 'toolsets', 'tasks', 'llm',
-            'function_calling_llm', 'allow_delegation', 'max_iter', 'max_rpm',
-            'max_execution_time', 'verbose', 'cache', 'system_template',
-            'prompt_template', 'response_template', 'tool_timeout', 'tool_retry_policy',
-            'planning_tools', 'planning', 'autonomy', 'guardrails', 'streaming', 'stream',
-            'approval', 'skills', 'cli_backend', 'runtime', 'reflection', 'handoff', 'web', 'web_fetch'
-        }
+        # Use the new comprehensive validator
+        from .config.validator import ConfigValidator
         
-        # Collect YAML-local model aliases (valid even if not in global catalogue)
-        local_model_aliases = set()
-        models_cfg = config.get("models", {})
-        if isinstance(models_cfg, dict):
-            local_model_aliases = {k for k in models_cfg.keys() if isinstance(k, str)}
+        # Use existing tool resolver if available
+        validator = ConfigValidator(tool_resolver=self.tool_resolver)
         
-        # Try to load model catalogue for validation
-        model_catalogue = None
-        try:
-            from .llm.catalogue import ModelCatalogue
-            model_catalogue = ModelCatalogue()
-        except ImportError:
-            pass  # Catalogue not available
-
-        for section_name in ('agents', 'roles'):
-            section = config.get(section_name, {})
-            if not isinstance(section, dict):
-                continue
-
-            entity_name = 'agent' if section_name == 'agents' else 'role'
-            for name, section_config in section.items():
-                if not isinstance(section_config, dict):
-                    continue
-
-                for field_name in section_config:
-                    if field_name in known_fields:
-                        continue
-
-                    close_matches = difflib.get_close_matches(
-                        field_name,
-                        known_fields,
-                        n=1,
-                        cutoff=0.6
-                    )
-                    suggestion = f" Did you mean '{close_matches[0]}'?" if close_matches else ""
-                    self.logger.warning(
-                        f"Unknown field '{field_name}' in {entity_name} '{name}'.{suggestion}"
-                    )
-                
-                # Validate model/llm values if catalogue available
-                if model_catalogue:
-                    for model_field in ('llm', 'function_calling_llm'):
-                        model_value = section_config.get(model_field)
-                        if model_value and isinstance(model_value, str):
-                            # Skip validation for local model aliases defined in YAML
-                            if model_value in local_model_aliases:
-                                continue
-                            try:
-                                model_catalogue.validate_model(model_value)
-                            except ValueError as e:
-                                self.logger.warning(
-                                    f"Invalid model '{model_value}' in {entity_name} '{name}' field '{model_field}': {e}"
-                                )
-                    
-                    # Check for tools configured with non-tool-calling models
-                    if section_config.get('tools'):
-                        llm_value = section_config.get('llm')
-                        if llm_value:
-                            model_info = model_catalogue.describe_model(llm_value)
-                            if model_info and not model_info.get('supports_tools'):
-                                self.logger.warning(
-                                    f"{entity_name.capitalize()} '{name}' has tools configured but model '{llm_value}' does not support tool calling"
-                                )
-        
-        # Also validate top-level llm/model config
-        if model_catalogue:
-            for model_field in ('llm', 'model'):
-                model_value = config.get(model_field)
-                if model_value and isinstance(model_value, str):
-                    # Skip validation for local model aliases defined in YAML
-                    if model_value in local_model_aliases:
-                        continue
-                    try:
-                        model_catalogue.validate_model(model_value)
-                    except ValueError as e:
-                        self.logger.warning(f"Invalid model '{model_value}' in top-level '{model_field}': {e}")
+        # Check for strict mode from environment or config
+        import os
+        strict_mode = os.getenv('PRAISONAI_VALIDATE_STRICT', 'false').lower() == 'true'
+        
+        # Validate configuration
+        result = validator.validate_config(config, strict=strict_mode)
+        
+        # Log warnings
+        for warning in result.warnings:
+            self.logger.warning(warning)
+        
+        # If there are errors, fail fast with aggregated error message
+        if not result.valid:
+            error_msg = f"Configuration validation failed with {len(result.errors)} error(s):\n"
+            for i, error in enumerate(result.errors, 1):
+                error_msg += f"  {i}. {error}\n"
+            
+            # Include warnings if any
+            if result.warnings:
+                error_msg += f"\nAdditionally, there are {len(result.warnings)} warning(s):\n"
+                for i, warning in enumerate(result.warnings, 1):
+                    error_msg += f"  {i}. {warning}\n"
+            
+            self.logger.error(error_msg)
+            raise ValueError(error_msg)
 
 
 
     def _load_config(self):
         """Load configuration from agent file or agent_yaml."""
         if self.agent_yaml:
-            config = yaml.safe_load(self.agent_yaml)
+            config = _yaml_safe_load(self.agent_yaml)
         else:
             if self.agent_file in ('/app/api:app', 'api:app'):
                 self.agent_file = 'agents.yaml'
             try:
                 with open(self.agent_file, 'r') as f:
-                    config = yaml.safe_load(f)
+                    config = _yaml_safe_load(f)
             except FileNotFoundError:
-                print(f"File not found: {self.agent_file}")
+                _rich_print(f"File not found: {self.agent_file}")
                 return None
         
         # Apply CLI config overrides to both paths (agent_yaml and agent_file)

{praisonai-4.6.70 → praisonai-4.6.72}/praisonai/bots/__init__.py

@@ -18,6 +18,7 @@ if TYPE_CHECKING:
     from .bot import Bot
     from .botos import BotOS
     from ._session import BotSessionManager
+    from ._identity import StoreBackedIdentityResolver
     from ._dlq import InboundDLQ, DLQEntry
     from ._ingress import InboundJournal, JournalEntry
     from ._slack_approval import SlackApproval
@@ -81,6 +82,9 @@ def __getattr__(name: str):
     if name == "BotSessionManager":
         from ._session import BotSessionManager
         return BotSessionManager
+    if name == "StoreBackedIdentityResolver":
+        from ._identity import StoreBackedIdentityResolver
+        return StoreBackedIdentityResolver
     # N4 — inbound dead-letter queue
     if name == "InboundDLQ":
         from ._dlq import InboundDLQ
@@ -130,6 +134,7 @@ __all__ = [
     "TelegramBot", "DiscordBot", "SlackBot", "WhatsAppBot", "LinearBot", "EmailBot", "AgentMailBot",
     "Bot", "BotOS",
     "BotSessionManager",
+    "StoreBackedIdentityResolver",
     "InboundDLQ", "DLQEntry",
     "InboundJournal", "JournalEntry",
     "OutboundQueue", "OutboundEntry",

praisonai-4.6.72/praisonai/bots/_identity.py

@@ -0,0 +1,199 @@
+"""
+Store-backed cross-platform identity resolver (wrapper implementation).
+
+The core SDK ships the ``IdentityResolverProtocol`` and lightweight
+in-memory / file-backed resolvers (``praisonaiagents.session.identity``).
+This module provides a *heavy* implementation that reuses the wrapper's
+persistence and **pairing** data so a linked/paired user shares one
+session, history and memory across channels **by default**.
+
+``StoreBackedIdentityResolver``:
+
+1. Keeps an explicit, persisted ``(platform, user_id) -> canonical_id``
+   link map (inherited from the core ``FileIdentityResolver``).
+2. Falls back to the gateway pairing store: when two channels were paired
+   under the same label/canonical id, they resolve to that id.
+3. Otherwise returns the per-platform id ``f"{platform}:{user_id}"`` — a
+   safe, non-merging default identical to the core resolver.
+
+Construction::
+
+    from praisonai.bots import StoreBackedIdentityResolver
+
+    resolver = StoreBackedIdentityResolver.from_env()
+    botos = BotOS(agent=agent, platforms=[...], identity_resolver=resolver)
+
+    # Link two channels to one canonical id
+    resolver.link("telegram", "12345", "alice")
+    resolver.link("whatsapp", "+44...", "alice")
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Optional
+
+from praisonaiagents.session.identity import FileIdentityResolver
+
+logger = logging.getLogger(__name__)
+
+
+class StoreBackedIdentityResolver(FileIdentityResolver):
+    """File-backed identity resolver augmented with pairing data.
+
+    Inherits the thread-safe, atomically-persisted link map from
+    :class:`praisonaiagents.session.identity.FileIdentityResolver` and adds
+    an optional read-through to a gateway :class:`PairingStore` so that
+    already-paired channels are recognised without an explicit ``link()``.
+
+    Resolution order for ``resolve(platform, user_id)``:
+
+    1. An explicit link registered via :meth:`link` (highest priority).
+    2. The pairing store's label for ``(user_id, platform)`` when that
+       channel is paired and carries a non-empty label (treated as the
+       canonical id) — lets paired users share a session out of the box.
+    3. ``f"{platform}:{user_id}"`` — the safe per-platform fallback.
+
+    Args:
+        path: JSON file for the explicit link map. Defaults to the core
+            resolver default (``$PRAISONAI_IDENTITY_PATH`` or
+            ``~/.praisonai/identity.json``).
+        pairing_store: Optional object exposing ``is_paired`` /
+            ``list_paired`` (e.g. ``praisonai.gateway.pairing.PairingStore``).
+            When ``None``, behaviour matches the plain file resolver.
+        use_pairing_label: When ``True`` (default) a paired channel's
+            ``label`` is used as its canonical id. Set ``False`` to ignore
+            labels and rely solely on explicit links.
+    """
+
+    def __init__(
+        self,
+        path: Optional[Path | str] = None,
+        pairing_store: Optional[Any] = None,
+        use_pairing_label: bool = True,
+    ) -> None:
+        super().__init__(path=path)
+        self._pairing_store = pairing_store
+        self._use_pairing_label = use_pairing_label
+
+    @classmethod
+    def from_env(
+        cls,
+        path: Optional[Path | str] = None,
+        store_dir: Optional[str] = None,
+        use_pairing_label: bool = True,
+    ) -> "StoreBackedIdentityResolver":
+        """Build a resolver wired to the default gateway pairing store.
+
+        The pairing store is loaded lazily and any failure (e.g. optional
+        deps unavailable) degrades gracefully to a plain file resolver.
+
+        Args:
+            path: Override for the explicit link-map JSON path.
+            store_dir: Override for the pairing store directory.
+            use_pairing_label: Forwarded to ``__init__``.
+        """
+        pairing_store = None
+        try:
+            from praisonai.gateway.pairing import PairingStore
+
+            pairing_store = PairingStore(store_dir=store_dir)
+        except Exception as e:  # pragma: no cover — optional/degraded path
+            logger.warning(
+                "StoreBackedIdentityResolver: pairing store unavailable, "
+                "falling back to link-map only: %s",
+                e,
+            )
+        return cls(
+            path=path,
+            pairing_store=pairing_store,
+            use_pairing_label=use_pairing_label,
+        )
+
+    def resolve(self, platform: str, platform_user_id: str) -> str:
+        # 1. Explicit links take precedence. The parent returns the
+        #    per-platform fallback when no explicit link exists; detect
+        #    that so we can consult the pairing store before giving up.
+        fallback = f"{platform}:{platform_user_id}"
+        with self._lock:
+            explicit = self._links.get((platform, platform_user_id))
+        if explicit is not None:
+            return explicit
+
+        # 2. Pairing-store read-through: a paired channel's label is the
+        #    canonical id shared across channels paired under it.
+        if self._pairing_store is not None and self._use_pairing_label:
+            try:
+                canonical = self._canonical_from_pairing(platform, platform_user_id)
+                if canonical:
+                    return canonical
+            except Exception as e:  # pragma: no cover — defensive
+                logger.warning("identity pairing lookup failed: %s", e)
+
+        # 3. Safe per-platform fallback.
+        return fallback
+
+    def link_paired(self) -> int:
+        """Materialise pairing-store labels as explicit links.
+
+        Scans the pairing store and registers an explicit link for every
+        paired channel whose label is non-empty, so paired users keep a
+        stable canonical id even if the pairing store later changes.
+
+        Returns the number of links created/updated.
+        """
+        if self._pairing_store is None:
+            return 0
+        count = 0
+        try:
+            paired = self._pairing_store.list_paired()
+        except Exception as e:  # pragma: no cover — defensive
+            logger.warning("identity link_paired failed to list pairings: %s", e)
+            return 0
+        for ch in paired:
+            label = getattr(ch, "label", "") or ""
+            channel_type = getattr(ch, "channel_type", "")
+            channel_id = getattr(ch, "channel_id", "")
+            if label and channel_type and channel_id:
+                # Write in-memory only; flush once after the loop to avoid
+                # N atomic disk writes when materialising many pairings.
+                with self._lock:
+                    self._links[(channel_type, channel_id)] = label
+                count += 1
+        if count:
+            self._flush()
+        return count
+
+    def all_links(self) -> list[tuple[str, str, str]]:
+        """Return every explicit link as ``(platform, user_id, canonical)``."""
+        with self._lock:
+            return [
+                (platform, user_id, canonical)
+                for (platform, user_id), canonical in self._links.items()
+            ]
+
+    def _canonical_from_pairing(
+        self, platform: str, platform_user_id: str
+    ) -> Optional[str]:
+        """Return the pairing label (canonical id) for a paired channel."""
+        store = self._pairing_store
+        # Fast path: most messages come from unpaired users. ``is_paired`` is
+        # an O(1) dict lookup, so short-circuit before the O(n) scan below.
+        is_paired = getattr(store, "is_paired", None)
+        if callable(is_paired) and not is_paired(platform_user_id, platform):
+            return None
+        list_paired = getattr(store, "list_paired", None)
+        if not callable(list_paired):
+            return None
+        for ch in list_paired():
+            if (
+                getattr(ch, "channel_id", None) == platform_user_id
+                and getattr(ch, "channel_type", None) == platform
+            ):
+                label = getattr(ch, "label", "") or ""
+                return label or None
+        return None
+
+
+__all__ = ["StoreBackedIdentityResolver"]