codegraphcontext-rust 0.5.5__cp310-cp310-win_amd64.whl

codegraphcontext/core/falkor_worker.py

@@ -0,0 +1,132 @@
+import sys
+import os
+import time
+import signal
+from pathlib import Path
+import logging
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+logger = logging.getLogger("falkor_worker")
+
+# Global to handle shutdown
+db_instance = None
+
+def handle_signal(signum, frame):
+    logger.info(f"Received signal {signum}. Stopping FalkorDB worker...")
+    sys.exit(0)
+
+def run_worker():
+    global db_instance
+    
+    # Get configuration from env
+    db_path = os.getenv('FALKORDB_PATH')
+    socket_path = os.getenv('FALKORDB_SOCKET_PATH')
+    
+    if not db_path or not socket_path:
+        logger.error("Missing configuration. FALKORDB_PATH and FALKORDB_SOCKET_PATH must be set.")
+        sys.exit(1)
+        
+    # Ensure dir exists
+    Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+    
+    logger.info(f"Starting FalkorDB Lite worker...")
+    logger.info(f"DB Path: {db_path}")
+    logger.info(f"Socket: {socket_path}")
+    
+    try:
+        import platform
+        
+        if platform.system() == "Windows":
+            raise RuntimeError(
+                "CodeGraphContext uses redislite/FalkorDB, which does not support Windows.\n"
+                "Please run the project using WSL or Docker."
+            )
+        
+        from redislite.falkordb_client import FalkorDB
+        
+        # Determine module path for frozen bundles
+        server_config = {}
+        if getattr(sys, 'frozen', False):
+            mei_pass = getattr(sys, '_MEIPASS', os.path.dirname(sys.executable))
+            exe_dir  = os.path.dirname(sys.executable)
+            
+            # All known locations PyInstaller may extract falkordb.so to
+            potential_paths = [
+                # Standard redislite layout
+                os.path.join(mei_pass, 'redislite', 'bin', 'falkordb.so'),
+                # falkordblite scripts layout
+                os.path.join(mei_pass, 'falkordblite.scripts', 'falkordb.so'),
+                # Root of the bundle (add_binary with '.' target)
+                os.path.join(mei_pass, 'falkordb.so'),
+                # Alongside the executable itself
+                os.path.join(exe_dir, 'falkordb.so'),
+                # redislite data dir variant
+                os.path.join(mei_pass, 'redislite', 'falkordb.so'),
+                # falkordblite.libs (shared-lib bundle)
+                os.path.join(mei_pass, 'falkordblite.libs', 'falkordb.so'),
+            ]
+            
+            module_path = None
+            for p in potential_paths:
+                if os.path.exists(p):
+                    module_path = p
+                    break
+            
+            if module_path:
+                logger.info(f"Using FalkorDB module from bundle: {module_path}")
+                server_config['loadmodule'] = module_path
+            else:
+                logger.error(
+                    "Could not find falkordb.so in the PyInstaller bundle. "
+                    "Searched: " + str(potential_paths)
+                )
+                # Exit with a distinct code so the parent can detect FalkorDB is
+                # unavailable in this environment and fall back to KùzuDB.
+                sys.exit(2)
+
+        # Start Embedded DB
+        if os.path.exists(socket_path):
+            try:
+                os.remove(socket_path)
+            except OSError:
+                pass
+
+        db_instance = FalkorDB(db_path, unix_socket_path=socket_path, serverconfig=server_config)
+        logger.info("FalkorDB Lite is running.")
+        
+        # Validate that FalkorDB module actually loaded by running a GRAPH.QUERY
+        try:
+            test_graph = db_instance.select_graph('__cgc_health_check')
+            test_graph.query('RETURN 1')
+            logger.info("FalkorDB GRAPH.QUERY OK.")
+        except Exception as health_err:
+            err_str = str(health_err).lower()
+            if 'graph.query' in err_str or 'unknown command' in err_str:
+                logger.error(
+                    f"FalkorDB module not loaded — GRAPH.QUERY unavailable: {health_err}. "
+                    "The Redis server started but the FalkorDB .so module was not loaded."
+                )
+                sys.exit(2)  # same exit code: parent will fall back to KùzuDB
+            else:
+                logger.warning(f"FalkorDB health-check warning (non-fatal): {health_err}")
+        
+        # Keep alive loop
+        while True:
+            time.sleep(1)
+            
+    except ImportError as e:
+        logger.error(f"Failed to import redislite.falkordb_client: {e}")
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)
+    except Exception as e:
+        logger.error(f"FalkorDB Worker Critical Failure: {e}")
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)
+
+if __name__ == '__main__':
+    signal.signal(signal.SIGTERM, handle_signal)
+    signal.signal(signal.SIGINT, handle_signal)
+    run_worker()

