open-edison 0.1.16__py3-none-any.whl → 0.1.19__py3-none-any.whl

src/server.py

@@ -6,6 +6,7 @@ No multi-user support, no complex routing - just a straightforward proxy.
 """
 
 import asyncio
+import json
 import traceback
 from collections.abc import Awaitable, Callable, Coroutine
 from pathlib import Path
@@ -23,7 +24,6 @@ from pydantic import BaseModel, Field
 
 from src.config import MCPServerConfig, config
 from src.config import get_config_dir as _get_cfg_dir  # type: ignore[attr-defined]
-from src.mcp_manager import MCPManager
 from src.middleware.session_tracking import (
     MCPSessionModel,
     create_db_session,
@@ -57,8 +57,7 @@ class OpenEdisonProxy:
         self.port: int = port
 
         # Initialize components
-        self.mcp_manager: MCPManager = MCPManager()
-        self.single_user_mcp: SingleUserMCP = SingleUserMCP(self.mcp_manager)
+        self.single_user_mcp: SingleUserMCP = SingleUserMCP()
 
         # Initialize FastAPI app for management
         self.fastapi_app: FastAPI = self._create_fastapi_app()
@@ -184,30 +183,33 @@ class OpenEdisonProxy:
             """
             Resolve a JSON config file path consistently with src.config defaults.
 
