empathy-framework 3.7.0__py3-none-any.whl → 3.7.1__py3-none-any.whl

empathy_os/cli.py

@@ -26,6 +26,7 @@ from empathy_os.pattern_library import PatternLibrary
 from empathy_os.persistence import MetricsCollector, PatternPersistence, StateManager
 from empathy_os.platform_utils import setup_asyncio_policy
 from empathy_os.templates import cmd_new
+from empathy_os.wizard_factory_cli import add_wizard_factory_commands
 from empathy_os.workflows import (
     cmd_fix_all,
     cmd_learn,
@@ -284,7 +285,9 @@ def cmd_version(args):
     logger.info("Displaying version information")
     try:
         version = get_version("empathy")
-    except Exception:
+    except Exception as e:
+        # Package metadata not available or invalid (development install)
+        logger.debug(f"Version not available: {e}")
         version = "unknown"
     logger.info(f"Empathy v{version}")
     logger.info("Copyright 2025 Smart-AI-Memory")
@@ -640,10 +643,21 @@ def cmd_validate(args):
         logger.info(f"  Confidence Threshold: {config.confidence_threshold}")
         logger.info(f"  Persistence Backend: {config.persistence_backend}")
         logger.info(f"  Metrics Enabled: {config.metrics_enabled}")
-    except Exception as e:
+    except (OSError, FileNotFoundError) as e:
+        # Config file not found or cannot be read
+        logger.error(f"Configuration file error: {e}")
+        logger.error(f"✗ Cannot read configuration file: {e}")
+        sys.exit(1)
+    except ValueError as e:
+        # Invalid configuration values
         logger.error(f"Configuration validation failed: {e}")
         logger.error(f"✗ Configuration invalid: {e}")
         sys.exit(1)
+    except Exception as e:
+        # Unexpected errors during config validation
+        logger.exception(f"Unexpected error validating configuration: {e}")
+        logger.error(f"✗ Configuration invalid: {e}")
+        sys.exit(1)
 
 
 def cmd_info(args):
@@ -734,8 +748,19 @@ def cmd_patterns_export(args):
 
         logger.info(f"Loaded {len(library.patterns)} patterns from {input_file}")
         logger.info(f"✓ Loaded {len(library.patterns)} patterns from {input_file}")
+    except (OSError, FileNotFoundError) as e:
+        # Input file not found or cannot be read
+        logger.error(f"Pattern file error: {e}")
+        logger.error(f"✗ Cannot read pattern file: {e}")
+        sys.exit(1)
+    except (ValueError, KeyError) as e:
+        # Invalid pattern data format
+        logger.error(f"Pattern data error: {e}")
+        logger.error(f"✗ Invalid pattern data: {e}")
+        sys.exit(1)
     except Exception as e:
-        logger.error(f"Failed to load patterns: {e}")
+        # Unexpected errors loading patterns
+        logger.exception(f"Unexpected error loading patterns: {e}")
         logger.error(f"✗ Failed to load patterns: {e}")
         sys.exit(1)
 
@@ -748,8 +773,14 @@ def cmd_patterns_export(args):
 
         logger.info(f"Saved {len(library.patterns)} patterns to {output_file}")
         logger.info(f"✓ Saved {len(library.patterns)} patterns to {output_file}")
+    except (OSError, FileNotFoundError, PermissionError) as e:
+        # Cannot write output file
+        logger.error(f"Pattern file write error: {e}")
+        logger.error(f"✗ Cannot write pattern file: {e}")
+        sys.exit(1)
     except Exception as e:
-        logger.error(f"Failed to save patterns: {e}")
+        # Unexpected errors saving patterns
+        logger.exception(f"Unexpected error saving patterns: {e}")
         logger.error(f"✗ Failed to save patterns: {e}")
         sys.exit(1)
 
@@ -1041,8 +1072,19 @@ def cmd_metrics_show(args):
         logger.info(f"  Level 3: {stats.get('level_3_count', 0)} uses")
         logger.info(f"  Level 4: {stats.get('level_4_count', 0)} uses")
         logger.info(f"  Level 5: {stats.get('level_5_count', 0)} uses")
+    except (OSError, FileNotFoundError) as e:
+        # Database file not found
+        logger.error(f"Metrics database error: {e}")
+        logger.error(f"✗ Cannot read metrics database: {e}")
+        sys.exit(1)
+    except KeyError as e:
+        # User not found in database
+        logger.error(f"User not found in metrics: {e}")
+        logger.error(f"✗ User {user_id} not found: {e}")
+        sys.exit(1)
     except Exception as e:
-        logger.error(f"Failed to retrieve metrics for user {user_id}: {e}")
+        # Unexpected errors retrieving metrics
+        logger.exception(f"Unexpected error retrieving metrics for user {user_id}: {e}")
         logger.error(f"✗ Failed to retrieve metrics: {e}")
         sys.exit(1)
 
@@ -1096,7 +1138,17 @@ def cmd_run(args):
             persistence_enabled=config.persistence_enabled,
         )
         print("✓ Empathy OS initialized")
