codegraphcontext 0.5.3__py3-none-any.whl → 0.5.4__py3-none-any.whl

codegraphcontext/api/app.py

@@ -1,10 +1,10 @@
 # src/codegraphcontext/api/app.py
 import os
-from fastapi import FastAPI
+from fastapi import Depends, FastAPI
 from fastapi.responses import HTMLResponse
 from fastapi.middleware.cors import CORSMiddleware
 from .router import router
-from .auth import log_auth_status
+from .auth import log_auth_status, require_api_key
 from .mcp_sse import handle_sse, handle_messages
 
 def create_app() -> FastAPI:
@@ -37,9 +37,23 @@ def create_app() -> FastAPI:
         """Liveness probe for load balancers and k8s."""
         return {"status": "ok"}
 
-    # MCP-over-SSE Endpoints
-    app.add_api_route("/api/v1/mcp/sse", handle_sse, methods=["GET"])
-    app.add_api_route("/api/v1/mcp/messages", handle_messages, methods=["POST"])
+    # MCP-over-SSE Endpoints. These dispatch to the same tools as the REST
+    # router (execute_cypher_query, add_code_to_graph, delete_repository), so
+    # they need the same API-key dependency the router applies — without it,
+    # setting CGC_API_KEY left the SSE transport as an unauthenticated path to
+    # every tool.
+    app.add_api_route(
+        "/api/v1/mcp/sse",
+        handle_sse,
+        methods=["GET"],
+        dependencies=[Depends(require_api_key)],
+    )
+    app.add_api_route(
+        "/api/v1/mcp/messages",
+        handle_messages,
+        methods=["POST"],
+        dependencies=[Depends(require_api_key)],
+    )
 
     @app.get("/", response_class=HTMLResponse)
     async def root():

codegraphcontext/api/mcp_sse.py