-            Precedence for reads (and writes if chosen):
-            1) Repository root next to src/ (editable/dev) if file exists
-            2) Config dir (OPEN_EDISON_CONFIG_DIR or platform default)
-               - If missing, bootstrap from repo root default when available
-            3) Current working directory as last resort
+            Precedence for reads and writes:
+            1) Config dir (OPEN_EDISON_CONFIG_DIR or platform default) — if file exists
+            2) Repository/package defaults next to src/ — and bootstrap a copy into the config dir if missing
+            3) Config dir target path (even if not yet created) as last resort
             """
-            # 1) Prefer repository root next to src/
-            repo_candidate = Path(__file__).parent.parent / filename
-            if repo_candidate.exists():
-                return repo_candidate
-
-            # 2) Config directory
+            # 1) Config directory (preferred)
             try:
                 base = _get_cfg_dir()
             except Exception:
                 base = Path.cwd()
             target = base / filename
-            if (not target.exists()) and repo_candidate.exists():
+            if target.exists():
+                return target
+
+            # 2) Repository/package defaults next to src/
+            repo_candidate = Path(__file__).parent.parent / filename
+            if repo_candidate.exists():
+                # Bootstrap a copy into config dir when possible
                 try:
                     target.parent.mkdir(parents=True, exist_ok=True)
                     target.write_text(repo_candidate.read_text(encoding="utf-8"), encoding="utf-8")
                 except Exception:
                     pass
-            return target if target.exists() else repo_candidate
+                return target if target.exists() else repo_candidate
+
+            # 3) Fall back to config dir path (will be created on save)
+            return target
 
         async def _serve_json(filename: str) -> Response:  # type: ignore[override]
             if filename not in allowed_json_files:
@@ -238,23 +240,28 @@ class OpenEdisonProxy:
                 content = body.get("content", "")
                 if not isinstance(content, str):
                     raise ValueError("content must be string")
+                source: str = "unknown"
                 if isinstance(name, str) and name in allowed_json_files:
                     target = _resolve_json_path(name)
+                    source = f"name={name}"
                 elif isinstance(path_val, str):
-                    base = Path.cwd()
-                    # Normalize path but restrict to allowed filenames
+                    # Normalize path but restrict to allowed filenames, then resolve like reads
                     candidate = Path(path_val)
                     filename = candidate.name
                     if filename not in allowed_json_files:
                         raise ValueError("filename not allowed")
-                    target = base / filename
+                    target = _resolve_json_path(filename)
+                    source = f"path={path_val} -> filename={filename}"
                 else:
                     raise ValueError("invalid target file")
-                # Basic validation to ensure valid JSON
-                import json as _json
 
-                _ = _json.loads(content or "{}")
+                log.debug(
+                    f"Saving JSON config ({source}), resolved target: {target} (bytes={len(content.encode('utf-8'))})"
+                )
+
+                _ = json.loads(content or "{}")
                 target.write_text(content or "{}", encoding="utf-8")
+                log.debug(f"Saved JSON config to {target}")
                 return {"status": "ok"}
             except Exception as e:  # noqa: BLE001
                 raise HTTPException(status_code=400, detail=f"Save failed: {e}") from e
@@ -348,12 +355,6 @@ class OpenEdisonProxy:
         log.info("🚀 Starting both FastAPI and FastMCP servers...")
         _ = await asyncio.gather(*servers_to_run)
 
-    async def shutdown(self) -> None:
-        """Shutdown the proxy server and all MCP servers"""
-        log.info("🛑 Shutting down Open Edison proxy server")
-        await self.mcp_manager.shutdown()
-        log.info("✅ Open Edison proxy server shutdown complete")
-
     def _register_routes(self, app: FastAPI) -> None:
         """Register all routes for the FastAPI app"""
         # Register routes with their decorators
@@ -362,13 +363,6 @@ class OpenEdisonProxy:
             "/mcp/status",
             self.mcp_status,
             methods=["GET"],
-            dependencies=[Depends(self.verify_api_key)],
-        )
-        app.add_api_route(
-            "/mcp/{server_name}/start",
-            self.start_mcp_server,
-            methods=["POST"],
-            dependencies=[Depends(self.verify_api_key)],
         )
         app.add_api_route(
             "/mcp/validate",
@@ -376,18 +370,6 @@ class OpenEdisonProxy:
             methods=["POST"],
             # Intentionally no auth required for validation for now
         )
-        app.add_api_route(
-            "/mcp/{server_name}/stop",
-            self.stop_mcp_server,
-            methods=["POST"],
-            dependencies=[Depends(self.verify_api_key)],
-        )
-        app.add_api_route(
-            "/mcp/call",
-            self.proxy_mcp_call,
-            methods=["POST"],
-            dependencies=[Depends(self.verify_api_key)],
-        )
         app.add_api_route(
             "/mcp/mounted",
             self.get_mounted_servers,
@@ -395,14 +377,8 @@ class OpenEdisonProxy:
             dependencies=[Depends(self.verify_api_key)],
         )
         app.add_api_route(
-            "/mcp/{server_name}/mount",
-            self.mount_server,
-            methods=["POST"],
-            dependencies=[Depends(self.verify_api_key)],
-        )
-        app.add_api_route(
-            "/mcp/{server_name}/unmount",
-            self.unmount_server,
+            "/mcp/reinitialize",
+            self.reinitialize_mcp_servers,
             methods=["POST"],
             dependencies=[Depends(self.verify_api_key)],
         )
@@ -412,6 +388,12 @@ class OpenEdisonProxy:
             self.get_sessions,
             methods=["GET"],
         )
+        # Cache invalidation endpoint (no auth required - allowed to fail)
+        app.add_api_route(
+            "/api/clear-caches",
+            self.clear_caches,
+            methods=["POST"],
+        )
 
     async def verify_api_key(
         self, credentials: HTTPAuthorizationCredentials = _auth_dependency
@@ -426,6 +408,18 @@ class OpenEdisonProxy:
             raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid API key")
         return credentials.credentials
 
+    async def mcp_status(self) -> dict[str, list[dict[str, Any]]]:
+        """Get status of configured MCP servers (auth required)."""
+        return {
+            "servers": [
+                {
+                    "name": server.name,
+                    "enabled": server.enabled,
+                }
+                for server in config.mcp_servers
+            ]
+        }
+
     def _handle_server_operation_error(
         self, operation: str, server_name: str, error: Exception
     ) -> HTTPException:
@@ -451,63 +445,6 @@ class OpenEdisonProxy:
         """Health check endpoint"""
         return {"status": "healthy", "version": "0.1.0", "mcp_servers": len(config.mcp_servers)}
 
-    async def mcp_status(self) -> dict[str, list[dict[str, str | bool]]]:
-        """Get status of configured MCP servers"""
-        return {
-            "servers": [
-                {
-                    "name": server.name,
-                    "enabled": server.enabled,
-                    "running": await self.mcp_manager.is_server_running(server.name),
-                }
-                for server in config.mcp_servers
-            ]
-        }
-
-    async def start_mcp_server(self, server_name: str) -> dict[str, str]:
-        """Start a specific MCP server"""
-        try:
-            _ = await self.mcp_manager.start_server(server_name)
-            return {"message": f"Server {server_name} started successfully"}
-        except Exception as e:
-            raise self._handle_server_operation_error("start", server_name, e) from e
-
-    async def stop_mcp_server(self, server_name: str) -> dict[str, str]:
-        """Stop a specific MCP server"""
-        try:
-            await self.mcp_manager.stop_server(server_name)
-            return {"message": f"Server {server_name} stopped successfully"}
-        except Exception as e:
-            raise self._handle_server_operation_error("stop", server_name, e) from e
-
-    async def proxy_mcp_call(self, request: dict[str, Any]) -> dict[str, Any]:
-        """
-        Proxy MCP calls to mounted servers.
-
-        This now routes requests through the mounted FastMCP servers.
-        """
-        try:
-            log.info(f"Proxying MCP request: {request.get('method', 'unknown')}")
-
-            mounted = await self.single_user_mcp.get_mounted_servers()
-            mounted_names = [server["name"] for server in mounted]
-
-            return {
-                "jsonrpc": "2.0",
-                "id": request.get("id"),
-                "result": {
-                    "message": "MCP request routed through FastMCP",
-                    "request": request,
-                    "mounted_servers": mounted_names,
-                },
-            }
-        except Exception as e:
-            log.error(f"Failed to proxy MCP call: {e}")
-            raise HTTPException(
-                status_code=500,
-                detail=f"Failed to proxy MCP call: {str(e)}",
-            ) from e
-
     async def get_mounted_servers(self) -> dict[str, Any]:
         """Get list of currently mounted MCP servers."""
         try:
@@ -520,35 +457,48 @@ class OpenEdisonProxy:
                 detail=f"Failed to get mounted servers: {str(e)}",
             ) from e
 
-    async def mount_server(self, server_name: str) -> dict[str, str]:
-        """Mount a specific MCP server."""
+    async def reinitialize_mcp_servers(self) -> dict[str, Any]:
+        """Reinitialize all MCP servers by creating a fresh instance and reloading config."""
+        old_mcp = None
         try:
-            server_config = self._find_server_config(server_name)
-            success = await self.single_user_mcp.mount_server(server_config)
-            if success:
-                return {"message": f"Server {server_name} mounted successfully"}
-            raise HTTPException(
-                status_code=500,
-                detail=f"Failed to mount server: {server_name}",
-            )
-        except HTTPException:
-            raise
-        except Exception as e:
-            raise self._handle_server_operation_error("mount", server_name, e) from e
+            log.info("🔄 Reinitializing MCP servers via API endpoint")
+
+            # Reload configuration from disk
+            log.info("Reloading configuration from disk")
+            from src.config import Config
+
+            fresh_config = Config.load()
+            log.info("✅ Configuration reloaded from disk")
+
+            # Create a completely new SingleUserMCP instance to ensure clean state
+            old_mcp = self.single_user_mcp
+            self.single_user_mcp = SingleUserMCP()
+
+            # Initialize the new instance with fresh config
+            await self.single_user_mcp.initialize(fresh_config)
+
+            # Get final status
+            final_mounted = await self.single_user_mcp.get_mounted_servers()
+
+            result = {
+                "status": "success",
+                "message": "MCP servers reinitialized successfully",
+                "final_mounted_servers": [server["name"] for server in final_mounted],
+                "total_final_mounted": len(final_mounted),
+            }
+
+            log.info("✅ MCP servers reinitialized successfully via API")
+            return result
 
-    async def unmount_server(self, server_name: str) -> dict[str, str]:
-        """Unmount a specific MCP server."""
-        try:
-            if server_name == "test-echo":
-                log.info("Special handling for test-echo server unmount")
-                _ = await self.single_user_mcp.unmount_server(server_name)
-                return {"message": f"Server {server_name} unmounted successfully"}
-            _ = await self.single_user_mcp.unmount_server(server_name)
-            return {"message": f"Server {server_name} unmounted successfully"}
-        except HTTPException:
-            raise
         except Exception as e:
-            raise self._handle_server_operation_error("unmount", server_name, e) from e
+            log.error(f"❌ Failed to reinitialize MCP servers: {e}")
+            # Restore the old instance on failure
+            if old_mcp is not None:
+                self.single_user_mcp = old_mcp
+            raise HTTPException(
+                status_code=500,
+                detail=f"Failed to reinitialize MCP servers: {str(e)}",
+            ) from e
 
     async def get_sessions(self) -> dict[str, Any]:
         """Return recent MCP session summaries from local SQLite.