+    except ValueError as e:
+        # Invalid configuration parameters
+        print(f"✗ Configuration error: {e}")
+        sys.exit(1)
+    except (OSError, FileNotFoundError, PermissionError) as e:
+        # Cannot access required files/directories
+        print(f"✗ File system error: {e}")
+        sys.exit(1)
     except Exception as e:
+        # Unexpected initialization failure
+        logger.exception(f"Unexpected error initializing Empathy OS: {e}")
         print(f"✗ Failed to initialize Empathy OS: {e}")
         sys.exit(1)
 
@@ -1180,7 +1232,12 @@ def cmd_run(args):
         except KeyboardInterrupt:
             print("\n\n👋 Goodbye!")
             break
+        except (ValueError, KeyError) as e:
+            # Invalid input or response structure
+            print(f"\n✗ Input error: {e}\n")
         except Exception as e:
+            # Unexpected errors in interactive loop - log and continue
+            logger.exception(f"Unexpected error in interactive loop: {e}")
             print(f"\n✗ Error: {e}\n")
 
 
@@ -1223,7 +1280,13 @@ def cmd_inspect(args):
             print(f"✗ Pattern library not found: {db_path}")
             print("  Tip: Use 'empathy-framework wizard' to set up your first project")
             sys.exit(1)
+        except (ValueError, KeyError) as e:
+            # Invalid pattern data format
+            print(f"✗ Invalid pattern data: {e}")
+            sys.exit(1)
         except Exception as e:
+            # Unexpected errors loading patterns
+            logger.exception(f"Unexpected error loading patterns: {e}")
             print(f"✗ Failed to load patterns: {e}")
             sys.exit(1)
 
@@ -1245,7 +1308,17 @@ def cmd_inspect(args):
             for level in range(1, 6):
                 count = stats.get(f"level_{level}_count", 0)
                 print(f"    Level {level}: {count} times")
+        except (OSError, FileNotFoundError) as e:
+            # Database file not found
+            print(f"✗ Metrics database not found: {e}")
+            sys.exit(1)
+        except KeyError as e:
+            # User not found
+            print(f"✗ User {user_id} not found: {e}")
+            sys.exit(1)
         except Exception as e:
+            # Unexpected errors loading metrics
+            logger.exception(f"Unexpected error loading metrics: {e}")
             print(f"✗ Failed to load metrics: {e}")
             sys.exit(1)
 
@@ -1262,7 +1335,13 @@ def cmd_inspect(args):
                 print("\n  Users:")
                 for uid in users:
                     print(f"    • {uid}")
+        except (OSError, FileNotFoundError) as e:
+            # State directory not found
+            print(f"✗ State directory not found: {e}")
+            sys.exit(1)
         except Exception as e:
+            # Unexpected errors loading state
+            logger.exception(f"Unexpected error loading state: {e}")
             print(f"✗ Failed to load state: {e}")
             sys.exit(1)
 
@@ -1314,7 +1393,17 @@ def cmd_export(args):
         print(f"✗ Source file not found: {db_path}")
         print("  Tip: Patterns are saved automatically when using the framework")
         sys.exit(1)
+    except (OSError, PermissionError) as e:
+        # Cannot write output file
+        print(f"✗ Cannot write to file: {e}")
+        sys.exit(1)
+    except (ValueError, KeyError) as e:
+        # Invalid pattern data
+        print(f"✗ Invalid pattern data: {e}")
+        sys.exit(1)
     except Exception as e:
