pyegeria 5.3.9.9.3__py3-none-any.whl → 5.5.3.3__py3-none-any.whl

pyegeria/core/load_config.py

@@ -0,0 +1,37 @@
+"""
+Compatibility shim for legacy imports.
+Re-exports configuration loading utilities from pyegeria.config.
+"""
+# Import config lazily inside functions to avoid import-time side effects in tests
+from importlib import import_module
+
+def load_app_config(env_file: str | None = None):
+    return import_module('pyegeria.config').load_app_config(env_file)
+
+def get_app_config(env_file: str | None = None):
+    return import_module('pyegeria.config').get_app_config(env_file)
+
+class PyegeriaSettings:
+    def __new__(cls, *args, **kwargs):
+        # Construct a real settings instance from pyegeria.config
+        return import_module('pyegeria.config').PyegeriaSettings(*args, **kwargs)
+
+    @classmethod
+    def with_env_file(cls, env_file: str):
+        return import_module('pyegeria.config').PyegeriaSettings.with_env_file(env_file)
+
+# expose the cached instance for tests that reset it directly
+from pyegeria.core import config as _config
+
+
+def __getattr__(name):
+    if name == "_app_config":
+        return _config._app_config
+    raise AttributeError(name)
+
+
+def __setattr__(name, value):
+    if name == "_app_config":
+        _config._app_config = value
+    else:
+        globals()[name] = value

pyegeria/core/logging_configuration.py