@@ -599,6 +549,21 @@ class OpenEdisonProxy:
             log.error(f"Failed to fetch sessions: {e}")
             raise HTTPException(status_code=500, detail="Failed to fetch sessions") from e
 
+    async def clear_caches(self) -> dict[str, str]:
+        """Clear all permission caches to force reload from configuration files."""
+        try:
+            from src.middleware.data_access_tracker import clear_all_permissions_caches
+
+            log.info("🔄 Clearing all permission caches via API endpoint")
+            clear_all_permissions_caches()
+            log.info("✅ All permission caches cleared successfully")
+
+            return {"status": "success", "message": "All permission caches cleared"}
+        except Exception as e:
+            log.error(f"❌ Failed to clear permission caches: {e}")
+            # Don't raise HTTPException - allow to fail gracefully as requested
+            return {"status": "error", "message": f"Failed to clear caches: {str(e)}"}
+
     # ---- MCP validation ----
     class _ValidateRequest(BaseModel):
         name: str | None = Field(None, description="Optional server name label")
@@ -655,9 +620,9 @@ class OpenEdisonProxy:
                     "args": body.args,
                     "has_roots": bool(body.roots),
                 },
-                "tools": [self._safe_tool(t) for t in tools],
+                "tools": [self._safe_tool(t, prefix=server_name) for t in tools],
                 "resources": [self._safe_resource(r) for r in resources],