+        # Unexpected errors during export
+        logger.exception(f"Unexpected error exporting patterns: {e}")
         print(f"✗ Export failed: {e}")
         sys.exit(1)
 
@@ -1367,7 +1456,17 @@ def cmd_import(args):
     except FileNotFoundError:
         print(f"✗ Input file not found: {input_file}")
         sys.exit(1)
+    except (ValueError, KeyError) as e:
+        # Invalid pattern data format
+        print(f"✗ Invalid pattern data: {e}")
+        sys.exit(1)
+    except (OSError, PermissionError) as e:
+        # Cannot read input or write to database
+        print(f"✗ File access error: {e}")
+        sys.exit(1)
     except Exception as e:
+        # Unexpected errors during import
+        logger.exception(f"Unexpected error importing patterns: {e}")
         print(f"✗ Import failed: {e}")
         sys.exit(1)
 
@@ -1940,7 +2039,11 @@ def cmd_workflow(args):
                         else:
                             try:
                                 final_output_serializable[k] = str(v)
-                            except Exception:
+                            except Exception as e:  # noqa: BLE001
+                                # INTENTIONAL: Silently skip any non-serializable objects
+                                # This is a best-effort serialization for JSON output
+                                # We cannot predict all possible object types users might return
+                                logger.debug(f"Cannot serialize field {k}: {e}")
                                 pass
                 else:
                     final_output_serializable = None
@@ -2668,6 +2771,9 @@ def main():
     )
     parser_achievements.set_defaults(func=cmd_achievements)
 
+    # Wizard Factory commands (create wizards 12x faster)
+    add_wizard_factory_commands(subparsers)
+
     # Parse arguments
     args = parser.parse_args()
 
@@ -2679,8 +2785,12 @@ def main():
         if args.command and args.command not in ("dashboard", "run"):
             try:
                 show_tip_if_available(args.command)
-            except Exception:
-                pass  # Don't fail on discovery errors
+            except Exception as e:  # noqa: BLE001
+                # INTENTIONAL: Discovery tips are optional UX enhancements
+                # They should never cause command execution to fail
+                # Cannot predict all possible errors from discovery system
+                logger.debug(f"Discovery tip not available for {args.command}: {e}")
+                pass
 
         return result if result is not None else 0
     parser.print_help()

empathy_os/cli_unified.py