codegraphcontext/core/jobs.py

@@ -0,0 +1,132 @@
+# src/codegraphcontext/core/jobs.py
+"""
+This module defines the data structures and manager for handling long-running,
+background jobs, such as code indexing.
+"""
+import uuid
+import threading
+from datetime import datetime, timedelta
+from dataclasses import dataclass, asdict
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from pathlib import Path
+
+
+class JobStatus(Enum):
+    """Enumeration for the possible statuses of a background job."""
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+@dataclass
+class JobInfo:
+    """
+    A data class to hold all information about a single background job.
+    This makes it easy to track the job's progress, status, and results.
+    """
+    job_id: str
+    status: JobStatus
+    start_time: datetime
+    end_time: Optional[datetime] = None
+    total_files: int = 0
+    processed_files: int = 0
+    current_file: Optional[str] = None
+    estimated_duration: Optional[float] = None
+    actual_duration: Optional[float] = None
+    errors: List[str] = None
+    result: Optional[Dict[str, Any]] = None
+    path: Optional[str] = None
+    is_dependency: bool = False
+
+    def __post_init__(self):
+        """Ensures the errors list is initialized after the object is created."""
+        if self.errors is None:
+            self.errors = []
+
+    @property
+    def progress_percentage(self) -> float:
+        """Calculates the completion percentage of the job."""
+        if self.total_files == 0:
+            return 0.0
+        return (self.processed_files / self.total_files) * 100
+
+    @property
+    def estimated_time_remaining(self) -> Optional[float]:
+        """Calculates the estimated time remaining based on the average time per file."""
+        if self.status != JobStatus.RUNNING or self.processed_files == 0:
+            return None
+        elapsed = (datetime.now() - self.start_time).total_seconds()
+        avg_time_per_file = elapsed / self.processed_files
+        remaining_files = self.total_files - self.processed_files
+        return remaining_files * avg_time_per_file
+
+class JobManager:
+    """
+    A thread-safe manager for creating, updating, and retrieving information
+    about background jobs. It stores job information in memory.
+    """
+    def __init__(self):
+        self.jobs: Dict[str, JobInfo] = {}
+        self.lock = threading.Lock() # A lock to ensure thread-safe access to the jobs dictionary.
+
+    def create_job(self, path: str, is_dependency: bool = False) -> str:
+        """Creates a new job, assigns it a unique ID, and stores it."""
+        job_id = str(uuid.uuid4())
+        with self.lock:
+            self.jobs[job_id] = JobInfo(
+                job_id=job_id,
+                status=JobStatus.PENDING,
+                start_time=datetime.now(),
+                path=path,
+                is_dependency=is_dependency
+            )
+        return job_id
+
+    def update_job(self, job_id: str, **kwargs):
+        """Updates the information for a specific job in a thread-safe manner."""
+        with self.lock:
+            if job_id in self.jobs:
+                job = self.jobs[job_id]
+                for key, value in kwargs.items():
+                    if hasattr(job, key):
+                        setattr(job, key, value)
+
+    def get_job(self, job_id: str) -> Optional[JobInfo]:
+        """Retrieves the information for a single job."""
+        with self.lock:
+            return self.jobs.get(job_id)
+
+    def list_jobs(self) -> List[JobInfo]:
+        """Returns a list of all jobs currently in the manager."""
+        with self.lock:
+            return list(self.jobs.values())
+
+    def find_active_job_by_path(self, path: str) -> Optional[JobInfo]:
+        """Finds the most recent, currently active (pending or running) job for a given path."""
+        with self.lock:
+            path_obj = Path(path).resolve()
+            
+            matching_jobs = sorted(
+                [job for job in self.jobs.values() if job.path and Path(job.path).resolve() == path_obj],
+                key=lambda j: j.start_time,
+                reverse=True
+            )
+
+            for job in matching_jobs:
+                if job.status in [JobStatus.PENDING, JobStatus.RUNNING]:
+                    return job
+                    
+            return None
+
+    def cleanup_old_jobs(self, max_age_hours: int = 24):
+        """Removes old, completed jobs from memory to prevent memory leaks."""
+        cutoff_time = datetime.now() - timedelta(hours=max_age_hours)
+        with self.lock:
+            jobs_to_remove = [
+                job_id for job_id, job in self.jobs.items()
+                if job.end_time and job.end_time < cutoff_time
+            ]
+            for job_id in jobs_to_remove:
+                del self.jobs[job_id]