@@ -0,0 +1,207 @@
+
+"""
+SPDX-License-Identifier: Apache-2.0
+Copyright Contributors to the ODPi Egeria project.
+
+This module configures logging using loguru. The pyegeria library modules do not configure
+loguru automatically so that the calling application has control over the logging. However, if the
+calling application doesn't have its own logging setup, it can use this module to configure loguru logging.
+
+If the application uses another logging library, such as the built-in python logging, it can
+do so by redirecting loguru output. Here is an example:
+
+    # application.py - App uses standard logging, redirects Loguru)
+
+    import logging
+    import logging.config
+    import sys # For sys.stderr
+    from loguru import logger # Import Loguru's logger
+    from my_library.my_module import MyLibraryClass, library_function
+
+    # --- Standard Logging Configuration (for the application) ---
+    # This is your application's primary logging setup.
+    LOGGING_CONFIG = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "standard": {
+                "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+            }
+        },
+        "handlers": {
+            "console": {
+                "class": "logging.StreamHandler",
+                "level": "INFO",
+                "formatter": "standard",
+                "stream": "ext://sys.stdout"
+            },
+            "file": {
+                "class": "logging.handlers.RotatingFileHandler",
+                "level": "DEBUG",
+                "formatter": "standard",
+                "filename": "app_standard.log",
+                "maxBytes": 10485760,
+                "backupCount": 5
+            }
+        },
+        "loggers": {
+            # Root logger for the application
+            "": { # Empty string means the root logger
+                "handlers": ["console", "file"],
+                "level": "DEBUG", # Set the overall minimum level here
+                "propagate": False
+            }
+        }
+    }
+
+    try:
+        logging.config.dictConfig(LOGGING_CONFIG)
+        app_logger = logging.getLogger(__name__)
+        app_logger.info("Application standard logging configured successfully.")
+    except Exception as e:
+        print(f"Error configuring standard logging: {e}. Falling back to basicConfig.")
+        logging.basicConfig(level=logging.INFO)
+        app_logger = logging.getLogger(__name__)
+        app_logger.warning("Using basic logging due to configuration error.")
+
+    # --- Integrate Loguru with Standard Logging ---
+    # This is the key to "disabling" Loguru's separate output.
+
+    # 1. Remove Loguru's default handler (which outputs to stderr)
+    logger.remove(0)
+
+    # 2. Add a handler to Loguru that redirects messages to the standard logging module.
+    #    The level here determines what Loguru sends to standard logging.
+    logger.add(
+        logging.StreamHandler(sys.stderr), # You can use any standard logging handler here
+        level="DEBUG", # Loguru will send messages at this level or higher to standard logging
+        format="{message}" # Keep Loguru's format simple, let standard logging handle formatting
+    )
+
+    # Optional: If you want to completely suppress Loguru's output and rely solely on standard logging
+    # for your library's messages, you can set Loguru's level to a very high value:
+    # logger.level("CRITICAL") # This would make it only log critical errors
+    # Or, if you want to completely disable it (not recommended for general use):
+    # logger.disable("my_library") # This disables logging for the 'my_library' hierarchy
+
+    app_logger.info("Loguru integrated with standard logging.")
+
+    # --- Main Application Logic ---
+    if __name__ == "__main__":
+        app_logger.info("Application started.")
+
+        # Your library's logs will now go through the standard logging system
+        my_instance = MyLibraryClass("test_value")
+        processed = my_instance.process_data("hello world")
+        app_logger.info("Processed data: %s", processed)
+
+        library_function()
+
+        try:
+            my_instance.perform_risky_operation()
+        except Exception:
+            app_logger.error("Caught exception from risky operation in library.")
+
+        app_logger.info("Application finished.")
+
+To suppress logging, an application can do the following:
+    # application.py (Scenario C: App wants library to be silent)
+
+    from loguru import logger
+    from my_library.my_module import MyLibraryClass, library_function
+
+    # Remove Loguru's default handler
+    logger.remove(0)
+
+    # Completely disable logging for the 'my_library' hierarchy
+    logger.disable("my_library")
+
+    logger.info("Application started. Loguru for 'my_library' is disabled.")
+
+    my_instance = MyLibraryClass("test_value")
+    processed = my_instance.process_data("hello world") # These will not be logged by library
+    logger.info("Processed data: %s", processed) # This will be logged by app's logger
+
+    library_function() # This will not be logged by library
+
+    logger.info("Application finished.")
+
+"""
+
+# application.py (Scenario A: App uses Loguru)
+import os, sys
+from loguru import logger
+from pyegeria.core.config import settings as app_settings
+
+def console_log_filter(record):
+    if len(record["module"]) > 0:
+        module_ok = True
+    else:
+        module_ok = record["module"] in app_settings.logging.console_logging_enabled
+
+
+    return (module_ok
+            and
+            record["level"].name in app_settings.Logging.console_filter_levels
+            )
+
+def init_logging(log_init:bool= False):
+    if not log_init:
+       logger.disable("pyegeria")
+
+def config_logging(verbose: bool=False):
+    """
+    Configures logging for the application using Loguru.
+
+    This function sets up logging functionalities for the application. It reads
+    the necessary logging configurations, ensures the desired log directory exists,
+    and defines logging handlers for both file-based and console-based logging.
+    Log messages can be retained with a rotation and compression policy for file logs.
+
+    Raises:
+        OSError: If the log directory cannot be created.
+
+    """
+
+
+    # Get the directory for log files from the environment variable
+    log_app_settings = app_settings.Logging
+    log_directory = log_app_settings.log_directory
+    console_logging_level = log_app_settings.console_logging_level
+    logging_console_format = log_app_settings.logging_console_format
+    file_logging_level = log_app_settings.file_logging_level
+    logging_file_format = log_app_settings.logging_file_format
+    console_logging_enabled = log_app_settings.console_logging_enabled
+    enable_logging = log_app_settings.enable_logging
+
+    # Ensure the directory exists
+    os.makedirs(log_directory, exist_ok=True)
+
+    # Define the log file path
+    log_file_path = os.path.join(log_directory, "pyegeria.log")
+    # Remove Loguru's default stderr handler (id=0) if you want full control
+    logger.remove()
+
+    # Add your desired handlers for the application (and thus the library)
+    logger.add(log_file_path,
+               level=file_logging_level,
+               format=logging_file_format,
+               # filter = "",
+               retention="7 days",  # Keep logs for 7 days
+               rotation="10 MB", # rotate logs once they are 10mb
+               compression="zip")
+    logger.add(
+        sys.stderr,
+        level=console_logging_level,
+        format=logging_console_format,
+        filter=console_log_filter,
+        colorize=True
+    )
+
+    if enable_logging:
+        logger.enable("pyegeria")
+    logger.trace("Application started with Loguru configured.")
+
+
+
+

pyegeria/core/mcp_adapter.py