@@ -372,6 +372,78 @@ def wizard_run(
     subprocess.run(["empathy-scan", str(path), "--wizards", name], check=False)
 
 
+@wizard_app.command("create")
+def wizard_create(
+    name: str = typer.Argument(..., help="Wizard name (snake_case)"),
+    domain: str = typer.Option(
+        ..., "--domain", "-d", help="Domain (healthcare, finance, software)"
+    ),
+    wizard_type: str = typer.Option(
+        "domain", "--type", "-t", help="Wizard type (domain, coach, ai)"
+    ),
+    methodology: str = typer.Option(
+        "pattern", "--methodology", "-m", help="Methodology (pattern, tdd)"
+    ),
+    patterns: str | None = typer.Option(
+        None, "--patterns", "-p", help="Comma-separated pattern IDs"
+    ),
+    interactive: bool = typer.Option(
+        False, "--interactive", "-i", help="Interactive pattern selection"
+    ),
+):
+    """Create a new wizard using Wizard Factory (12x faster)."""
+    cmd = [
+        sys.executable,
+        "-m",
+        "scaffolding",
+        "create",
+        name,
+        "--domain",
+        domain,
+        "--type",
+        wizard_type,
+        "--methodology",
+        methodology,
+    ]
+    if patterns:
+        cmd.extend(["--patterns", patterns])
+    if interactive:
+        cmd.append("--interactive")
+    subprocess.run(cmd, check=False)
+
+
+@wizard_app.command("list-patterns")
+def wizard_list_patterns():
+    """List all available wizard patterns."""
+    subprocess.run([sys.executable, "-m", "scaffolding", "list-patterns"], check=False)
+
+
+@wizard_app.command("generate-tests")
+def wizard_generate_tests(
+    wizard_id: str = typer.Argument(..., help="Wizard ID"),
+    patterns: str = typer.Option(..., "--patterns", "-p", help="Comma-separated pattern IDs"),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Output directory"),
+):
+    """Generate tests for a wizard."""
+    cmd = [sys.executable, "-m", "test_generator", "generate", wizard_id, "--patterns", patterns]
+    if output:
+        cmd.extend(["--output", str(output)])
+    subprocess.run(cmd, check=False)
+
+
+@wizard_app.command("analyze")
+def wizard_analyze(
+    wizard_id: str = typer.Argument(..., help="Wizard ID"),
+    patterns: str = typer.Option(..., "--patterns", "-p", help="Wizard ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON format"),
+):
+    """Analyze wizard risk and get coverage recommendations."""
+    cmd = [sys.executable, "-m", "test_generator", "analyze", wizard_id, "--patterns", patterns]
+    if json_output:
+        cmd.append("--json")
+    subprocess.run(cmd, check=False)
+
+
 # =============================================================================
 # WORKFLOW SUBCOMMAND GROUP
 # =============================================================================
@@ -397,6 +469,50 @@ def workflow_run(
     )
 
 
+@workflow_app.command("create")
+def workflow_create(
+    name: str = typer.Argument(..., help="Workflow name (kebab-case, e.g., bug-scanner)"),
+    description: str = typer.Option(None, "--description", "-d", help="Workflow description"),
+    patterns: str = typer.Option(None, "--patterns", "-p", help="Comma-separated pattern IDs"),
+    stages: str = typer.Option(None, "--stages", "-s", help="Comma-separated stage names"),
+    tier_map: str = typer.Option(
+        None, "--tier-map", "-t", help="Tier map (e.g., analyze:CHEAP,process:CAPABLE)"
+    ),
+    output: Path = typer.Option(None, "--output", "-o", help="Output directory"),
+):
+    """Create a new workflow using Workflow Factory (12x faster)."""
+    cmd = [sys.executable, "-m", "workflow_scaffolding", "create", name]
+    if description:
+        cmd.extend(["--description", description])
+    if patterns:
+        cmd.extend(["--patterns", patterns])
+    if stages:
+        cmd.extend(["--stages", stages])
+    if tier_map:
+        cmd.extend(["--tier-map", tier_map])
+    if output:
+        cmd.extend(["--output", str(output)])
+    subprocess.run(cmd, check=False)
+
+
+@workflow_app.command("list-patterns")
+def workflow_list_patterns():
+    """List available workflow patterns."""
+    subprocess.run([sys.executable, "-m", "workflow_scaffolding", "list-patterns"], check=False)
+
+
+@workflow_app.command("recommend")
+def workflow_recommend(
+    workflow_type: str = typer.Argument(
+        ..., help="Workflow type (code-analysis, simple, multi-agent, etc.)"
+    ),
+):
+    """Recommend patterns for a workflow type."""
+    subprocess.run(
+        [sys.executable, "-m", "workflow_scaffolding", "recommend", workflow_type], check=False
+    )
+
+
 # =============================================================================
 # UTILITY COMMANDS
 # =============================================================================
@@ -435,10 +551,14 @@ def cheatsheet():
 [bold]Workflows[/bold]
   empathy workflow list     Show available workflows
   empathy workflow run <name>   Execute a workflow
+  empathy workflow create <name> -p <patterns>  Create workflow (12x faster)
+  empathy workflow list-patterns                List available patterns
 
 [bold]Wizards[/bold]
   empathy wizard list       Show available wizards
-  empathy wizard run <name> Execute a wizard""",
+  empathy wizard run <name> Execute a wizard
+  empathy wizard create <name> -d <domain>  Create wizard (12x faster)
+  empathy wizard list-patterns              List available patterns""",
             title="[bold blue]Empathy Framework Cheatsheet[/bold blue]",
         ),
     )

empathy_os/config/__init__.py