-                "prompts": [self._safe_prompt(p) for p in prompts],
+                "prompts": [self._safe_prompt(p, prefix=server_name) for p in prompts],
             }
         except TimeoutError as te:  # noqa: PERF203
             log.error(f"MCP validation timed out: {te}\n{traceback.format_exc()}")
@@ -728,10 +693,13 @@ class OpenEdisonProxy:
         timeout = body.timeout_s if isinstance(body.timeout_s, (int | float)) else 20.0
         return await asyncio.wait_for(list_all(), timeout=timeout)
 
-    def _safe_tool(self, t: Any) -> dict[str, Any]:
+    def _safe_tool(self, t: Any, prefix: str) -> dict[str, Any]:
         name = getattr(t, "name", None)
         description = getattr(t, "description", None)
-        return {"name": str(name) if name is not None else "", "description": description}
+        return {
+            "name": prefix + "_" + str(name) if name is not None else "",
+            "description": description,
+        }
 
     def _safe_resource(self, r: Any) -> dict[str, Any]:
         uri = getattr(r, "uri", None)
@@ -742,7 +710,10 @@ class OpenEdisonProxy:
         description = getattr(r, "description", None)
         return {"uri": uri_str, "description": description}
 
-    def _safe_prompt(self, p: Any) -> dict[str, Any]:
+    def _safe_prompt(self, p: Any, prefix: str) -> dict[str, Any]:
         name = getattr(p, "name", None)
         description = getattr(p, "description", None)
-        return {"name": str(name) if name is not None else "", "description": description}
+        return {
+            "name": prefix + "_" + str(name) if name is not None else "",
+            "description": description,
+        }

src/single_user_mcp.py

@@ -7,11 +7,11 @@ Handles MCP protocol communication with running servers using a unified composit
 
 from typing import Any, TypedDict
 
+from fastmcp import Client as FastMCPClient
 from fastmcp import FastMCP
 from loguru import logger as log
 
 from src.config import MCPServerConfig, config
