codegraphcontext 0.2.8__py3-none-any.whl → 0.2.9__py3-none-any.whl

codegraphcontext/cli/cli_helpers.py

@@ -1,6 +1,6 @@
-# src/codegraphcontext/cli/cli_helpers.py
 import asyncio
 import json
+import uuid
 import urllib.parse
 from pathlib import Path
 import time
@@ -27,10 +27,32 @@ def _initialize_services():
 
     try:
         db_manager.get_driver()
-    except ValueError as e:
-        console.print(f"[bold red]Database Connection Error:[/bold red] {e}")
-        console.print("Please ensure your Neo4j credentials are correct and the database is running.")
-        return None, None, None
+    except Exception as e:
+        # Check if this is a FalkorDB failure that should trigger a KùzuDB fallback
+        from ..core.database_falkordb import FalkorDBUnavailableError
+        if isinstance(e, FalkorDBUnavailableError):
+            console.print(f"[yellow]⚠ FalkorDB Lite is not functional in this environment: {e}[/yellow]")
+            console.print("[cyan]Falling back to KùzuDB for a reliable experience...[/cyan]")
+            
+            # Close the broken driver/socket
+            try:
+                db_manager.close_driver()
+            except Exception:
+                pass
+            
+            # Re-initialize explicitly with KùzuDB
+            from ..core.database_kuzu import KuzuDBManager
+            db_manager = KuzuDBManager()
+            try:
+                db_manager.get_driver()
+                console.print("[green]✓[/green] Successfully switched to KùzuDB fallback")
+            except Exception as kuzu_e:
+                console.print(f"[bold red]Critical Error:[/bold red] Both FalkorDB and KùzuDB failed: {kuzu_e}")
+                return None, None, None
+        else:
+            console.print(f"[bold red]Database Connection Error:[/bold red] {e}")
+            console.print("Please ensure your database is configured correctly or run 'cgc doctor'.")
+            return None, None, None
     
     # The GraphBuilder requires an event loop, even for synchronous-style execution
     try:
@@ -263,16 +285,28 @@ def cypher_helper_visual(query: str):
 import webbrowser
 
 def visualize_helper(query: str):
-    """Generates a visualization."""
+    """"Generates a visualization."""
     services = _initialize_services()
     if not all(services):
         return
 
     db_manager, _, _ = services
     
-    # Check if FalkorDB
-    if "FalkorDB" in db_manager.__class__.__name__:
+    # Check Backend Type
+    backend = getattr(db_manager, "name", "").lower()
+    if not backend:
+        # Fallback check
+        if "FalkorDB" in db_manager.__class__.__name__:
+            backend = "falkordb"
+        elif "Kuzu" in db_manager.__class__.__name__:
+            backend = "kuzudb"
+        else:
+            backend = "neo4j"
+
+    if backend == "falkordb":
         _visualize_falkordb(db_manager)
+    elif backend == "kuzudb":
+        _visualize_kuzudb(db_manager)
     else:
         try:
             encoded_query = urllib.parse.quote(query)
@@ -391,6 +425,138 @@ def _visualize_falkordb(db_manager):
         db_manager.close_driver()
 
 