@@ -0,0 +1,63 @@
+"""Configuration management for Empathy Framework.
+
+This package provides:
+1. Original EmpathyConfig (backward compatible)
+2. XML enhancement configurations (new)
+
+Copyright 2026 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+# Import original config from parent module's config.py for backward compatibility
+import importlib.util
+import sys
+from pathlib import Path
+
+# Check if PyYAML is available
+try:
+    import yaml  # noqa: F401
+
+    YAML_AVAILABLE = True
+except ImportError:
+    YAML_AVAILABLE = False
+
+# Load the original config.py module directly
+config_py_path = Path(__file__).parent.parent / "config.py"
+spec = importlib.util.spec_from_file_location("empathy_os_config_legacy", config_py_path)
+if spec and spec.loader:
+    legacy_config = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(legacy_config)
+    EmpathyConfig = legacy_config.EmpathyConfig
+    load_config = legacy_config.load_config
+else:
+    # Fallback if import fails
+    EmpathyConfig = None
+    load_config = None
+
+# Import XML enhancement configs
+from empathy_os.config.xml_config import (  # noqa: E402
+    AdaptiveConfig,
+    EmpathyXMLConfig,
+    I18nConfig,
+    MetricsConfig,
+    OptimizationConfig,
+    XMLConfig,
+    get_config,
+    set_config,
+)
+
+__all__ = [
+    # Original config (backward compatible)
+    "EmpathyConfig",
+    "load_config",
+    "YAML_AVAILABLE",
+    # XML enhancement configs
+    "XMLConfig",
+    "OptimizationConfig",
+    "AdaptiveConfig",
+    "I18nConfig",
+    "MetricsConfig",
+    "EmpathyXMLConfig",
+    "get_config",
+    "set_config",
+]

empathy_os/config/xml_config.py

@@ -0,0 +1,239 @@
+"""Configuration system for XML-enhanced prompting features.
+
+Provides feature flags and settings for all 6 XML enhancement options:
+1. Workflow migration settings
+2. XML schema validation
+3. Prompt metrics tracking
+4. Context window optimization
+5. Dynamic prompt adaptation
+6. Multi-language support
+
+Copyright 2026 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class XMLConfig:
+    """XML prompting configuration.
+
+    Controls XML-enhanced prompt behavior and validation.
+    """
+
+    use_xml_structure: bool = True  # Default to XML prompts
+    validate_schemas: bool = False  # Feature flag for validation
+    schema_dir: str = ".empathy/schemas"
+    strict_validation: bool = False  # Fail on validation errors
+
+
+@dataclass
+class OptimizationConfig:
+    """Context window optimization configuration.
+
+    Controls prompt compression and token reduction strategies.
+    """
+
+    compression_level: str = "moderate"  # none, light, moderate, aggressive
+    use_short_tags: bool = True
+    strip_whitespace: bool = True
+    cache_system_prompts: bool = True
+    max_context_tokens: int = 8000
+
+
+@dataclass
+class AdaptiveConfig:
+    """Adaptive prompting configuration.
+
+    Controls dynamic model tier and compression selection based on task complexity.
+    """
+
+    enable_adaptation: bool = True
+    model_tier_mapping: dict[str, str] = field(
+        default_factory=lambda: {
+            "simple": "gpt-3.5-turbo",
+            "moderate": "gpt-4",
+            "complex": "gpt-4",
+            "very_complex": "gpt-4-turbo-preview",
+        }
+    )
+    complexity_thresholds: dict[str, int] = field(
+        default_factory=lambda: {
+            "simple_tokens": 100,
+            "moderate_tokens": 500,
+            "complex_tokens": 2000,
+        }
+    )
+
+
+@dataclass
+class I18nConfig:
+    """Internationalization configuration.
+
+    Controls multi-language support for XML prompts.
+    """
+
+    default_language: str = "en"
+    translate_tags: bool = False  # Keep tags in English by default
+    translate_content: bool = True
+    fallback_to_english: bool = True
+    translation_dir: str = ".empathy/translations"
+
+
+@dataclass
+class MetricsConfig:
+    """Metrics tracking configuration.
+
+    Controls prompt performance metrics collection and storage.
+    """
+
+    enable_tracking: bool = True
+    metrics_file: str = ".empathy/prompt_metrics.json"
+    track_token_usage: bool = True
+    track_latency: bool = True
+    track_retries: bool = True
+    track_parsing_success: bool = True
+
+
+@dataclass
+class EmpathyXMLConfig:
+    """Main Empathy XML enhancement configuration.
+
+    Combines all feature configurations with centralized management.
+
+    Usage:
+        config = EmpathyXMLConfig.load_from_file()
+        if config.xml.use_xml_structure:
+            use_xml_prompts()
+
+        # Or create custom config
+        config = EmpathyXMLConfig(
+            xml=XMLConfig(validate_schemas=True),
+            metrics=MetricsConfig(enable_tracking=True)
+        )
+        config.save_to_file()
+    """
+
+    xml: XMLConfig = field(default_factory=XMLConfig)
+    optimization: OptimizationConfig = field(default_factory=OptimizationConfig)
+    adaptive: AdaptiveConfig = field(default_factory=AdaptiveConfig)
+    i18n: I18nConfig = field(default_factory=I18nConfig)
+    metrics: MetricsConfig = field(default_factory=MetricsConfig)
+
+    @classmethod
+    def load_from_file(cls, config_file: str = ".empathy/config.json") -> "EmpathyXMLConfig":
+        """Load configuration from JSON file.
+
+        Args:
+            config_file: Path to config file (default: .empathy/config.json)
+
+        Returns:
+            EmpathyXMLConfig instance loaded from file, or default config if file doesn't exist
+        """
+        path = Path(config_file)
+
+        if not path.exists():
+            # Return default config if file doesn't exist
+            return cls()
+
+        try:
+            with open(path) as f:
+                data = json.load(f)
+
+            # Reconstruct nested dataclasses
+            return cls(
+                xml=XMLConfig(**data.get("xml", {})),
+                optimization=OptimizationConfig(**data.get("optimization", {})),
+                adaptive=AdaptiveConfig(**data.get("adaptive", {})),
+                i18n=I18nConfig(**data.get("i18n", {})),
+                metrics=MetricsConfig(**data.get("metrics", {})),
+            )
+        except Exception as e:
+            # Return default config on error
+            print(f"Warning: Failed to load config from {config_file}: {e}")
+            return cls()
+
+    def save_to_file(self, config_file: str = ".empathy/config.json") -> None:
+        """Save configuration to JSON file.
+
+        Args:
+            config_file: Path to save config (default: .empathy/config.json)
+        """
+        path = Path(config_file)
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        data = {
+            "xml": asdict(self.xml),
+            "optimization": asdict(self.optimization),
+            "adaptive": asdict(self.adaptive),
+            "i18n": asdict(self.i18n),
+            "metrics": asdict(self.metrics),
+        }
+
+        with open(path, "w") as f:
+            json.dump(data, f, indent=2)
+
+    @classmethod
+    def from_env(cls) -> "EmpathyXMLConfig":
+        """Load configuration from environment variables.
+
+        Environment variables:
+            EMPATHY_XML_ENABLED: Enable XML prompts (default: true)
+            EMPATHY_VALIDATION_ENABLED: Enable schema validation (default: false)
+            EMPATHY_METRICS_ENABLED: Enable metrics tracking (default: true)
+            EMPATHY_OPTIMIZATION_LEVEL: Compression level (default: moderate)
+            EMPATHY_ADAPTIVE_ENABLED: Enable adaptive prompts (default: true)
+
+        Returns:
+            EmpathyXMLConfig with settings from environment variables
+        """
+        return cls(
+            xml=XMLConfig(
+                use_xml_structure=os.getenv("EMPATHY_XML_ENABLED", "true").lower() == "true",
+                validate_schemas=os.getenv("EMPATHY_VALIDATION_ENABLED", "false").lower() == "true",
+            ),
+            optimization=OptimizationConfig(
+                compression_level=os.getenv("EMPATHY_OPTIMIZATION_LEVEL", "moderate"),
+            ),
+            adaptive=AdaptiveConfig(
+                enable_adaptation=os.getenv("EMPATHY_ADAPTIVE_ENABLED", "true").lower() == "true",
+            ),
+            metrics=MetricsConfig(
+                enable_tracking=os.getenv("EMPATHY_METRICS_ENABLED", "true").lower() == "true",
+            ),
+        )
+
+
+# Global default configuration instance
+_global_config: EmpathyXMLConfig | None = None
+
+
+def get_config() -> EmpathyXMLConfig:
+    """Get global configuration instance.
+
+    Returns cached config or loads from file if not yet loaded.
+
+    Returns:
+        Global EmpathyXMLConfig instance
+    """
+    global _global_config
+
+    if _global_config is None:
+        # Try to load from file, fall back to defaults
+        _global_config = EmpathyXMLConfig.load_from_file()
+
+    return _global_config
+
+
+def set_config(config: EmpathyXMLConfig) -> None:
+    """Set global configuration instance.
+
+    Args:
+        config: EmpathyXMLConfig to use globally
+    """
+    global _global_config
+    _global_config = config