codegraphcontext/core/watcher.py

@@ -0,0 +1,260 @@
+# src/codegraphcontext/core/watcher.py
+"""
+This module implements the live file-watching functionality using the `watchdog` library.
+It observes directories for changes and triggers updates to the code graph.
+"""
+import threading
+from pathlib import Path
+import typing
+from watchdog.observers import Observer
+from watchdog.events import FileSystemEventHandler
+
+if typing.TYPE_CHECKING:
+    from codegraphcontext.tools.graph_builder import GraphBuilder
+    from codegraphcontext.core.jobs import JobManager
+
+from codegraphcontext.utils.debug_log import debug_log, info_logger, error_logger, warning_logger
+
+class RepositoryEventHandler(FileSystemEventHandler):
+    """
+    A dedicated event handler for a single repository being watched.
+    
+    This handler is stateful. It performs an initial scan of the repository
+    to build a baseline and then uses this cached state to perform efficient
+    updates when files are changed, created, or deleted.
+    """
+    def __init__(self, graph_builder: "GraphBuilder", repo_path: Path, debounce_interval=2.0, perform_initial_scan: bool = True):
+        """
+        Initializes the event handler.
+
+        Args:
+            graph_builder: An instance of the GraphBuilder to perform graph operations.
+            repo_path: The absolute path to the repository directory to watch.
+            debounce_interval: The time in seconds to wait for more changes before processing an event.
+            perform_initial_scan: Whether to perform an initial scan of the repository.
+        """
+        super().__init__()
+        self.graph_builder = graph_builder
+        self.repo_path = repo_path
+        self.debounce_interval = debounce_interval
+        self.timers = {} # A dictionary to manage debounce timers for file paths.
+        
+        # Caches for the repository's state.
+        self.all_file_data = []
+        self.imports_map = {}
+        
+        # Perform the initial scan and linking when the watcher is created.
+        if perform_initial_scan:
+            self._initial_scan()
+
+    def _initial_scan(self):
+        """Scans the entire repository, parses all files, and builds the initial graph."""
+        info_logger(f"Performing initial scan for watcher: {self.repo_path}")
+        supported_extensions = self.graph_builder.parsers.keys()
+        all_files = [f for f in self.repo_path.rglob("*") if f.is_file() and f.suffix in supported_extensions]
+        
+        # 1. Pre-scan all files to get a global map of where every symbol is defined.
+        self.imports_map = self.graph_builder.pre_scan_imports(all_files)
+        
+        # 2. Parse all files in detail and cache the parsed data.
+        for f in all_files:
+            parsed_data = self.graph_builder.parse_file(self.repo_path, f)
+            if "error" not in parsed_data:
+                self.all_file_data.append(parsed_data)
+        
+        # 3. After all files are parsed, create the relationships (e.g., function calls) between them.
+        self.graph_builder.link_function_calls(self.all_file_data, self.imports_map)
+        self.graph_builder.link_inheritance(self.all_file_data, self.imports_map)
+        # Free memory — all_file_data is only needed during the linking pass.
+        self.all_file_data.clear()
+        info_logger(f"Initial scan and graph linking complete for: {self.repo_path}")
+
+    def _debounce(self, event_path, action):
+        """
+        Schedules an action to run after a debounce interval.
+        This prevents the handler from firing on every single file save event in rapid
+        succession, which is common in IDEs. It waits for a quiet period before processing.
+        """
+        # If a timer already exists for this path, cancel it.
+        if event_path in self.timers:
+            self.timers[event_path].cancel()
+        # Create and start a new timer.
+        timer = threading.Timer(self.debounce_interval, action)
+        timer.start()
+        self.timers[event_path] = timer
+
+    def _update_imports_map_for_file(self, changed_path: Path):
+        """Re-scan a single file and merge its contributions into self.imports_map.
+        Removes stale paths for the file before inserting new ones so renamed/deleted
+        symbols don't leave dangling entries."""
+        changed_str = str(changed_path.resolve())
+        # Remove old contributions of this file from every symbol it previously exported.
+        for symbol in list(self.imports_map.keys()):
+            old_list = self.imports_map[symbol]
+            if changed_str in old_list:
+                new_list = [p for p in old_list if p != changed_str]
+                if new_list:
+                    self.imports_map[symbol] = new_list
+                else:
+                    del self.imports_map[symbol]
+        # Merge new contributions (if the file still exists).
+        if changed_path.exists():
+            new_map = self.graph_builder.pre_scan_imports([changed_path])
+            for symbol, paths in new_map.items():
+                if symbol not in self.imports_map:
+                    self.imports_map[symbol] = []
+                self.imports_map[symbol].extend(paths)
+
+    def _handle_modification(self, event_path_str: str):
+        """
+        Incremental update: only re-parse and re-link the changed file plus the files
+        that previously called into it.  O(k) instead of O(n) for every event.
+
+        Algorithm:
+          1. Query Neo4j for files that have CALLS/INHERITS touching the changed file
+             (must happen BEFORE nodes are deleted, so the graph still has the old edges).
+          2. Update self.imports_map for the changed file only (O(1) file scan).
+          3. update_file_in_graph — DETACH DELETE cleans up ALL CALLS/INHERITS on the
+             changed file's nodes (both incoming and outgoing) automatically.
+          4. Delete outgoing CALLS from affected *caller* files (their CALLS to the changed
+             file were removed by DETACH DELETE, but their CALLS to unrelated files are
+             still there; we must delete all their outgoing CALLS before re-creating so we
+             don't leave stale CALLS to functions that have moved/been renamed).
+          5. Re-parse only the affected subset (changed file + callers + inheritors).
+          6. Build file_class_lookup cheaply from Neo4j (no full re-parse needed).
+          7. Re-create CALLS/INHERITS for the subset only.
+        """
+        info_logger(f"File change detected (incremental update): {event_path_str}")
+        changed_path = Path(event_path_str)
+        changed_path_str = str(changed_path.resolve())
+        supported_extensions = self.graph_builder.parsers.keys()
+
+        # Step 1: Find affected neighbours BEFORE nodes are destroyed.
+        caller_paths = self.graph_builder.get_caller_file_paths(changed_path_str)
+        inheritor_paths = self.graph_builder.get_inheritance_neighbor_paths(changed_path_str)
+        affected_paths = {changed_path_str} | caller_paths | inheritor_paths
+        info_logger(
+            f"[INCREMENTAL] affected={len(affected_paths)} files "
+            f"(callers={len(caller_paths)}, inheritors={len(inheritor_paths)})"
+        )
+
+        # Step 2: Update imports_map for the changed file only.
+        self._update_imports_map_for_file(changed_path)
+
+        # Step 3: Delete + re-add nodes for the changed file.
+        # DETACH DELETE inside update_file_in_graph removes all CALLS/INHERITS on its nodes.
+        self.graph_builder.update_file_in_graph(changed_path, self.repo_path, self.imports_map)
+
+        # Step 4: Clean up CALLS/INHERITS from the affected *caller/inheritor* files.
+        # Their CALLS to the changed file were already removed by DETACH DELETE, but their
+        # CALLS to other files are still intact.  We delete all their outgoing CALLS so we
+        # can safely re-create the full set from scratch for the subset.
+        other_callers = list(caller_paths)       # does NOT include changed_path_str
+        other_inheritors = list(inheritor_paths)
+        if other_callers:
+            self.graph_builder.delete_outgoing_calls_from_files(other_callers)
+        if other_inheritors:
+            self.graph_builder.delete_inherits_for_files(other_inheritors)
+
+        # Step 5: Re-parse only the affected subset.
+        subset_file_data = []
+        for path_str in affected_paths:
+            p = Path(path_str)
+            if p.exists() and p.suffix in supported_extensions:
+                parsed = self.graph_builder.parse_file(self.repo_path, p)
+                if "error" not in parsed:
+                    subset_file_data.append(parsed)
+
+        # Step 6: Get full-repo file_class_lookup from Neo4j (avoids re-parsing all files).
+        # The changed file's new classes are already overlaid inside _create_all_function_calls.
+        file_class_lookup = self.graph_builder.get_repo_class_lookup(self.repo_path)
+
+        # Step 7: Re-create CALLS/INHERITS for the affected subset only.
+        info_logger(f"[INCREMENTAL] Re-linking {len(subset_file_data)} files...")
+        self.graph_builder.link_function_calls(subset_file_data, self.imports_map, file_class_lookup)
+        self.graph_builder.link_inheritance(subset_file_data, self.imports_map)
+        info_logger(f"[INCREMENTAL] Done. Graph refresh for {event_path_str} complete! ✅")
+
+    # The following methods are called by the watchdog observer when a file event occurs.
+    def on_created(self, event):
+        if not event.is_directory and Path(event.src_path).suffix in self.graph_builder.parsers:
+            self._debounce(event.src_path, lambda: self._handle_modification(event.src_path))
+
+    def on_modified(self, event):
+        if not event.is_directory and Path(event.src_path).suffix in self.graph_builder.parsers:
+            self._debounce(event.src_path, lambda: self._handle_modification(event.src_path))
+
+    def on_deleted(self, event):
+        if not event.is_directory and Path(event.src_path).suffix in self.graph_builder.parsers:
+            self._debounce(event.src_path, lambda: self._handle_modification(event.src_path))
+
+    def on_moved(self, event):
+        if not event.is_directory:
+            if Path(event.src_path).suffix in self.graph_builder.parsers:
+                self._debounce(event.src_path, lambda: self._handle_modification(event.src_path))
+            if Path(event.dest_path).suffix in self.graph_builder.parsers:
+                self._debounce(event.dest_path, lambda: self._handle_modification(event.dest_path))
+
+
+class CodeWatcher:
+    """
+    Manages the file system observer thread. It can watch multiple directories,
+    assigning a separate `RepositoryEventHandler` to each one.
+    """
+    def __init__(self, graph_builder: "GraphBuilder", job_manager= "JobManager"):
+        self.graph_builder = graph_builder
+        self.observer = Observer()
+        self.watched_paths = set() # Keep track of paths already being watched.
+        self.watches = {} # Store watch objects to allow unscheduling
+
+    def watch_directory(self, path: str, perform_initial_scan: bool = True):
+        """Schedules a directory to be watched for changes."""
+        path_obj = Path(path).resolve()
+        path_str = str(path_obj)
+
+        if path_str in self.watched_paths:
+            info_logger(f"Path already being watched: {path_str}")
+            return {"message": f"Path already being watched: {path_str}"}
+        
+        # Create a new, dedicated event handler for this specific repository path.
+        event_handler = RepositoryEventHandler(self.graph_builder, path_obj, perform_initial_scan=perform_initial_scan)
+        
+        watch = self.observer.schedule(event_handler, path_str, recursive=True)
+        self.watches[path_str] = watch
+        self.watched_paths.add(path_str)
+        info_logger(f"Started watching for code changes in: {path_str}")
+        
+        return {"message": f"Started watching {path_str}."}
+    def unwatch_directory(self, path: str):
+        """Stops watching a directory for changes."""
+        path_obj = Path(path).resolve()
+        path_str = str(path_obj)
+
+        if path_str not in self.watched_paths:
+            warning_logger(f"Attempted to unwatch a path that is not being watched: {path_str}")
+            return {"error": f"Path not currently being watched: {path_str}"}
+
+        watch = self.watches.pop(path_str, None)
+        if watch:
+            self.observer.unschedule(watch)
+        
+        self.watched_paths.discard(path_str)
+        info_logger(f"Stopped watching for code changes in: {path_str}")
+        return {"message": f"Stopped watching {path_str}."}
+
+    def list_watched_paths(self) -> list:
+        """Returns a list of all currently watched directory paths."""
+        return list(self.watched_paths)
+
+    def start(self):
+        """Starts the observer thread."""
+        if not self.observer.is_alive():
+            self.observer.start()
+            info_logger("Code watcher observer thread started.")
+
+    def stop(self):
+        """Stops the observer thread gracefully."""
+        if self.observer.is_alive():
+            self.observer.stop()
+            self.observer.join() # Wait for the thread to terminate.
+            info_logger("Code watcher observer thread stopped.")