-from src.mcp_manager import MCPManager
 from src.middleware.session_tracking import (
     SessionTrackingMiddleware,
     get_current_session_data_tracker,
@@ -42,9 +42,8 @@ class SingleUserMCP(FastMCP[Any]):
     All enabled MCP servers are mounted through a single FastMCP composite proxy.
     """
 
-    def __init__(self, mcp_manager: MCPManager):
+    def __init__(self):
         super().__init__(name="open-edison-single-user")
-        self.mcp_manager: MCPManager = mcp_manager
         self.mounted_servers: dict[str, MountedServerInfo] = {}
         self.composite_proxy: FastMCP[Any] | None = None
 
@@ -109,119 +108,33 @@ class SingleUserMCP(FastMCP[Any]):
         Returns:
             True if composite proxy was created successfully, False otherwise
         """
-        try:
-            # Filter out test servers for composite proxy
-            real_servers = [s for s in enabled_servers if s.command != "echo"]
-
-            if not real_servers:
-                log.info("No real servers to mount in composite proxy")
-                return True
-
-            # Start all required server processes
-            for server_config in real_servers:
-                if not await self.mcp_manager.is_server_running(server_config.name):
-                    log.info(f"Starting server process: {server_config.name}")
-                    _ = await self.mcp_manager.start_server(server_config.name)
-
-            # Convert to FastMCP config format
-            fastmcp_config = self._convert_to_fastmcp_config(real_servers)
-
-            log.info(
-                f"Creating composite proxy for servers: {list(fastmcp_config['mcpServers'].keys())}"
-            )
-
-            # Create the composite proxy using FastMCP's multi-server support
-            self.composite_proxy = FastMCP.as_proxy(
-                backend=fastmcp_config, name="open-edison-composite-proxy"
-            )
-
-            # Import the composite proxy into this main server
-            # Tools and resources will be automatically namespaced by server name
-            await self.import_server(self.composite_proxy)
-
-            # Track mounted servers for status reporting
-            for server_config in real_servers:
-                self.mounted_servers[server_config.name] = MountedServerInfo(
-                    config=server_config, proxy=self.composite_proxy
-                )
-
-            log.info(f"✅ Created composite proxy with {len(real_servers)} servers")
+        if not enabled_servers:
+            log.info("No real servers to mount in composite proxy")
             return True
 
-        except Exception as e:
-            log.error(f"❌ Failed to create composite proxy: {e}")
-            return False
-
-    async def mount_server(self, server_config: MCPServerConfig) -> bool:
-        """
-        Mount a single MCP server by rebuilding the composite proxy.
-
-        Args:
-            server_config: Configuration for the server to mount
-
-        Returns:
-            True if mounting was successful, False otherwise
-        """
-        try:
-            # Check if server is already mounted
-            if server_config.name in self.mounted_servers:
-                log.info(f"Server {server_config.name} is already mounted")
-                return True
-
-            # Handle test servers separately
-            if server_config.command == "echo":
-                return await self._mount_test_server(server_config)
-
-            # For real servers, we need to rebuild the composite proxy
-            log.info(f"Mounting server {server_config.name} via composite proxy rebuild")
-
-            # Get currently mounted servers and add the new one
-            current_configs = [mounted["config"] for mounted in self.mounted_servers.values()]
-
-            # Add the new server if not already there
-            if server_config not in current_configs:
-                current_configs.append(server_config)
-
-            # Rebuild composite proxy with new server list
-            return await self.create_composite_proxy(current_configs)
-
-        except Exception as e:
-            log.error(f"❌ Failed to mount server {server_config.name}: {e}")
-            return False
-
-    async def unmount_server(self, server_name: str) -> bool:
-        """
-        Unmount an MCP server and stop its subprocess.
-
-        NOTE: For servers in the composite proxy, this will require rebuilding
-        the entire composite proxy without the specified server.
-        """
-        try:
-            # Check if this is a test server (individually mounted)
-            if server_name in self.mounted_servers:
-                mounted = self.mounted_servers[server_name]
-                if mounted["config"].command == "echo":
-                    # Test server - handle individually
-                    await self._cleanup_mounted_server(server_name)
-                    return True
-
-                # Real server in composite proxy - needs full rebuild
-                log.warning(f"Unmounting {server_name} requires rebuilding composite proxy")
-                return await self._rebuild_composite_proxy_without(server_name)
-
-            log.warning(f"Server {server_name} not found in mounted servers")
-            return False
+        # Import the composite proxy into this main server
+        # Tools and resources will be automatically namespaced by server name
+        for server_config in enabled_servers:
+            server_name = server_config.name
+            # Skip if this server would produce an empty config (e.g., misconfigured)
+            fastmcp_config = self._convert_to_fastmcp_config([server_config])
+            if not fastmcp_config.get("mcpServers"):
+                log.warning(f"Skipping server '{server_name}' due to empty MCP config")
+                continue
+            proxy = FastMCP.as_proxy(FastMCPClient(fastmcp_config))
+            self.mount(proxy, prefix=server_name)
+            self.mounted_servers[server_name] = MountedServerInfo(config=server_config, proxy=proxy)
 
-        except Exception as e:
-            log.error(f"❌ Failed to unmount MCP server {server_name}: {e}")
-            return False
+        log.info(
+            f"✅ Created composite proxy with {len(enabled_servers)} servers ({self.mounted_servers.keys()})"
+        )
+        return True
 
     async def _rebuild_composite_proxy_without(self, excluded_server: str) -> bool:
         """Rebuild the composite proxy without the specified server."""
         try:
             # Remove from mounted servers
             await self._cleanup_mounted_server(excluded_server)
-            await self._stop_server_process(excluded_server)
 
             # Get remaining servers that should be in composite proxy
             remaining_configs = [
@@ -245,15 +158,11 @@ class SingleUserMCP(FastMCP[Any]):
 
     async def _cleanup_mounted_server(self, server_name: str) -> None:
         """Clean up mounted server resources."""
+        # TODO not sure this is possible for the self object? i.e. there is no self.unmount
         if server_name in self.mounted_servers:
             del self.mounted_servers[server_name]
             log.info(f"✅ Unmounted MCP server: {server_name}")
 
-    async def _stop_server_process(self, server_name: str) -> None:
-        """Stop the server subprocess if it's not a test server."""
-        if server_name != "test-echo":
-            await self.mcp_manager.stop_server(server_name)
-
     async def get_mounted_servers(self) -> list[ServerStatusInfo]:
         """Get list of currently mounted servers."""
         return [
@@ -287,6 +196,80 @@ class SingleUserMCP(FastMCP[Any]):
 
         log.info("✅ Single User MCP server initialized with composite proxy")
 
+    async def reinitialize(self, test_config: Any | None = None) -> dict[str, Any]:
+        """
+        Reinitialize all MCP servers by cleaning up existing ones and reloading config.
+
+        This method:
+        1. Cleans up all mounted servers and MCP proxies
+        2. Reloads the configuration
+        3. Reinitializes all enabled servers
+
+        Args:
+            test_config: Optional test configuration to use instead of reloading from disk
+
+        Returns:
+            Dictionary with reinitialization status and details
+        """
+        log.info("🔄 Reinitializing all MCP servers")
+
+        try:
+            # Step 1: Clean up existing mounted servers and proxies
+            log.info("Cleaning up existing mounted servers and proxies")
+
+            # Clean up composite proxy if it exists
+            if self.composite_proxy is not None:
+                log.info("Cleaning up composite proxy")
+                self.composite_proxy = None
+
+            # Clean up all mounted servers
+            mounted_server_names = list(self.mounted_servers.keys())
+            for server_name in mounted_server_names:
+                await self._cleanup_mounted_server(server_name)
+
+            # Clear the mounted servers dictionary completely
+            self.mounted_servers.clear()
+
+            log.info(f"✅ Cleaned up {len(mounted_server_names)} mounted servers")
+
+            # Step 2: Reload configuration if not using test config
+            config_to_use = test_config
+            if test_config is None:
+                log.info("Reloading configuration from disk")
+                # Import here to avoid circular imports
+                from src.config import Config
+
+                config_to_use = Config.load()
+                log.info("✅ Configuration reloaded from disk")
+
+            # Step 3: Reinitialize all servers
+            log.info("Reinitializing servers with fresh configuration")
+            await self.initialize(config_to_use)
+
+            # Step 4: Get final status
+            final_mounted = await self.get_mounted_servers()
+
+            result = {
+                "status": "success",
+                "message": "MCP servers reinitialized successfully",
+                "cleaned_up_servers": mounted_server_names,
+                "final_mounted_servers": [server["name"] for server in final_mounted],
+                "total_final_mounted": len(final_mounted),
+            }
+
+            log.info(
+                f"✅ Reinitialization complete. Final mounted servers: {result['final_mounted_servers']}"
+            )
+            return result
+
+        except Exception as e:
+            log.error(f"❌ Failed to reinitialize MCP servers: {e}")
+            return {
+                "status": "error",
+                "message": f"Failed to reinitialize MCP servers: {str(e)}",
+                "error": str(e),
+            }
+
     def _calculate_risk_level(self, trifecta: dict[str, bool]) -> str:
         """
         Calculate a human-readable risk level based on trifecta flags.