@@ -48,11 +48,41 @@ async def handle_call_tool(name: str, arguments: dict | None) -> list[TextConten
 # Create the SSE transport.
 sse = SseServerTransport("/api/v1/mcp/messages")
 
+
+class _AlreadySentResponse(Response):
+    """Placeholder for a response the MCP transport wrote itself.
+
+    Both handlers below hand the raw ASGI ``send`` to the SDK, which emits the
+    complete response. FastAPI still does ``await endpoint(request)`` followed
+    by ``await response(...)``, so returning ``None`` raises ``TypeError:
+    'NoneType' object is not callable`` and returning a real ``Response`` starts
+    a second response on a finished ASGI cycle. This satisfies FastAPI while
+    putting nothing on the wire.
+    """
+
+    async def __call__(self, scope, receive, send) -> None:
+        return
+
+
+class _SendTracker:
+    """ASGI ``send`` wrapper that records whether a response was started."""
+
+    def __init__(self, send):
+        self._send = send
+        self.response_started = False
+
+    async def __call__(self, message) -> None:
+        if message.get("type") == "http.response.start":
+            self.response_started = True
+        await self._send(message)
+
+
 async def handle_sse(request: Request):
     """Entry point for the SSE connection."""
     logger.info("SSE client connected")
+    sender = _SendTracker(request._send)
     try:
-        async with sse.connect_sse(request.scope, request.receive, request._send) as (read_stream, write_stream):
+        async with sse.connect_sse(request.scope, request.receive, sender) as (read_stream, write_stream):
             await mcp_server.run(
                 read_stream,
                 write_stream,
@@ -70,6 +100,10 @@ async def handle_sse(request: Request):
         logger.debug("SSE connection closed: %s", type(exc).__name__)
     finally:
         logger.info("SSE client disconnected — handler exited, resources freed")
+    if sender.response_started:
+        return _AlreadySentResponse()
+    # connect_sse bailed out before writing anything (e.g. rejected origin).
+    return Response(status_code=500, content="SSE connection could not be established")
 
 
 async def handle_messages(request: Request):
@@ -99,7 +133,20 @@ async def handle_messages(request: Request):
             media_type="application/json"
         )
 
+    # `handle_post_message` builds its own Request and awaits `.body()` again.
+    # Starlette caches a body on the Request instance, not in the scope, so
+    # handing it the raw `receive` would make it wait for a body that has
+    # already been drained above — the POST hangs until the client gives up and
+    # the message never reaches the session. Replay the buffered bytes instead.
+    async def replay_receive() -> dict:
+        return {"type": "http.request", "body": raw_body, "more_body": False}
+
+    sender = _SendTracker(request._send)
     try:
-        await sse.handle_post_message(request.scope, request.receive, request._send)
+        await sse.handle_post_message(request.scope, replay_receive, sender)
     except Exception as exc:
         logger.debug("Message handler closed: %s", type(exc).__name__)
+
+    if sender.response_started:
+        return _AlreadySentResponse()
+    return Response(status_code=202, content="Accepted")

codegraphcontext/cli/cli_helpers.py

@@ -239,65 +239,78 @@ def _initialize_services(
     return db_manager, graph_builder, code_finder, ctx
 
 
-async def _run_index_with_progress(graph_builder: GraphBuilder, path_obj: Path, is_dependency: bool = False, cgcignore_path: str = None):
+async def _run_index_with_progress(graph_builder: GraphBuilder, path_obj: Path, is_dependency: bool = False, cgcignore_path: str = None, disable_progress: bool = False):
     """Internal helper to run indexing with a Live progress bar."""
     job_id = graph_builder.job_manager.create_job(str(path_obj), is_dependency=is_dependency)
     
-    # Create the progress bar
-    with Progress(
-        SpinnerColumn(),
-        TextColumn("[progress.description]{task.description}"),
-        BarColumn(),
-        TaskProgressColumn(),
-        MofNCompleteColumn(),
-        TimeRemainingColumn(),
-        TextColumn("[dim]{task.fields[filename]}"),
-        console=console,
-        transient=True,
-    ) as progress:
-        
-        task_id = progress.add_task(
-            "Indexing...", 
-            total=None,  # Will be updated once file discovery is done
-            filename=""
-        )
+    disable_progress = (
+        disable_progress
+        or not console.is_terminal
+        or os.environ.get("CI", "").lower() == "true"
+    )
 
-        indexing_task = asyncio.create_task(
-            graph_builder.build_graph_from_path_async(path_obj, is_dependency=is_dependency, job_id=job_id, cgcignore_path=cgcignore_path)
-        )
+    if not disable_progress:
+        os.environ["CGC_ACTIVE_PROGRESS_BAR"] = "1"
 
-        from ..core.jobs import JobStatus
+    try:
+        # Create the progress bar
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TaskProgressColumn(),
+            MofNCompleteColumn(),
+            TimeRemainingColumn(),
+            TextColumn("[dim]{task.fields[filename]}"),
+            console=console,
+            transient=True,
+            disable=disable_progress,
+        ) as progress:
         
-        # Poll for updates
-        while not indexing_task.done():
-            job = graph_builder.job_manager.get_job(job_id)
-            if job:
-                if job.total_files > 0:
-                    progress.update(task_id, total=job.total_files, completed=job.processed_files)
-                
-                # Prefer post-processing status over the last parsed file path
-                current_file = job.status_message or job.current_file or ""
-                if len(current_file) > 40:
-                    current_file = "..." + current_file[-37:]
-                progress.update(task_id, filename=current_file)
+            task_id = progress.add_task(
+                "Indexing...", 
+                total=None,  # Will be updated once file discovery is done
+                filename=""
+            )
 
-                if job.status in [JobStatus.COMPLETED, JobStatus.FAILED, JobStatus.CANCELLED]:
-                    break
+            indexing_task = asyncio.create_task(
+                graph_builder.build_graph_from_path_async(path_obj, is_dependency=is_dependency, job_id=job_id, cgcignore_path=cgcignore_path)
+            )
+
+            from ..core.jobs import JobStatus
             
-            await asyncio.sleep(0.1)
+            # Poll for updates
+            while not indexing_task.done():
+                job = graph_builder.job_manager.get_job(job_id)
+                if job:
+                    if job.total_files > 0:
+                        progress.update(task_id, total=job.total_files, completed=job.processed_files)
+                    
+                    # Prefer post-processing status over the last parsed file path
+                    current_file = job.status_message or job.current_file or ""
+                    if len(current_file) > 40:
+                        current_file = "..." + current_file[-37:]
+                    progress.update(task_id, filename=current_file)
+
+                    if job.status in [JobStatus.COMPLETED, JobStatus.FAILED, JobStatus.CANCELLED]:
+                        break
+                
+                await asyncio.sleep(0.1)
 
-        # Wait for actual completion and handle final state
-        try:
-            await indexing_task
-            job = graph_builder.job_manager.get_job(job_id)
-            if job and job.status == JobStatus.FAILED:
-                error_msg = job.errors[0] if job.errors else "Unknown error"
-                raise RuntimeError(error_msg)
-        except Exception as e:
-            raise e
+            # Wait for actual completion and handle final state
+            try:
+                await indexing_task
+                job = graph_builder.job_manager.get_job(job_id)
+                if job and job.status == JobStatus.FAILED:
+                    error_msg = job.errors[0] if job.errors else "Unknown error"
+                    raise RuntimeError(error_msg)
+            except Exception as e:
+                raise e
+    finally:
+        os.environ.pop("CGC_ACTIVE_PROGRESS_BAR", None)
 
 
-def index_helper(path: str, context: Optional[str] = None):
+def index_helper(path: str, context: Optional[str] = None, no_progress: bool = False):
     """Synchronously indexes a repository in a given context."""
     time_start = time.time()
     path_obj = Path(path).resolve()
@@ -334,10 +347,16 @@ def index_helper(path: str, context: Optional[str] = None):
                 file_count = record["file_count"] if record else 0
                 
                 if file_count > 0:
-                    console.print(f"[yellow]Repository '{path}' is already indexed with {file_count} files. Skipping.[/yellow]")
-                    console.print("[dim]💡 Tip: Use 'cgc index --force' to re-index[/dim]")
-                    db_manager.close_driver()
-                    return
+                    expected = graph_builder.estimate_processing_time(path_obj) if path_obj.is_dir() else None
+                    expected_file_count = expected[0] if expected else None
+                    if expected_file_count is None or file_count >= expected_file_count:
+                        console.print(f"[yellow]Repository '{path}' is already indexed with {file_count} files. Skipping.[/yellow]")
+                        console.print("[dim]💡 Tip: Use 'cgc index --force' to re-index[/dim]")
+                        db_manager.close_driver()
+                        return
+                    console.print(
+                        f"[yellow]Repository '{path}' has only {file_count} of {expected_file_count} files indexed. Continuing.[/yellow]"
+                    )
                 else:
                     console.print(f"[yellow]Repository '{path}' exists but has no files (likely interrupted). Re-indexing...[/yellow]")
         except Exception as e:
@@ -351,7 +370,7 @@ def index_helper(path: str, context: Optional[str] = None):
     console.print(f"Starting indexing for: {path_obj}")
 
     try:
-        asyncio.run(_run_index_with_progress(graph_builder, path_obj, is_dependency=False, cgcignore_path=ctx.cgcignore_path))
+        asyncio.run(_run_index_with_progress(graph_builder, path_obj, is_dependency=False, cgcignore_path=ctx.cgcignore_path, disable_progress=no_progress))
         time_end = time.time()
         elapsed = time_end - time_start
         _print_call_resolution_diagnostics(graph_builder)
@@ -608,34 +627,56 @@ def _render_offline_visualization(
     def _ident(value) -> Optional[str]:
         return None if value is None else str(value)
 
-    # Neo4j/Falkor return driver objects carrying .labels / .type; Kùzu and
-    # Ladybug return plain dicts carrying _label plus _src/_dst. Check the
-    # driver attributes first — a driver object may also be dict-like.
+    # Kùzu spells the internal record keys in lowercase (_label/_src/_dst/_id);
+    # Ladybug returns the same fields uppercased (_LABEL/_SRC/_DST/_ID). Look
+    # up both spellings so either backend reaches the offline renderer (#1458).
+    def _meta(d: dict, key: str, default=None):
+        if key in d:
+            return d[key]
+        return d.get(key.upper(), default)
+
+    def _has_meta(d: dict, key: str) -> bool:
+        return key in d or key.upper() in d
+
+    # Neo4j returns driver objects carrying .labels / .type that support
+    # dict()/Mapping access. FalkorDB's own driver objects also carry
+    # .labels on nodes, but are NOT dict-convertible — their properties live
+    # in a plain `.properties` dict, and its Edge exposes `.relation` /
+    # `.src_node` / `.dest_node` instead of `.type` / `.start_node` /
+    # `.end_node`. Kùzu and Ladybug return plain dicts carrying _label plus
+    # _src/_dst. Check the driver attributes first — a driver object may
+    # also be dict-like.
     def _is_relationship(value) -> bool:
         if hasattr(value, "labels"):
             return False
         if hasattr(value, "type"):
             return True
-        return isinstance(value, dict) and "_src" in value and "_dst" in value
+        if hasattr(value, "relation") and hasattr(value, "src_node"):
+            return True
+        return isinstance(value, dict) and _has_meta(value, "_src") and _has_meta(value, "_dst")
 
     def _is_node(value) -> bool:
         if hasattr(value, "labels"):
             return True
         if hasattr(value, "type"):
             return False
+        if hasattr(value, "relation") and hasattr(value, "src_node"):
+            return False
         # Kùzu relationships also carry _label, so _src/_dst is what
         # distinguishes them from nodes.
-        return isinstance(value, dict) and "_label" in value and "_src" not in value
+        return isinstance(value, dict) and _has_meta(value, "_label") and not _has_meta(value, "_src")
 
     def _node_payload(value) -> Dict[str, Any]:
         if hasattr(value, "labels"):
-            props = dict(value)
+            # FalkorDB's Node keeps properties in `.properties` and is not
+            # itself iterable; Neo4j's Node supports dict() via Mapping.
+            props = dict(value.properties) if hasattr(value, "properties") else dict(value)
             labels = list(getattr(value, "labels", []) or [])
             label = labels[0] if labels else "Node"
             node_id = getattr(value, "element_id", None) or getattr(value, "id", None)
         else:
-            props, label = dict(value), value.get("_label", "Node")
-            node_id = value.get("_id")
+            props, label = dict(value), _meta(value, "_label", "Node")
+            node_id = _meta(value, "_id")
         if node_id is None:
             node_id = props.get("path") or props.get("name")
         return {
@@ -646,20 +687,33 @@ def _render_offline_visualization(
             "line_number": props.get("line_number"),
         }
 
+    def _node_ref_id(ref) -> Any:
+        # Neo4j's start_node/end_node are full Node objects; FalkorDB's
+        # src_node/dest_node are already the bare node id (an int).
+        if isinstance(ref, (int, str)):
+            return ref
+        return getattr(ref, "element_id", None) or getattr(ref, "id", None)
+
     def _edge_payload(value) -> Optional[Dict[str, Any]]:
+        # Neo4j: .start_node/.end_node/.type. FalkorDB: .src_node/.dest_node/
+        # .relation.
         start = getattr(value, "start_node", None)
+        if start is None:
+            start = getattr(value, "src_node", None)
         end = getattr(value, "end_node", None)
+        if end is None:
+            end = getattr(value, "dest_node", None)
         if start is not None and end is not None:
             return {
-                "source": _ident(getattr(start, "element_id", None) or getattr(start, "id", None)),
-                "target": _ident(getattr(end, "element_id", None) or getattr(end, "id", None)),
-                "type": getattr(value, "type", "RELATED"),
+                "source": _ident(_node_ref_id(start)),
+                "target": _ident(_node_ref_id(end)),
+                "type": getattr(value, "type", None) or getattr(value, "relation", "RELATED"),
             }
         if isinstance(value, dict):
             return {
-                "source": _ident(value.get("_src")),
-                "target": _ident(value.get("_dst")),
-                "type": value.get("_label", "RELATED"),
+                "source": _ident(_meta(value, "_src")),
+                "target": _ident(_meta(value, "_dst")),
+                "type": _meta(value, "_label", "RELATED"),
             }
         return None
 
@@ -803,7 +857,7 @@ def visualize_helper(
         db_manager.close_driver()
 
 
-def reindex_helper(path: str, context: Optional[str] = None):
+def reindex_helper(path: str, context: Optional[str] = None, no_progress: bool = False):
     """Force re-index by deleting and rebuilding the repository."""
     time_start = time.time()
     path_obj = Path(path).resolve()
@@ -836,7 +890,7 @@ def reindex_helper(path: str, context: Optional[str] = None):
     console.print(f"[cyan]Re-indexing: {path_obj}[/cyan]")
     
     try:
-        asyncio.run(_run_index_with_progress(graph_builder, path_obj, is_dependency=False, cgcignore_path=ctx.cgcignore_path))
+        asyncio.run(_run_index_with_progress(graph_builder, path_obj, is_dependency=False, cgcignore_path=ctx.cgcignore_path, disable_progress=no_progress))
         time_end = time.time()
         elapsed = time_end - time_start
         _print_call_resolution_diagnostics(graph_builder)

codegraphcontext/cli/config_manager.py

@@ -87,6 +87,8 @@ DEFAULT_CONFIG = {
     "DEFAULT_DATABASE": "falkordb",
     "FALKORDB_PATH": str(CONFIG_DIR / "global" / "db" / "falkordb"),
     "FALKORDB_SOCKET_PATH": str(CONFIG_DIR / "global" / "db" / "falkordb.sock"),
+    # Empty selects a deterministic port derived from each embedded DB socket.
+    "FALKORDB_PORT": "",
     "LADYBUGDB_PATH": str(CONFIG_DIR / "global" / "db" / "ladybugdb"),
     "KUZUDB_PATH": str(CONFIG_DIR / "global" / "db" / "kuzudb"),
     "INDEX_VARIABLES": "true",
@@ -142,6 +144,7 @@ CONFIG_DESCRIPTIONS = {
     "DEFAULT_DATABASE": "Default database backend (neo4j|falkordb|falkordb-remote|kuzudb|nornic|ladybugdb)",
     "FALKORDB_PATH": "Path to FalkorDB database file",
     "FALKORDB_SOCKET_PATH": "Path to FalkorDB Unix socket",
+    "FALKORDB_PORT": "Optional FalkorDB port override (empty = per-database port)",
     "LADYBUGDB_PATH": "Path to LadybugDB database directory",
     "KUZUDB_PATH": "Path to KuzuDB database directory",
     "INDEX_VARIABLES": "Index variable nodes in the graph (lighter graph if false)",

codegraphcontext/cli/main.py

@@ -1440,6 +1440,7 @@ def index(
     force: bool = typer.Option(False, "--force", "-f", help="Force re-index (delete existing and rebuild)"),
     context: Optional[str] = typer.Option(None, "--context", "-c", help="Specific context to use (overrides mode/default)"),
     summarize: bool = typer.Option(False, "--summarize", "-s", help="Show a summary of the indexed codebase after indexing"),
+    no_progress: bool = typer.Option(False, "--no-progress", help="Disable live progress rendering during indexing."),
 ):
     """
     Indexes a directory or file by adding it to the code graph.
@@ -1455,9 +1456,9 @@ def index(
     try:
         if force:
             console.print("[yellow]Force re-indexing (--force flag detected)[/yellow]")
-            reindex_helper(path, context)
+            reindex_helper(path, context, no_progress=no_progress)
         else:
-            index_helper(path, context)
+            index_helper(path, context, no_progress=no_progress)
     except typer.Exit:
         # typer.Exit subclasses RuntimeError and str() is empty, so the handler
         # below caught it, printed nothing, and returned 0 — every helper that
@@ -3050,12 +3051,13 @@ def index_abbrev(
     path: Optional[str] = typer.Argument(None, help="Path to index"),
     force: bool = typer.Option(False, "--force", "-f", help="Force re-index (delete existing and rebuild)"),
     summarize: bool = typer.Option(False, "--summarize", "-s", help="Display a codebase summary after indexing"),
-    context: Optional[str] = typer.Option(None, "--context", "-c", help="Specific context to use")
+    context: Optional[str] = typer.Option(None, "--context", "-c", help="Specific context to use"),
+    no_progress: bool = typer.Option(False, "--no-progress", help="Disable live progress rendering during indexing.")
 ):
     """Shortcut for 'cgc index'"""
     # `summarize` must be passed explicitly: omitted, it keeps its OptionInfo
     # sentinel, which is truthy — so `cgc i` always printed the summary.
-    index(path, force=force, summarize=summarize, context=context)
+    index(path, force=force, summarize=summarize, context=context, no_progress=no_progress)
 
 @app.command("ls", rich_help_panel="Shortcuts")
 def list_abbrev(
@@ -3084,7 +3086,10 @@ def visualize_abbrev(
 ):
     """Shortcut for 'cgc visualize'"""
     _load_credentials()
-    visualize_helper(repo, port, context=context)
+    # `port` must be passed by keyword: visualize_helper's second positional
+    # parameter is `host`, so the int landed there and the server tried to bind
+    # to host=8000 while ignoring --port entirely.
+    visualize_helper(repo, port=port, context=context)
 
 @app.command("w", rich_help_panel="Shortcuts")
 def watch_abbrev(

codegraphcontext/cli/setup_wizard.py

@@ -184,6 +184,11 @@ def find_jetbrains_mcp_config():
                     configs.append(mcp_file)
                     print(mcp_file)
                     return configs
+    # Always return a list: callers store this directly in the config_paths
+    # mapping and iterate it, so returning None (no JetBrains install, or no
+    # mcpServer.xml yet) raised a TypeError instead of falling through to the
+    # "configure manually" path.
+    return configs
 
 
 def convert_mcp_json_to_yaml():

codegraphcontext/core/__init__.py

@@ -20,7 +20,9 @@ from pathlib import Path
 from typing import Union, Optional
 import importlib.util
 
-# Set when FalkorDB Lite fails in-process so we skip repeated startup/retry storms.
+# Retained for compatibility with callers that inspect this module attribute.
+# FalkorDB startup failures are now tracked by FalkorDBManager per database
+# configuration, rather than disabling the backend for the whole process.
 _FALKORDB_DISABLED = False
 
 
@@ -48,15 +50,56 @@ def _fallback_db_path_for(db_path: Optional[str], target_backend: str) -> Option
     return db_path
 
 
+def _try_fallback_backends(db_path: Optional[str], candidates, *, reason: str):
+    """
+    Return the first available backend from ``candidates``, naming it in the log.
+
+    Every fallback path funnels through here so the backend a user actually ends
+    up on is always recorded. A silent switch is effectively undebuggable: the
+    only trace left is that the *requested* backend was requested, so an
+    interpreter where FalkorDB Lite cannot load looks identical to one where it
+    loaded fine, and queries run against a different (often empty) database.
+
+    Returns ``None`` when no candidate is available, so callers keep control of
+    the error they raise.
+    """
+    from codegraphcontext.utils.debug_log import warning_logger
+
+    for name in candidates:
+        if name == 'kuzudb' and _is_kuzudb_available():
+            from .database_kuzu import KuzuDBManager
+            path = _fallback_db_path_for(db_path, 'kuzudb')
+            warning_logger(
+                f"Database backend fallback: {reason} "
+                f"Now using KùzuDB at {path or 'default path'}."
+            )
+            return KuzuDBManager(db_path=path)
+        if name == 'ladybugdb' and _is_ladybugdb_available():
+            from .database_ladybug import LadybugDBManager
+            path = _fallback_db_path_for(db_path, 'ladybugdb')
+            warning_logger(
+                f"Database backend fallback: {reason} "
+                f"Now using LadybugDB at {path or 'default path'}."
+            )
+            return LadybugDBManager(db_path=path)
+        if name == 'neo4j' and _is_neo4j_configured():
+            from .database import DatabaseManager
+            warning_logger(f"Database backend fallback: {reason} Now using Neo4j Server.")
+            return DatabaseManager()
+        if name == 'nornic' and _is_nornic_configured():
+            from .database_nornic import NornicDBManager
+            warning_logger(f"Database backend fallback: {reason} Now using Nornic DB.")
+            return NornicDBManager()
+    return None
+
+
 def mark_falkordb_unavailable() -> None:
-    """Remember that FalkorDB Lite cannot run in this process."""
-    global _FALKORDB_DISABLED
-    _FALKORDB_DISABLED = True
+    """Compatibility hook; startup failures are scoped by FalkorDBManager."""
 
 
 def is_falkordb_usable() -> bool:
-    """True when FalkorDB Lite is installed and has not failed this session."""
-    return _is_falkordb_available() and not _FALKORDB_DISABLED
+    """True when FalkorDB Lite is available on this system."""
+    return _is_falkordb_available()
 
 def _is_kuzudb_available() -> bool:
     """Check if KùzuDB is installed."""
@@ -124,17 +167,13 @@ def get_database_manager(db_path: Optional[str] = None) -> Union['DatabaseManage
         db_type = db_type.lower()
         if db_type == 'kuzudb':
             if not _is_kuzudb_available():
-                info_logger("Kùzu is not installed. Falling back to an available configured backend.")
-                if _is_ladybugdb_available():
-                    from .database_ladybug import LadybugDBManager
-                    return LadybugDBManager(db_path=db_path)
-                if _is_neo4j_configured():
-                    from .database import DatabaseManager
-                    info_logger("Using Neo4j Server (fallback)")
-                    return DatabaseManager()
-                if _is_nornic_configured():
-                    from .database_nornic import NornicDBManager
-                    return NornicDBManager()
+                mgr = _try_fallback_backends(
+                    db_path,
+                    ('ladybugdb', 'neo4j', 'nornic'),
+                    reason="database was set to 'kuzudb' but Kùzu is not installed.",
+                )
+                if mgr is not None:
+                    return mgr
                 raise ValueError("Database set to 'kuzudb' but Kùzu is not installed.\nRun 'pip install kuzu'")
             from .database_kuzu import KuzuDBManager
             info_logger(f"Using KùzuDB (explicit) at {db_path or 'default path'}")
@@ -142,23 +181,13 @@ def get_database_manager(db_path: Optional[str] = None) -> Union['DatabaseManage
 
         elif db_type == 'falkordb':
             if not is_falkordb_usable():
-                if _FALKORDB_DISABLED:
-                    info_logger("FalkorDB Lite disabled for this process after earlier failure. Falling back to an available backend.")
-                else:
-                    info_logger("FalkorDB Lite is not supported or not installed. Falling back to an available backend.")
-                if _is_kuzudb_available():
-                    from .database_kuzu import KuzuDBManager
-                    return KuzuDBManager(db_path=_fallback_db_path_for(db_path, 'kuzudb'))
-                if _is_ladybugdb_available():
-                    from .database_ladybug import LadybugDBManager
-                    return LadybugDBManager(db_path=_fallback_db_path_for(db_path, 'ladybugdb'))
-                if _is_neo4j_configured():
-                    from .database import DatabaseManager
-                    info_logger("Using Neo4j Server (fallback)")
-                    return DatabaseManager()
-                if _is_nornic_configured():
-                    from .database_nornic import NornicDBManager
-                    return NornicDBManager()
+                mgr = _try_fallback_backends(
+                    db_path,
+                    ('kuzudb', 'ladybugdb', 'neo4j', 'nornic'),
+                    reason="FalkorDB Lite is not supported or not installed here.",
+                )
+                if mgr is not None:
+                    return mgr
                 raise ValueError(
                     "Database set to 'falkordb' but FalkorDB Lite is not installed or not supported on this OS.\n"
                     "Install 'falkordblite' or configure a supported alternative such as KùzuDB or Neo4j."
@@ -172,20 +201,13 @@ def get_database_manager(db_path: Optional[str] = None) -> Union['DatabaseManage
                 return mgr
             except FalkorDBUnavailableError as falkor_err:
                 mark_falkordb_unavailable()
-                info_logger(f"FalkorDB Lite not functional ({falkor_err}). Falling back to available backend.")
-                if _is_kuzudb_available():
-                    from .database_kuzu import KuzuDBManager
-                    return KuzuDBManager(db_path=_fallback_db_path_for(db_path, 'kuzudb'))
-                if _is_ladybugdb_available():
-                    from .database_ladybug import LadybugDBManager
-                    return LadybugDBManager(db_path=_fallback_db_path_for(db_path, 'ladybugdb'))
-                if _is_neo4j_configured():
-                    from .database import DatabaseManager
-                    info_logger("Using Neo4j Server (fallback)")
-                    return DatabaseManager()
-                if _is_nornic_configured():
-                    from .database_nornic import NornicDBManager
-                    return NornicDBManager()
+                mgr = _try_fallback_backends(
+                    db_path,
+                    ('kuzudb', 'ladybugdb', 'neo4j', 'nornic'),
+                    reason=f"FalkorDB Lite was requested but is not functional ({falkor_err}).",
+                )
+                if mgr is not None:
+                    return mgr
                 raise
 
         elif db_type == 'falkordb-remote':