+def _visualize_kuzudb(db_manager):
+    console.print("[dim]Generating KùzuDB visualization (showing up to 500 relationships)...[/dim]")
+    try:
+        data_nodes = []
+        data_edges = []
+        
+        with db_manager.get_driver().session() as session:
+            # Fetch nodes and edges
+            # KùzuDB returns dicts for n, r, m in the result
+            q = "MATCH (n)-[r]->(m) RETURN n, r, m LIMIT 500"
+            result = session.run(q)
+            
+            seen_nodes = set()
+            
+            # Helper to extract Node ID and props
+            def process_node(node):
+                uid = None
+                lbl = 'Node'
+                props = {}
+                
+                # Handle Kuzu Node Object (processed by wrapper)
+                if hasattr(node, 'properties'):
+                    props = node.properties or {}
+                    if hasattr(node, 'labels') and node.labels:
+                        lbl = node.labels[0]
+                    if hasattr(node, 'id'):
+                        uid = str(node.id)
+                # Handle Dictionary (raw Kuzu result)
+                elif isinstance(node, dict):
+                    if '_id' in node:
+                        uid = f"{node['_id']['table']}_{node['_id']['offset']}"
+                    lbl = node.get('_label', 'Node')
+                    props = {k: v for k, v in node.items() if not k.startswith('_')}
+                
+                if not uid:
+                    uid = str(uuid.uuid4())
+                    
+                name = props.get('name', str(uid))
+                
+                if uid not in seen_nodes:
+                    seen_nodes.add(uid)
+                    color = "#97c2fc" # Default blue
+                    if "Repository" == lbl: color = "#ffb3ba"
+                    elif "File" == lbl: color = "#baffc9"
+                    elif "Class" == lbl: color = "#bae1ff"
+                    elif "Function" == lbl: color = "#ffffba"
+                    elif "Module" == lbl: color = "#ffdfba"
+                    
+                    data_nodes.append({
+                        "id": uid, 
+                        "label": name, 
+                        "group": lbl, 
+                        "title": str(props),
+                        "color": color
+                    })
+                return uid
+            
+            # Iterate results
+            for record in result:
+                # record is dict-like access to row items
+                n = record['n']
+                r = record['r']
+                m = record['m']
+                
+                nid = process_node(n)
+                mid = process_node(m)
+                
+                # Process Edge
+                e_type = 'REL'
+                if hasattr(r, 'type'):
+                    e_type = r.type
+                elif isinstance(r, dict):
+                    e_type = r.get('_label', 'REL')
+                elif hasattr(r, 'label'): # Some versions
+                     e_type = r.label
+                
+                data_edges.append({
+                    "from": nid,
+                    "to": mid,
+                    "label": e_type,
+                    "arrows": "to"
+                })
+        
+        filename = "codegraph_viz.html"
+        html_content = f"""
+<!DOCTYPE html>
+<html>
+<head>
+  <title>CodeGraphContext KùzuDB Visualization</title>
+  <script type="text/javascript" src="https://unpkg.com/vis-network/standalone/umd/vis-network.min.js"></script>
+  <style type="text/css">
+    #mynetwork {{
+      width: 100%;
+      height: 100vh;
+      border: 1px solid lightgray;
+    }}
+  </style>
+</head>
+<body>
+  <div id="mynetwork"></div>
+  <script type="text/javascript">
+    var nodes = new vis.DataSet({json.dumps(data_nodes)});
+    var edges = new vis.DataSet({json.dumps(data_edges)});
+    var container = document.getElementById('mynetwork');
+    var data = {{ nodes: nodes, edges: edges }};
+    var options = {{
+        nodes: {{ shape: 'dot', size: 16 }},
+        physics: {{ stabilization: false }},
+        layout: {{ improvedLayout: false }}
+    }};
+    var network = new vis.Network(container, data, options);
+  </script>
+</body>
+</html>
+"""
+        
+        out_path = Path(filename).resolve()
+        with open(out_path, "w") as f:
+            f.write(html_content)
+            
+        console.print(f"[green]Visualization generated at:[/green] {out_path}")
+        console.print("Opening in default browser...")
+        webbrowser.open(f"file://{out_path}")
+
+    except Exception as e:
+        console.print(f"[bold red]Visualization failed:[/bold red] {e}")
+        import traceback
+        traceback.print_exc()
+    finally:
+        db_manager.close_driver()
+
+
 def reindex_helper(path: str):
     """Force re-index by deleting and rebuilding the repository."""
     time_start = time.time()

codegraphcontext/cli/config_manager.py