@@ -0,0 +1,144 @@
+"""
+SPDX-License-Identifier: Apache-2.0
+
+Thin adapter helpers to surface pyegeria FormatSets as MCP-style tools without
+side effects. This does NOT implement an MCP transport/server; it focuses on
+programmatic functions that an MCP server entry point can call.
+
+Only format sets that advertise DICT or ALL are considered eligible.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Dict, Optional
+
+from loguru import logger
+
+from pyegeria.view.base_report_formats import (
+    list_mcp_format_sets,
+    select_report_spec, find_report_specs,
+)
+from pyegeria.egeria_tech_client import EgeriaTech
+from pyegeria.view.format_set_executor import exec_report_spec, _async_run_report
+
+
+def list_reports() -> dict:
+    """List eligible format sets as MCP tools (support DICT or ALL)."""
+    return  list_mcp_format_sets()
+
+def run_find_report_specs(perspective: str= None, question: str= None, report_spec:str= None) -> Dict[str, Any]:
+    """
+    Find report specs that match the given perspective and question.
+
+    Args:
+        perspective (str): The perspective to search for (e.g., "Data Steward").
+        question (str): The question to search for (e.g., "What is the current status of the project?").
+        report_spec (str): The report spec to search for (e.g., "ProjectStatusReport").
+
+    Returns:
+        list[dict]: A list of dictionaries, each representing a matching report spec item.
+    """
+    perspective = None if perspective == "*" else perspective
+    question = None if question == "*" else question
+    report_spec = None if report_spec == "*" else report_spec
+
+    report_specs = find_report_specs(perspective=perspective, question=question, report_spec=report_spec)
+    if not report_specs:
+        raise ValueError(f"No report specs found for perspective '{perspective}' and question '{question}'")
+    return {"Matching Report Specs" : report_specs}
+
+def describe_report(name: str, output_type: str = "DICT") -> Dict[str, Any]:
+    """
+    Describe a format set for MCP discovery. If outputType != ANY, a concrete format
+    will be resolved; otherwise only metadata/action are returned.
+    """
+    meta = select_report_spec(name, output_type)
+    if not meta:
+        raise ValueError(f"Unknown or incompatible format set: {name}")
+    return meta
+
+
+def _execute_egeria_call_blocking(
+        *,
+        report: str,
+        params: Optional[Dict[str, Any]] = None,
+        view_server: Optional[str] = None,
+        view_url: Optional[str] = None,
+        user: Optional[str] = None,
+        user_pass: Optional[str] = None,) -> Dict[str, Any]:
+    """
+    Executes the synchronous, blocking Egeria client call on a dedicated worker thread.
+
+    You must replace the hardcoded return with your actual Egeria client logic here.
+    All code in this function runs in a blocking, synchronous manner.
+    """
+
+    print(
+        f"Format set: {report}\nparams: {json.dumps(params)}\nview_server: {view_server}\nview_url: {view_url}\nuser: {user}\nuser_pass: {user_pass}",
+        file=sys.stderr)
+    # Lazy import of settings to avoid circulars when optional args are None
+    # from pyegeria.config import settings as _settings
+    from pyegeria.core.config import settings as _settings
+
+
+    return exec_report_spec(
+        format_set_name=report,
+        output_format="DICT",
+        params=params or {},
+        view_server=view_server if view_server is not None else _settings.Environment.egeria_view_server,
+        view_url=view_url if view_url is not None else _settings.Environment.egeria_view_server_url,
+        user=user if user is not None else _settings.User_Profile.user_name,
+        user_pass=user_pass if user_pass is not None else _settings.User_Profile.user_pwd,
+    )
+    # # Returning the hardcoded success for now to prove the async structure works.
+    # return {
+    #     "status": "SUCCESS (Thread Test)",
+    #     "report_name": report_name,
+    #     "message": "The blocking call was successfully run on a separate thread, preventing timeout."
+    # }
+
+
+
+def run_report(
+    *,
+    report: str,
+    params: Optional[Dict[str, Any]] = None,
+    view_server: Optional[str] = None,
+    view_url: Optional[str] = None,
+    user: Optional[str] = None,
+    user_pass: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Execute a format set action as an MCP-style tool. Enforces DICT/ALL by default.
+    Caller may pass credentials explicitly; otherwise defaults are used from config.
+    """
+    print(f"Format set: {report}\nparams: {json.dumps(params)}\nview_server: {view_server}\nview_url: {view_url}\nuser: {user}\nuser_pass: {user_pass}", file=sys.stderr)
+    # Lazy import of settings to avoid circulars when optional args are None
+    from pyegeria.core.config import settings as _settings
+    logger.info(f"Format set: {report}\nparams: {json.dumps(params)}\nview_server: {view_server}\nview_url: {view_url}\nuser: {user}\nuser_pass: {user_pass}")
+    return exec_report_spec(
+        format_set_name=report,
+        output_format="DICT",
+        params=params or {},
+        view_server=view_server if view_server is not None else _settings.Environment.egeria_view_server,
+        view_url=view_url if view_url is not None else _settings.Environment.egeria_view_server_url,
+        user=user if user is not None else _settings.User_Profile.user_name,
+        user_pass=user_pass if user_pass is not None else _settings.User_Profile.user_pwd,
+    )
+
+async def _async_run_report_tool(
+    *,
+    report: str,
+    egeria_client: EgeriaTech,
+    params: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """
+    Execute a format set action as an MCP-style tool. Enforces DICT/ALL by default.
+    Caller may pass credentials explicitly; otherwise defaults are used from config.
+    """
+    # Lazy import of settings to avoid circulars when optional args are None
+
+    print(f"Report: {report}\n params: {json.dumps(params)}\n", file=sys.stderr)
+    result = await _async_run_report(report, egeria_client, output_format="DICT", params=params)
+    return result

pyegeria/core/mcp_server.py

@@ -0,0 +1,212 @@
+"""PDX-License-Identifier: Apache-2.0
+Copyright Contributors to the ODPi Egeria project.
+
+This module provides a basic MCP server for Egeria.
+"""
+import re
+import sys
+import nest_asyncio
+
+from typing import Any, Dict, Optional
+
+from mcp.server.fastmcp.exceptions import ValidationError
+
+from pyegeria.egeria_tech_client import EgeriaTech
+from pyegeria.core._exceptions import print_validation_error
+# from pyegeria.base_report_formats import find_report_specs
+
+GLOBAL_EGERIA_CLIENT: Optional[EgeriaTech] = None
+nest_asyncio.apply()
+
+try:
+    # We use Optional[] and List[] types, so we import them.
+    from mcp.server.fastmcp import FastMCP
+    from pyegeria.core.mcp_adapter import (
+        list_reports,
+        describe_report,
+        run_report, _execute_egeria_call_blocking,
+        _async_run_report_tool, run_find_report_specs
+    )
+
+    print("MCP import successful...", file=sys.stderr)
+except ImportError:
+    print("MCP import failed.", file=sys.stderr)
+    raise
+
+
+def _ok(result: Dict[str, Any]) -> Dict[str, Any]:
+    # Pass-through helper in case you want to normalize or add metadata
+    print("OK: Operation completed successfully.", file=sys.stderr)
+    return result
+
+
+def main() -> None:
+    # Initialize the server
+
+    global GLOBAL_EGERIA_CLIENT
+
+    try:
+        """ Runs ONCE when the server starts.
+            Initializes the Egeria client and stores it in the server's state.
+        """
+        print("DEBUG: Initializing Egeria client...", file=sys.stderr)
+        from pyegeria.core.config import settings as _settings
+        user_id = _settings.User_Profile.user_name
+        user_pwd = _settings.User_Profile.user_pwd
+
+        GLOBAL_EGERIA_CLIENT = EgeriaTech(
+            _settings.Environment.egeria_view_server,
+            _settings.Environment.egeria_view_server_url,
+            user_id,
+            user_pwd
+        )
+        print("DEBUG: Egeria Client initialized", file=sys.stderr)
+        GLOBAL_EGERIA_CLIENT.create_egeria_bearer_token("erinoverview", "secret")
+        print("DEBUG: Egeria Client connected", file=sys.stderr)
+
+    except ValidationError as e:
+        print_validation_error(e)
+        raise
+    except Exception as e:
+        print(f"DEBUG: Exception occurred: {str(e)}", file=sys.stderr)
+        raise
+
+    srv = FastMCP(name="pyegeria-mcp")
+    print("Starting MCP server...", file=sys.stderr)
+
+    # list_reports tool (formerly list_format_sets)
+    @srv.tool(name="list_reports")
+    def list_reports_tool() -> Dict[str, Any]:
+        """Lists all available reports (FormatSets)."""
+        print("DEBUG: Listing reports...", file=sys.stderr)
+        return _ok(list_reports())
+
+    @srv.tool(name="find_report_specs")
+    def find_report_specs_tool(perspective: str=None, question: str=None, report_spec: str=None) -> Dict[str, Any]:
+        """Finds report specs that match the given perspective, question, and report spec."""
+        print("DEBUG: Finding report specs...", file=sys.stderr)
+        return _ok(run_find_report_specs(perspective=perspective, question=question, report_spec=report_spec))
+
+
+    @srv.tool(name="describe_report")
+    def describe_report_tool(name: str, output_type: str = "DICT") -> Dict[str, Any]:
+        """Returns the schema and details for a specified report."""
+        # FastMCP handles validation of 'name' and 'output_type' types automatically.
+        print(f"DEBUG: Describing report: {name} with output type: {output_type}", file=sys.stderr)
+        try:
+            return _ok(describe_report(name, output_type))
+        except Exception as e:
+            print(f"DEBUG: Exception during describe_report: {str(e)}", file=sys.stderr)
+            raise
+
+    @srv.tool(name="run_report")
+    async def run_report_tool(
+            report_name: str,
+            search_string: str = "*",
+            page_size: Optional[int] = 0,
+            start_from: Optional[int] = 0,
+            starts_with: Optional[bool] = None,
+            ends_with: Optional[bool] = None,
+            ignore_case: Optional[bool] = None,
+            output_format: str = "DICT"
+    ) -> Dict[str, Any]:
+        import asyncio
+        import nest_asyncio
+        nest_asyncio.apply()
+
+        """Run a report with the specified parameters."""
+        print("DEBUG: Running report...", file=sys.stderr)
+        # 1. Automatic Validation: FastMCP/Pydantic ensures types are correct.
+
+        # 2. Manual Validation (for specific values like output_format)
+        if output_format not in ["DICT", "JSON", "REPORT", "MERMAID", "HTML"]:
+            print(f"DEBUG: Invalid output_format: {output_format}", file=sys.stderr)
+            raise ValueError(
+                f"Invalid output_format: {output_format}. Must be one of ['DICT', 'JSON', 'REPORT', 'MERMAID', 'HTML'].")
+
+        # 3. Build params dictionary with only non-None values for clean passing
+        params = {
+            "search_string": search_string,
+            "page_size": page_size,
+            "start_from": start_from,
+            "starts_with": starts_with,
+            "ends_with": ends_with,
+            "ignore_case": ignore_case,
+        }
+        # Filter out None values before passing to run_report
+        params = {k: v for k, v in params.items() if v is not None}
+
+        print(f"DEBUG: Running report={report_name} with params={params}", file=sys.stderr)
+
+        try:
+
+            egeria_client: EgeriaTech = GLOBAL_EGERIA_CLIENT
+            print("DEBUG: Egeria Client connected", file=sys.stderr)
+            result = await asyncio.wait_for(
+                _async_run_report_tool(
+                    report=report_name,
+                    egeria_client=egeria_client,
+                    params=params),
+                timeout=30  # Adjust timeout as needed
+            )
+
+            print("DEBUG: run_report completed successfully", file=sys.stderr)
+            return _ok(result)
+        except Exception as e:
+            # Re-raise the exception to be sent back as a JSON-RPC error
+            print(f"DEBUG: Exception occurred: {str(e)}", file=sys.stderr)
+            raise
+
+    @srv.tool(name="prompt")
+    async def natural_language_prompt(prompt: str) -> Dict[str, Any]:
+        """
+        Handles natural language queries from the user.
+        In a production environment, this would call an LLM API.
+        """
+        print(f"DEBUG: Received natural language prompt: {prompt}", file=sys.stderr)
+
+        # Example of simple logic: If the user asks to list reports, delegate to the tool.
+        if "list" in prompt.lower() and "reports" in prompt.lower():
+            print("DEBUG: Delegating prompt to list_reports tool.", file=sys.stderr)
+            return list_reports()  # This is sync, so no await needed
+        elif "run" in prompt.lower() and "report" in prompt.lower():
+            print("DEBUG: Delegating prompt to run_report tool.", file=sys.stderr)
+
+            match = re.search(r'report\s+([a-zA-Z0-9]+)', prompt, re.IGNORECASE)
+            report_name = match.group(1) if match else None
+
+            if report_name:
+                print(f"DEBUG: Extracted report name: {report_name}", file=sys.stderr)
+
+                page_size_match = re.search(r'page size of\s+(\d+)', prompt, re.IGNORECASE)
+                page_size = int(page_size_match.group(1)) if page_size_match else None
+
+                search_match = re.search(r'search for\s+(.*?)(?:\s+in\s+report|\.|$)', prompt, re.IGNORECASE)
+
+                if search_match:
+                    search_string = search_match.group(1).strip()
+
+                    if search_string:
+                        print(
+                            f"DEBUG: Delegating prompt to run_report tool. Report: {report_name}, Search: '{search_string}'",
+                            file=sys.stderr)
+
+                        # AWAIT the async function call
+                        return await run_report_tool(report_name=report_name, search_string=search_string,
+                                                     page_size=page_size)
+
+                # AWAIT the async function call
+                return await run_report_tool(report_name=report_name, page_size=page_size)
+
+        return {
+            "response": f"Acknowledged natural language query: '{prompt}'. This would be sent to an LLM."
+        }
+
+    # CRITICAL: This is the missing step. It tells the server to read and process
+    # JSON-RPC messages from standard input (stdin).
+    srv.run()
+    print("MCP server finished running.", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()