codegraphcontext/prompts.py

@@ -0,0 +1,125 @@
+# src/codegraphcontext/prompts.py
+"""
+This file contains the system prompt for the language model.
+This prompt provides the core instructions, principles, and standard operating
+procedures for the AI assistant, guiding it on how to effectively use the tools
+provided by this MCP server.
+"""
+
+LLM_SYSTEM_PROMPT = """# AI Pair Programmer Instructions
+
+## 1. Your Role and Goal
+
+You are an expert AI pair programmer. Your primary goal is to help a developer understand, write, and refactor code within their **local project**. Your defining feature is your connection to a local Model Context Protocol (MCP) server, which gives you real-time, accurate information about the codebase.
+**Always prioritize using this MCP tools when they can simplify or enhance your workflow compared to guessing.**
+
+## 2. Your Core Principles
+
+### Principle I: Ground Your Answers in Fact
+**Your CORE DIRECTIVE is to use the provided tools to gather facts from the MCP server *before* answering questions or generating code.** Do not guess. Your value comes from providing contextually-aware, accurate assistance.
+
+### Principle II: Be an Agent, Not Just a Planner
+**Your goal is to complete the user's task in the fewest steps possible.**
+* If the user's request maps directly to a single tool, **execute that tool immediately.**
+* Do not create a multi-step plan for a one-step task. The Standard Operating Procedures (SOPs) below are for complex queries that require reasoning and combining information from multiple tools.
+
+**Example of what NOT to do:**
+
+> **User:** "Start watching the `my-project` folder."
+> **Incorrect Plan:**
+> 1. Check if `watchdog` is installed.
+> 2. Use the `watch_directory` tool on `my-project`.
+> 3. Update a todo list.
+
+**Example of the CORRECT, direct action:**
+
+> **User:** "Start watching the `my-project` folder."
+> **Correct Action:** Immediately call the `watch_directory` tool.
+> ```json
+> {
+>     "tool_name": "watch_directory",
+>     "arguments": { "path": "my-project" }
+> }
+> ```
+
+## 3. Tool Manifest & Usage
+
+| Tool Name                    | Purpose & When to Use                                                                                                                                 |
+| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
+| **`find_code`** | **Your primary search tool.** Use this first for almost any query about locating code.          t                                         |
+| **`analyze_code_relationships`** | **Your deep analysis tool.** Use this after locating a specific item. Use query types like `find_callers` or `find_callees`.      |
+| **`add_code_to_graph`** | **Your indexing tool.** Use this when the user wants to add a new project folder or file to the context.                               |
+| **`add_package_to_graph`** | **Your dependency indexing tool.** Use this to add a `pip` package to the context.                                                                    |
+| **`list_jobs`** & **`check_job_status`** | **Your job monitoring tools.** |
+| **`watch_directory`** | **Your live-update tool.** Use this if the user wants to automatically keep the context updated as they work.                          |
+| **`execute_cypher_query`** | **Expert Fallback Tool.** Use this *only* when other tools cannot answer a very specific or complex question about the code graph. Requires knowledge of Cypher. |
+
+## 4. Graph Schema Reference
+**CRITICAL FOR CYPHER QUERIES:** The database schema uses specific property names.
+
+### Nodes & Properties
+* **`Repository`**
+    * `name` (string)
+    * `path` (string, absolute path)
+    * `is_dependency` (boolean)
+* **`File`**
+    * `name` (string)
+    * `path` (string, absolute path)
+    * `relative_path` (string)
+    * `is_dependency` (boolean)
+* **`Function`**
+    * `name` (string)
+    * `path` (string, absolute path) **<-- NOTE: Use `path`, NOT `path`**
+    * `line_number` (int)
+    * `end_line` (int)
+    * `args` (list)
+    * `cyclomatic_complexity` (int)
+    * `decorators` (list)
+    * `lang` (string)
+    * `source` (string, the full source code of the function)
+    * `is_dependency` (boolean)
+* **`Class`**
+    * `name` (string)
+    * `path` (string, absolute path) **<-- NOTE: Use `path`, NOT `path`**
+    * `line_number` (int)
+    * `end_line` (int)
+    * `bases` (list)
+    * `decorators` (list)
+    * `lang` (string)
+    * `source` (string, the full source code of the class)
+    * `is_dependency` (boolean)
+
+### Relationships
+* **`CONTAINS`**:
+    * `(Repository)-[:CONTAINS]->(File)`
+    * `(File)-[:CONTAINS]->(Function)`
+    * `(File)-[:CONTAINS]->(Class)`
+* **`CALLS`**: `(Function)-[:CALLS]->(Function)`
+* **`IMPORTS`**: `(File)-[:IMPORTS]->(Module)`
+* **`INHERITS`**: `(Class)-[:INHERITS]->(Class)`
+
+## 5. Standard Operating Procedures (SOPs) for Complex Tasks
+
+**Note:** Follow these methodical workflows for **complex requests** that require multiple steps of reasoning or combining information from several tools. For direct commands, refer to Principle II and act immediately.
+
+### SOP-1: Answering "Where is...?" or "How does...?" Questions
+1.  **Locate:** Use `find_code` to find the relevant code.
+2.  **Analyze:** Use `analyze_code_relationships` to understand its usage.
+3.  **Synthesize:** Combine the information into a clear explanation.
+
+### SOP-2: Generating New Code
+1.  **Find Context:** Use `find_code` to find similar, existing code to match the style.
+2.  **Find Reusable Code:** Use `find_code` to locate specific helper functions the user wants you to use.
+3.  **Generate:** Write the code using the correct imports and signatures.
+
+### SOP-3: Refactoring or Analyzing Impact
+1.  **Identify & Locate:** Use `find_code` to get the canonical path of the item to be changed.
+2.  **Assess Impact:** Use `analyze_code_relationships` with the `find_callers` query type to find all affected locations.
+3.  **Report Findings:** Present a clear list of all affected files.
+
+### SOP-4: Using the Cypher Fallback
+1.  **Attempt Standard Tools:** First, always try to use `find_code` and `analyze_code_relationships`.
+2.  **Identify Failure:** If the standard tools cannot answer a complex, multi-step relationship query (e.g., "Find all functions that are called by a method in a class that inherits from 'BaseHandler'"), then and only then, resort to the fallback.
+3.  **Formulate & Execute:** Construct a Cypher query to find the answer and execute it using `execute_cypher_query`. **Consult the Graph Schema Reference above to ensure you use the correct property names (e.g. `path` vs `path`).**
+4.  **Present Results:** Explain the results to the user based on the query output.
+"""