@@ -48,7 +48,7 @@ DEFAULT_CONFIG = {
 
 # Configuration key descriptions
 CONFIG_DESCRIPTIONS = {
-    "DEFAULT_DATABASE": "Default database backend (neo4j|falkordb)",
+    "DEFAULT_DATABASE": "Default database backend (neo4j|falkordb|kuzudb)",
     "FALKORDB_PATH": "Path to FalkorDB database file",
     "FALKORDB_SOCKET_PATH": "Path to FalkorDB Unix socket",
     "INDEX_VARIABLES": "Index variable nodes in the graph (lighter graph if false)",
@@ -75,7 +75,7 @@ CONFIG_DESCRIPTIONS = {
 
 # Valid values for each config key
 CONFIG_VALIDATORS = {
-    "DEFAULT_DATABASE": ["neo4j", "falkordb"],
+    "DEFAULT_DATABASE": ["neo4j", "falkordb", "kuzudb"],
     "INDEX_VARIABLES": ["true", "false"],
     "ALLOW_DB_DELETION": ["true", "false"],
     "DEBUG_LOGS": ["true", "false"],

codegraphcontext/cli/main.py

@@ -229,6 +229,13 @@ def _load_credentials():
     from dotenv import dotenv_values
     from codegraphcontext.cli.config_manager import ensure_config_dir
     
+    # Capture DATABASE_TYPE from actual shell env BEFORE we load .env files.
+    # If the user ran `DATABASE_TYPE=falkordb cgc …` we must not let
+    # DEFAULT_DATABASE=neo4j in .env steal priority later.
+    shell_db_type = os.environ.get('DATABASE_TYPE')
+    if shell_db_type and not os.environ.get('CGC_RUNTIME_DB_TYPE'):
+        os.environ['CGC_RUNTIME_DB_TYPE'] = shell_db_type
+
     # Ensure config directory exists (lazy initialization)
     ensure_config_dir()
     
@@ -272,9 +279,16 @@ def _load_credentials():
     for config in config_sources:
         merged_config.update(config)
     
-    # Apply merged config to environment
+    # Apply merged config to environment.
+    # IMPORTANT: DB-selection keys set in the shell must win over .env defaults.
+    # E.g. `DATABASE_TYPE=falkordb cgc index …` must not be overridden by
+    # DEFAULT_DATABASE=neo4j sitting in ~/.codegraphcontext/.env
+    DB_OVERRIDE_KEYS = {"DATABASE_TYPE", "CGC_RUNTIME_DB_TYPE", "DEFAULT_DATABASE"}
     for key, value in merged_config.items():
         if value is not None:  # Only set non-None values
+            # Never let .env clobber a DB-type key that the user already set in the shell
+            if key in DB_OVERRIDE_KEYS and key in os.environ:
+                continue
             os.environ[key] = str(value)
     
     # Report what was loaded
@@ -287,14 +301,31 @@ def _load_credentials():
         console.print("[yellow]No configuration file found. Using defaults.[/yellow]")
     
     
-    # Show which database is actually being used
-    # Check for runtime override first (from -db/--database flag)
+    # Show which database is actually being used.
+    # When DATABASE_TYPE is explicitly set, trust it.  When it's left to auto-
+    # detect, call get_database_manager() so the banner can never lie: e.g. if
+    # falkordblite is installed but its native .so is missing (frozen bundle),
+    # the factory falls back to KùzuDB and we display that correctly.
     runtime_db = os.environ.get("CGC_RUNTIME_DB_TYPE")
-    if runtime_db:
-        default_db = runtime_db.lower()
+    explicit_db = (
+        runtime_db
+        or os.environ.get("DEFAULT_DATABASE")
+        or os.environ.get("DATABASE_TYPE")
+    )
+
+    if explicit_db:
+        default_db = explicit_db.lower()
     else:
-        default_db = os.environ.get("DEFAULT_DATABASE", "falkordb").lower()
-    
+        # No explicit choice — ask the factory which backend it will use
+        try:
+            from codegraphcontext.core import get_database_manager
+            _mgr = get_database_manager()
+            default_db = _mgr.get_backend_type()   # e.g. 'falkordb' / 'kuzudb'
+        except Exception:
+            # Factory failed entirely — still show a best-guess
+            from codegraphcontext.core import _is_falkordb_available
+            default_db = "falkordb" if _is_falkordb_available() else "kuzudb"
+
     if default_db == "neo4j":
         has_neo4j_creds = all([
             os.environ.get("NEO4J_URI"),
@@ -308,18 +339,26 @@ def _load_credentials():
             else:
                 console.print("[cyan]Using database: Neo4j[/cyan]")
         else:
-            console.print("[yellow]⚠ DEFAULT_DATABASE=neo4j but credentials not found. Falling back to FalkorDB.[/yellow]")
+            console.print("[yellow]⚠ DEFAULT_DATABASE=neo4j but credentials not found. Falling back to default.[/yellow]")
+    elif default_db == "falkordb":
+        console.print("[cyan]Using database: FalkorDB Lite[/cyan]")
+    elif default_db == "kuzudb":
+        console.print("[cyan]Using database: KùzuDB[/cyan]")
     elif default_db == "falkordb-remote":
         host = os.environ.get("FALKORDB_HOST")
         if host:
             console.print(f"[cyan]Using database: FalkorDB Remote ({host})[/cyan]")
         else:
             console.print("[yellow]⚠ DATABASE_TYPE=falkordb-remote but FALKORDB_HOST not set.[/yellow]")
-    else:
+    elif default_db == "falkordb":
         if os.environ.get("FALKORDB_HOST"):
             console.print(f"[cyan]Using database: FalkorDB Remote ({os.environ.get('FALKORDB_HOST')})[/cyan]")
         else:
             console.print("[cyan]Using database: FalkorDB[/cyan]")
+    else:
+        console.print(f"[cyan]Using database: {default_db}[/cyan]")
+
+
 
 # ============================================================================
 # CONFIG COMMAND GROUP

codegraphcontext/core/__init__.py

@@ -2,26 +2,44 @@
 """
 Core database management module.
 
-Supports Neo4j, FalkorDB Lite, and remote FalkorDB backends.
+Supports Neo4j, FalkorDB Lite, remote FalkorDB, and KùzuDB backends.
 Use DATABASE_TYPE environment variable to switch:
-- DATABASE_TYPE=falkordb - Uses embedded FalkorDB Lite (recommended for lite-version)
+- DATABASE_TYPE=kuzudb - Uses embedded KùzuDB (Recommended for cross-platform zero-config)
+- DATABASE_TYPE=falkordb - Uses embedded FalkorDB Lite (Unix-only)
 - DATABASE_TYPE=falkordb-remote - Uses a remote/hosted FalkorDB server over TCP
 - DATABASE_TYPE=neo4j - Uses Neo4j server
 - If not set, auto-detects based on what's available
+
+ Priority (no DATABASE_TYPE set):
+  1. FalkorDB Lite  (Unix + Python 3.12+ + falkordblite installed)
+  2. KùzuDB         (cross-platform fallback)
+  3. Remote FalkorDB (if FALKORDB_HOST is set)
+  4. Neo4j           (if credentials are configured)
 """
 import os
+import platform
 from typing import Union
 
 import importlib.util
 
+def _is_kuzudb_available() -> bool:
+    """Check if KùzuDB is installed."""
+    try:
+        return importlib.util.find_spec("kuzu") is not None
+    except ImportError:
+        return False
+
 def _is_falkordb_available() -> bool:
-    """Check if FalkorDB Lite is installed (without importing native modules)."""
+    """Check if FalkorDB Lite is installed (Unix only)."""
+    if platform.system() == "Windows":
+        return False
+
     import sys
     if sys.version_info < (3, 12):
         return False
     try:
-        # Check for redislite/falkordb-client spec without loading it
-        return importlib.util.find_spec("redislite") is not None
+        import redislite
+        return hasattr(redislite, 'falkordb_client')
     except ImportError:
         return False
 
@@ -37,7 +55,7 @@ def _is_neo4j_configured() -> bool:
         os.getenv('NEO4J_PASSWORD')
     ])
 
-def get_database_manager() -> Union['DatabaseManager', 'FalkorDBManager', 'FalkorDBRemoteManager']:
+def get_database_manager() -> Union['DatabaseManager', 'FalkorDBManager', 'FalkorDBRemoteManager', 'KuzuDBManager']:
     """
     Factory function to get the appropriate database manager based on configuration.
 
@@ -45,12 +63,13 @@ def get_database_manager() -> Union['DatabaseManager', 'FalkorDBManager', 'Falko
     1. Runtime Override: 'CGC_RUNTIME_DB_TYPE' (set via --database flag)
     2. Configured Default: 'DEFAULT_DATABASE' (set via 'cgc default database')
     3. Legacy Env Var: 'DATABASE_TYPE'
-    4. Auto-detect: Remote FalkorDB (if FALKORDB_HOST is set)
-    5. Implicit Default: FalkorDB Lite (if available)
-    6. Fallback: Neo4j (if configured)
+    4. Implicit Default: KùzuDB (Best cross-platform zero-config)
+    5. Auto-detect: Remote FalkorDB (if FALKORDB_HOST is set)
+    6. Fallback Default: FalkorDB Lite (if Unix and available)
+    7. Fallback: Neo4j (if configured)
     """
     from codegraphcontext.utils.debug_log import info_logger
-    
+
     # 1. Runtime Override (CLI flag) or Config/Env
     db_type = os.getenv('CGC_RUNTIME_DB_TYPE')
     if not db_type:
@@ -60,13 +79,33 @@ def get_database_manager() -> Union['DatabaseManager', 'FalkorDBManager', 'Falko
 
     if db_type:
         db_type = db_type.lower()
-        if db_type == 'falkordb':
+        if db_type == 'kuzudb':
+            if not _is_kuzudb_available():
+                raise ValueError("Database set to 'kuzudb' but Kùzu is not installed.\nRun 'pip install kuzu'")
+            from .database_kuzu import KuzuDBManager
+            info_logger("Using KùzuDB (explicit)")
+            return KuzuDBManager()
+
+        elif db_type == 'falkordb':
             if not _is_falkordb_available():
-                 raise ValueError("Database set to 'falkordb' but FalkorDB Lite is not installed.\nRun 'pip install falkordblite'")
-            from .database_falkordb import FalkorDBManager
-            info_logger("Using FalkorDB Lite (explicit)")
-            return FalkorDBManager()
+                info_logger("FalkorDB Lite is not supported or not installed. Falling back to KùzuDB.")
+                if _is_kuzudb_available():
+                    from .database_kuzu import KuzuDBManager
+                    return KuzuDBManager()
+                raise ValueError("Database set to 'falkordb' but FalkorDB Lite is not installed or not supported on this OS.\nRun 'pip install falkordblite'")
             
+            from .database_falkordb import FalkorDBManager, FalkorDBUnavailableError
+            try:
+                mgr = FalkorDBManager()
+                info_logger("Using FalkorDB Lite (explicit)")
+                return mgr
+            except FalkorDBUnavailableError as falkor_err:
+                info_logger(f"FalkorDB Lite not functional ({falkor_err}). Falling back to KùzuDB.")
+                if _is_kuzudb_available():
+                    from .database_kuzu import KuzuDBManager
+                    return KuzuDBManager()
+                raise
+
         elif db_type == 'falkordb-remote':
             if not _is_falkordb_remote_configured():
                 raise ValueError(
@@ -79,52 +118,59 @@ def get_database_manager() -> Union['DatabaseManager', 'FalkorDBManager', 'Falko
 
         elif db_type == 'neo4j':
             if not _is_neo4j_configured():
-                 raise ValueError("Database set to 'neo4j' but it is not configured.\nRun 'cgc neo4j setup' to configure Neo4j.")
+                raise ValueError("Database set to 'neo4j' but it is not configured.\nRun 'cgc neo4j setup' to configure Neo4j.")
             from .database import DatabaseManager
             info_logger("Using Neo4j Server (explicit)")
             return DatabaseManager()
         else:
-            raise ValueError(f"Unknown database type: '{db_type}'. Use 'falkordb', 'falkordb-remote', or 'neo4j'.")
+            raise ValueError(f"Unknown database type: '{db_type}'. Use 'kuzudb', 'falkordb', 'falkordb-remote', or 'neo4j'.")
 
-    # 4. Auto-detect: Remote FalkorDB (if FALKORDB_HOST is set)
+    # 4. Implicit Default -> FalkorDB Lite (Unix Zero Config)
+    if _is_falkordb_available():
+        from .database_falkordb import FalkorDBManager, FalkorDBUnavailableError
+        try:
+            mgr = FalkorDBManager()
+            info_logger("Using FalkorDB Lite (default)")
+            return mgr
+        except FalkorDBUnavailableError as falkor_err:
+            info_logger(
+                f"FalkorDB Lite not functional in this environment ({falkor_err}). "
+                "Falling back to KùzuDB."
+            )
+            # fall through to KùzuDB below
+
+    # 5. Implicit Default -> KùzuDB (Best Zero Config)
+    if _is_kuzudb_available():
+        from .database_kuzu import KuzuDBManager
+        info_logger("Using KùzuDB (default)")
+        return KuzuDBManager()
+
+    # 6. Auto-detect: Remote FalkorDB (if FALKORDB_HOST is set)
     if _is_falkordb_remote_configured():
         from .database_falkordb_remote import FalkorDBRemoteManager
         info_logger("Using remote FalkorDB (auto-detected via FALKORDB_HOST)")
         return FalkorDBRemoteManager()
 
-    # 5. Implicit Default -> FalkorDB Lite (Zero Config)
-    if _is_falkordb_available():
-        from .database_falkordb import FalkorDBManager
-        info_logger("Using FalkorDB Lite (default)")
-        return FalkorDBManager()
-        
-    # 6. Fallback if FalkorDB missing but Neo4j is ready
+    # 7. Fallback if configured
     if _is_neo4j_configured():
         from .database import DatabaseManager
         info_logger("Using Neo4j Server (auto-detected)")
         return DatabaseManager()
 
-    import sys
     error_msg = "No database backend available.\n"
-    
-    if sys.version_info < (3, 12):
-        error_msg += (
-            "FalkorDB Lite is not supported on Python < 3.12.\n"
-            "You are running Python " + str(sys.version_info.major) + "." + str(sys.version_info.minor) + ".\n"
-            "Please upgrade to Python 3.12+ to use the embedded database,\n"
-            "OR run 'cgc neo4j setup' to configure an external Neo4j database."
-        )
-    else:
-        error_msg += (
-            "Recommended: Install FalkorDB Lite ('pip install falkordblite')\n"
-            "Alternative: Run 'cgc neo4j setup' to configure Neo4j."
-        )
-            
+    error_msg += "Recommended: Install KùzuDB for zero-config ('pip install kuzu')\n"
+
+    if platform.system() != "Windows":
+        error_msg += "Alternative: Install FalkorDB Lite ('pip install falkordblite')\n"
+
+    error_msg += "Alternative: Run 'cgc neo4j setup' to configure Neo4j."
+
     raise ValueError(error_msg)
 
-# For backward compatibility, export DatabaseManager
+# For backward compatibility, export managers
 from .database import DatabaseManager
 from .database_falkordb import FalkorDBManager
 from .database_falkordb_remote import FalkorDBRemoteManager
+from .database_kuzu import KuzuDBManager
 
-__all__ = ['DatabaseManager', 'FalkorDBManager', 'FalkorDBRemoteManager', 'get_database_manager']
+__all__ = ['DatabaseManager', 'FalkorDBManager', 'FalkorDBRemoteManager', 'KuzuDBManager', 'get_database_manager']

codegraphcontext/core/database_falkordb.py

@@ -3,6 +3,13 @@
 This module provides a thread-safe singleton manager for the FalkorDB Lite database connection.
 FalkorDB Lite is an embedded graph database that requires no external server setup.
 """
+
+class FalkorDBUnavailableError(RuntimeError):
+    """
+    Raised when FalkorDB Lite is installed but cannot actually run in this
+    environment (e.g. falkordb.so not found in a PyInstaller bundle,
+    or GRAPH.QUERY not available). Callers should fall back to KùzuDB.
+    """
 import os
 import sys
 import subprocess
@@ -167,15 +174,16 @@ class FalkorDBManager:
             try:
                 from falkordb import FalkorDB
                 d = FalkorDB(unix_socket_path=self.socket_path)
-                try:
-                    d.execute_command("PING")
-                except AttributeError:
-                    pass
-                info_logger("Connected to existing FalkorDB Lite process.")
+                # Test not just connectivity (PING), but functionality (GRAPH.QUERY)
+                # This ensures we don't connect to a "stale" process that doesn't have the module loaded
+                test_graph = d.select_graph('__cgc_health_check')
+                test_graph.query("RETURN 1")
+                info_logger("Connected to existing (functional) FalkorDB Lite process.")
                 return
-            except Exception:
-                # Stale socket or unresponsive
-                info_logger("Found stale socket, cleaning up...")
+            except Exception as e:
+                # Stale socket, unresponsive, or "brainless" (unknown command GRAPH.QUERY)
+                info_logger(f"Existing FalkorDB process at {self.socket_path} is stale or non-functional: {e}")
+                info_logger("Cleaning up and attempting fresh start...")
                 try:
                     os.remove(self.socket_path)
                 except OSError:
@@ -190,7 +198,21 @@ class FalkorDBManager:
         python_exe = sys.executable
         
         # We assume codegraphcontext is installed or in python path
-        cmd = [python_exe, '-m', 'codegraphcontext.core.falkor_worker']
+        if getattr(sys, 'frozen', False):
+            # In frozen mode, the executable is the bundle itself.
+            # We tell the bundle to run the worker instead of the app via environment variable.
+            env['CGC_RUN_FALKOR_WORKER'] = 'true'
+            cmd = [python_exe]
+        else:
+            # If not frozen, sys.executable should be python.
+            # But on some platforms (like PIP installs), it might be the 'cgc' entry point script.
+            # We check if it looks like python, otherwise search the PATH.
+            import shutil
+            exe_name = os.path.basename(python_exe).lower()
+            if not any(x in exe_name for x in ['python', 'py.exe', 'pypy']):
+                python_exe = shutil.which('python3') or shutil.which('python') or sys.executable
+            
+            cmd = [python_exe, '-m', 'codegraphcontext.core.falkor_worker']
         
         info_logger("Starting FalkorDB Lite worker subprocess...")
         self._process = subprocess.Popen(cmd, env=env, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
@@ -209,7 +231,15 @@ class FalkorDBManager:
             # Check if process died
             if self._process.poll() is not None:
                 out, err = self._process.communicate()
-                raise RuntimeError(f"FalkorDB worker failed to start (Exit Code {self._process.returncode}):\nSTDOUT: {out.decode()}\nSTDERR: {err.decode()}")
+                returncode = self._process.returncode
+                
+                # Any non-zero exit code during startup means this backend is toast
+                # Raise FalkorDBUnavailableError to trigger the automatic KùzuDB fallback
+                raise FalkorDBUnavailableError(
+                    f"FalkorDB Lite worker failed to start (Exit Code {returncode}).\n"
+                    f"STDOUT: {out.decode().strip()}\n"
+                    f"STDERR: {err.decode().strip()}"
+                )
             
             time.sleep(0.5)
             
@@ -217,8 +247,10 @@ class FalkorDBManager:
 
     def close_driver(self):
         """Closes the connection."""
-        self._driver = None
-        self._graph = None
+        if self._driver is not None:
+            info_logger("Closing FalkorDB Lite connection")
+            self._driver = None
+            self._graph = None
 
     def shutdown(self):
         """Kills the subprocess on exit."""

codegraphcontext/core/database_falkordb_remote.py

@@ -114,8 +114,10 @@ class FalkorDBRemoteManager:
 
     def close_driver(self):
         """Closes the connection."""
-        self._driver = None
-        self._graph = None
+        if self._driver is not None:
+            info_logger("Closing FalkorDB Remote connection")
+            self._driver = None
+            self._graph = None
 
     def shutdown(self):
         """Clean up on exit. No subprocess to kill for remote connections."""