pygeai 0.6.0b14__py3-none-any.whl → 0.6.1__py3-none-any.whl

pygeai/_docs/source/content/debugger.rst

@@ -4,16 +4,17 @@ PyGEAI Debugger
 Overview
 --------
 
-``geai-dbg`` is a command-line debugger for the ``geai`` CLI tool, part of the ``pygeai`` package. It allows developers to pause execution at specified points (breakpoints) in the ``geai`` codebase, inspect local variables, navigate the call stack, step through code execution, and control program flow interactively.
+``geai-dbg`` is an interactive command-line debugger for PyGEAI applications. It enables developers to debug the ``geai`` CLI, custom Python scripts that use PyGEAI, or specific PyGEAI modules. The debugger pauses execution at specified breakpoints, allowing inspection of variables, stack navigation, code stepping, and interactive control of program flow.
 
 The debugger provides features similar to Python's built-in ``pdb`` debugger, including:
 
-- **Breakpoint management**: Set, list, enable/disable, and remove breakpoints
+- **Multiple debugging modes**: Debug geai CLI, Python files, or specific modules
+- **Breakpoint management**: Set, list, enable/disable, and remove breakpoints with optional conditions
 - **Stepping**: Step into, over, and out of function calls
 - **Stack navigation**: Move up and down the call stack to inspect different frames
 - **Variable inspection**: Print, pretty-print, and examine local/global variables
 - **Source code display**: View source code around the current execution point
-- **Performance optimization**: Only traces relevant modules to minimize overhead
+- **Performance optimization**: Module filtering to minimize overhead
 - **Command history**: Uses readline for command history and editing
 
 Installation and Setup
@@ -25,52 +26,130 @@ Installation and Setup
 
     pip install pygeai
 
-No additional setup is required. The debugger script (``debugger.py``) is located in the ``pygeai.dbg`` module and can be invoked via the ``geai-dbg`` command.
+No additional setup is required. The debugger is located in the ``pygeai.dbg`` module and can be invoked via the ``geai-dbg`` command.
 
-Usage
------
+Usage Modes
+-----------
+
+The debugger supports three distinct usage modes:
 
-Basic Usage
-~~~~~~~~~~~
+Mode 1: Debug geai CLI (Default)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To use ``geai-dbg``, run it with the same arguments you would pass to the ``geai`` CLI. For example:
+Debug the ``geai`` CLI tool with your command arguments:
 
 .. code-block:: bash
 
+    geai-dbg
     geai-dbg ail lrs
+    geai-dbg chat "Hello, AI"
 
-This command runs the ``geai`` CLI with the arguments ``ail lrs`` under the debugger. The debugger automatically sets a breakpoint at the ``main`` function in the ``pygeai.cli.geai`` module, pausing execution before the ``geai`` command processes the arguments.
+This runs the ``geai`` CLI under the debugger with an automatic breakpoint at ``pygeai.cli.geai:main``.
 
-Upon hitting a breakpoint, the debugger displays:
+Mode 2: Debug Python Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- The location (module and function) where execution is paused
-- Source code context around the current line
-- An interactive prompt ``(geai-dbg)`` for entering commands
+Debug any Python script that uses PyGEAI:
 
-Custom Target Functions
-~~~~~~~~~~~~~~~~~~~~~~~
+.. code-block:: bash
+
+    geai-dbg my_script.py
+    geai-dbg my_script.py --input data.csv --output results.json
+    geai-dbg -b process_data my_script.py
+
+The debugger automatically detects whether your script imports PyGEAI and adjusts module filtering accordingly.
+
+Mode 3: Debug Specific Modules
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Debug a specific module and function directly:
+
+.. code-block:: bash
+
+    geai-dbg -m pygeai.cli.geai:main
+    geai-dbg -m pygeai.chat:send_message -b process_response
+
+This imports the module, sets up debugging, and runs the specified function.
+
+Command-Line Options
+--------------------
+
+.. code-block:: text
+
+    geai-dbg [OPTIONS] [target] [args...]
+
+    Options:
+      -h, --help            Show help message
+      -m MODULE:FUNC        Debug a module function (e.g., pygeai.cli.geai:main)
+      -b BREAKPOINT         Set initial breakpoint ([module:]function)
+      --filter PREFIX       Only trace modules with this prefix
+      --trace-all           Trace all modules (warning: slow)
+      -v, --verbose         Enable verbose logging for pygeai modules
+      --log-level LEVEL     Log level for verbose mode: DEBUG, INFO, WARNING, ERROR (default: DEBUG)
+
+    Examples:
+      geai-dbg                                 Debug the geai CLI
+      geai-dbg script.py arg1 arg2             Debug a Python file with arguments
+      geai-dbg -v script.py                    Debug with verbose logging (DEBUG level)
+      geai-dbg -v --log-level INFO script.py   Debug with INFO level logging
+      geai-dbg -m pygeai.cli.geai:main         Debug a specific module function
+      geai-dbg -b main script.py               Break on 'main' function
+      geai-dbg --filter pygeai script.py       Only trace pygeai modules
+
+Programmatic Usage
+------------------
+
+Debug a Python File
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from pygeai.dbg import debug_file
+    
+    # Set up debugger for a file
+    dbg = debug_file('my_script.py', args=['--verbose'])
+    dbg.add_breakpoint(function_name='process_data')
+    dbg.add_breakpoint(module='pygeai.chat', function_name='send_message')
+    
+    # Run with debugging
+    dbg.run()
+    
+    # Enable verbose logging with custom log level
+    dbg = debug_file('my_script.py', verbose=True, log_level='INFO')
+    dbg.run()
+
+Debug a Module
+~~~~~~~~~~~~~~
+
+.. code-block:: python
 
-You can also debug custom Python functions using the ``Debugger`` class directly:
+    from pygeai.dbg import debug_module
+    
+    # Debug a specific module function
+    dbg = debug_module('pygeai.cli.geai', 'main')
+    dbg.add_breakpoint(module='pygeai.core.llm', function_name='get_completion')
+    dbg.run()
+
+Advanced Configuration
+~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: python
 
-    from pygeai.dbg.debugger import Debugger
+    from pygeai.dbg import Debugger
     
     def my_function():
-        x = 10
-        y = 20
-        result = x + y
-        print(f"Result: {result}")
-    
-    # Create debugger and set breakpoint
-    dbg = Debugger(target=my_function, module_filter="__main__")
-    dbg.add_breakpoint(module="__main__", function_name="my_function")
+        # Your code here
+        pass
+    
+    # Create custom debugger
+    dbg = Debugger(target=my_function, module_filter='')  # Trace all modules
+    dbg.add_breakpoint(function_name='helper_func', condition='x > 100')
     dbg.run()
 
-Commands Reference
-------------------
+Interactive Commands
+--------------------
 
-At the ``(geai-dbg)`` prompt, the following commands are available:
+Once paused at a breakpoint, the following commands are available at the ``(geai-dbg)`` prompt:
 
 Flow Control
 ~~~~~~~~~~~~
@@ -90,13 +169,13 @@ Flow Control
 **run, r**
     Run the program to completion, disabling all breakpoints and skipping further pauses.
 
-**quit, q, Ctrl+D**
+**quit, q**
     Exit the debugger, terminating the program with a clean exit status (0).
 
 Stack Navigation
 ~~~~~~~~~~~~~~~~
 
-**where, w, bt, backtrace**
+**where, w, bt**
     Display the stack trace, showing all frames from the current execution point to the top of the call stack.
 
 **up, u**
@@ -167,20 +246,6 @@ Breakpoint Management
     
     Example: ``dis main``
 
-Legacy Commands
-~~~~~~~~~~~~~~~
-
-These commands are maintained for backward compatibility:
-
-**breakpoint-module, bm**
-    Add a breakpoint for a specific module (interactive prompt).
-
-**breakpoint-function, bf**
-    Add a breakpoint for a specific function (interactive prompt).
-
-**list-modules, lm**
-    List all loaded modules starting with the module filter (default: ``pygeai``).
-
 Other Commands
 ~~~~~~~~~~~~~~
 
@@ -188,18 +253,59 @@ Other Commands
     Display a list of available commands and their descriptions.
 
 **<Python code>**
-    Execute arbitrary Python code in the current frame's context. For example, ``x = 42`` or ``print(sys.argv)``. Errors are caught and logged without crashing the debugger.
-
-**Ctrl+C**
-    Interrupt the current command input and resume execution, equivalent to ``continue``.
+    Execute arbitrary Python code in the current frame's context. For example, ``x = 42`` or ``print(sys.argv)``.
 
 Examples
 --------
 
-Example 1: Basic Debugging
+Example 1: Debug a Chat Application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create a chat application script:
+
+.. code-block:: python
+
+    # chat_app.py
+    from pygeai.chat import ChatClient
+    
+    def process_message(message):
+        client = ChatClient()
+        response = client.send_message(message)
+        return response.content
+    
+    def main():
+        msg = "Hello, AI!"
+        result = process_message(msg)
+        print(result)
+    
+    if __name__ == "__main__":
+        main()
+
+Debug it:
+
+.. code-block:: bash
+
+    # Break on process_message
+    geai-dbg -b process_message chat_app.py
+    
+    # Or with module-specific breakpoint
+    geai-dbg -b pygeai.chat:send_message chat_app.py
+
+Interactive session:
+
+.. code-block:: text
+
+    (geai-dbg) p message
+    'Hello, AI!'
+    (geai-dbg) s              # Step into send_message
+    (geai-dbg) l              # List source code
+    (geai-dbg) p self.config  # Inspect client configuration
+    (geai-dbg) c              # Continue
+
+Example 2: Debug geai CLI
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Debug the ``geai ail lrs`` command:
+Debug the ``geai`` CLI with specific arguments:
 
 .. code-block:: bash
 
@@ -209,10 +315,10 @@ Output:
 
 .. code-block:: text
 
-    2026-01-07 15:04:57,263 - geai.dbg - INFO - GEAI debugger started.
-    2026-01-07 15:04:57,264 - geai.dbg - INFO - Breakpoint added: pygeai.cli.geai:main (enabled, hits: 0)
-    2026-01-07 15:04:57,264 - geai.dbg - INFO - Setting trace and running target
-    2026-01-07 15:04:57,264 - geai.dbg - INFO - Breakpoint hit at pygeai.cli.geai.main (hit #1)
+    2026-01-14 15:04:57,263 - geai.dbg - INFO - GEAI debugger started.
+    2026-01-14 15:04:57,264 - geai.dbg - INFO - Breakpoint added: pygeai.cli.geai:main (enabled, hits: 0)
+    2026-01-14 15:04:57,264 - geai.dbg - INFO - Setting trace and running target
+    2026-01-14 15:04:57,264 - geai.dbg - INFO - Breakpoint hit at pygeai.cli.geai.main (hit #1)
     
     ============================================================
     Paused at pygeai.cli.geai.main (line 42)
@@ -227,45 +333,44 @@ Output:
        45  
     ============================================================
     Type 'h' for help, 'c' to continue
-    (geai-dbg)
-
-Example 2: Stepping Through Code
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    (geai-dbg) p sys.argv
+    ['geai', 'ail', 'lrs']
+    (geai-dbg) c
 
-At a breakpoint, step through code execution:
+Example 3: Debug with Conditional Breakpoints
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: text
+.. code-block:: python
 
-    (geai-dbg) s
-    # Steps into the next function call
+    from pygeai.dbg import debug_file
     
-    (geai-dbg) n
-    # Steps over function calls, staying in the current function
+    dbg = debug_file('process_data.py')
     
-    (geai-dbg) ret
-    # Continues until the current function returns
+    # Only break when count exceeds 1000
+    dbg.add_breakpoint(
+        function_name='process_batch',
+        condition='len(batch) > 1000'
+    )
+    
+    dbg.run()
 
-Example 3: Inspecting Variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Example 4: Debug SDK Internals
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Examine variables at a breakpoint:
+.. code-block:: bash
+
+    # Debug the CLI and inspect how commands are processed
+    geai-dbg -m pygeai.cli.geai:main -b parse_command
+
+Interactive session:
 
 .. code-block:: text
 
-    (geai-dbg) p x
-    42
-    
+    (geai-dbg) p command
     (geai-dbg) pp locals()
-    {'x': 42,
-     'y': 20,
-     'result': 62}
-    
-    (geai-dbg) args
-    Function arguments:
-      self = <pygeai.cli.geai.CLIDriver object at 0x...>
-      args = None
+    (geai-dbg) where  # See the full call stack
 
-Example 4: Stack Navigation
+Example 5: Stack Navigation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Navigate the call stack:
@@ -288,7 +393,7 @@ Navigate the call stack:
     (geai-dbg) down
     Frame #1: __main__.level_3
 
-Example 5: Breakpoint Management
+Example 6: Breakpoint Management
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Manage breakpoints during debugging:
@@ -311,21 +416,35 @@ Manage breakpoints during debugging:
     (geai-dbg) cl pygeai.core:helper_function
     Breakpoint removed: pygeai.core:helper_function
 
-Example 6: Viewing Source Code
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Example 7: Verbose Logging
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Display source code around the current line:
+Debug with verbose logging to see PyGEAI internal logs:
 
-.. code-block:: text
+.. code-block:: bash
+
+    # Enable verbose logging with DEBUG level (default)
+    geai-dbg -v my_script.py
+    
+    # Enable verbose logging with INFO level
+    geai-dbg -v --log-level INFO my_script.py
+    
+    # Enable verbose logging with ERROR level only
+    geai-dbg -v --log-level ERROR my_script.py
+
+Programmatically:
+
+.. code-block:: python
 
-    (geai-dbg) list 5
-    Source (/path/to/file.py):
-       10  def process_data(data):
-       11      result = []
-       12      for item in data:
-    ->  13          processed = helper_function(item)
-       14          result.append(processed)
-       15      return result
+    from pygeai.dbg import debug_file
+    
+    # Enable verbose logging with DEBUG level
+    dbg = debug_file('my_script.py', verbose=True)
+    dbg.run()
+    
+    # Enable verbose logging with INFO level
+    dbg = debug_file('my_script.py', verbose=True, log_level='INFO')
+    dbg.run()
 
 Advanced Features
 -----------------
@@ -333,15 +452,35 @@ Advanced Features
 Module Filtering
 ~~~~~~~~~~~~~~~~
 
-The debugger includes a performance optimization that only traces modules matching a specified prefix (default: ``pygeai``). This significantly reduces overhead compared to tracing all Python code.
+The debugger includes a performance optimization that only traces modules matching a specified prefix. This significantly reduces overhead compared to tracing all Python code.
 
-When creating a custom debugger, you can specify the module filter:
+**Automatic detection** (for file debugging):
 
-.. code-block:: python
+- Scripts without PyGEAI imports: filters to ``__main__`` only
+- Scripts with PyGEAI imports: traces all modules (empty filter)
+
+**Manual control**:
+
+.. code-block:: bash
+
+    # Only trace pygeai modules (default for geai CLI)
+    geai-dbg --filter pygeai my_script.py
+    
+    # Only trace your script
+    geai-dbg --filter __main__ my_script.py
+    
+    # Trace everything (slow!)
+    geai-dbg --trace-all my_script.py
 
-    dbg = Debugger(target=my_function, module_filter="my_package")
+Programmatically:
 
-This will only trace modules starting with ``my_package``, ignoring standard library and third-party code.
+.. code-block:: python
+
+    # Fast: only trace __main__
+    dbg = debug_file('script.py', module_filter='__main__')
+    
+    # Slower: trace pygeai and __main__
+    dbg = debug_file('script.py', module_filter='')
 
 Conditional Breakpoints
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -350,6 +489,8 @@ Breakpoints can include conditions that must be met for the breakpoint to trigge
 
 .. code-block:: python
 
+    from pygeai.dbg import Debugger
+    
     dbg = Debugger(target=my_function)
     dbg.add_breakpoint(
         module="my_module",
@@ -366,39 +507,35 @@ The debugger uses Python's ``readline`` module to provide command history and li
 
 - **Up/Down arrows**: Navigate through command history
 - **Ctrl+R**: Search command history
-- **Tab**: (if configured) Auto-completion
 
 Command history is saved to ``~/.geai_dbg_history`` and persists across debugging sessions.
 
-Programmatic Usage
-~~~~~~~~~~~~~~~~~~
+Helper Functions
+~~~~~~~~~~~~~~~~
 
-You can use the ``Debugger`` class programmatically in your own code:
+The ``pygeai.dbg`` module provides convenient helper functions:
 
-.. code-block:: python
-
-    from pygeai.dbg.debugger import Debugger, Breakpoint
-    
-    def my_target():
-        # Your code here
-        pass
-    
-    # Create debugger
-    dbg = Debugger(target=my_target, module_filter="my_package")
-    
-    # Add breakpoints
-    dbg.add_breakpoint(module="my_package.module", function_name="my_function")
-    dbg.add_breakpoint(function_name="helper", condition="x > 10")
-    
-    # List breakpoints
-    for bp in dbg.list_breakpoints():
-        print(f"Breakpoint: {bp}")
+**debug_file(filepath, args, module_filter, breakpoint_specs, verbose, log_level)**
+    Debug a Python file by executing it under the debugger.
     
-    # Run under debugger
-    dbg.run()
+    :param filepath: Path to the Python file to debug (required)
+    :param args: Command-line arguments to pass to the script (optional)
+    :param module_filter: Module prefix to trace, None auto-detects (optional)
+    :param breakpoint_specs: List of (module, function) tuples for initial breakpoints (optional)
+    :param verbose: Enable verbose logging for pygeai modules (default: False)
+    :param log_level: Log level for verbose mode: 'DEBUG', 'INFO', 'WARNING', 'ERROR' (default: 'DEBUG')
+    :return: Configured Debugger instance
+    :raises: FileNotFoundError if the file doesn't exist
+
+**debug_module(module_name, function_name, args, module_filter)**
+    Debug a specific module and function.
     
-    # Reset state for reuse
-    dbg.reset()
+    :param module_name: Fully qualified module name, e.g., 'pygeai.cli.geai' (required)
+    :param function_name: Function to call (default: 'main')
+    :param args: Command-line arguments (optional)
+    :param module_filter: Module prefix to trace (optional)
+    :return: Configured Debugger instance with automatic breakpoint
+    :raises: ImportError if module or function cannot be imported
 
 Tips and Best Practices
 -----------------------
@@ -417,27 +554,53 @@ Tips and Best Practices
 
 7. **Conditional breakpoints**: Use conditions to break only when specific criteria are met, reducing manual stepping.
 
-Notes
------
+8. **Strategic breakpoints**: Set breakpoints only where needed. Specific module:function breakpoints are faster than wildcards.
 
-- **Ctrl+D and Ctrl+C**:
-  - Pressing ``Ctrl+D`` at the ``(geai-dbg)`` prompt terminates the debugger gracefully, logging "Debugger terminated by user (EOF)." and exiting with status 0.
-  - Pressing ``Ctrl+C`` resumes execution, equivalent to the ``continue`` command.
+Performance Considerations
+--------------------------
 
-- **Python Code Execution**:
-  - Arbitrary Python code executed at the prompt runs in the context of the current frame, with access to local and global variables. Use with caution, as it can modify program state.
+**Module Filtering**
 
-- **Performance**:
-  - The debugger uses ``sys.settrace`` which has performance overhead. The module filter helps minimize this, but expect slower execution than running without the debugger.
+Module filtering defaults to sensible values:
 
-- **Breakpoint Persistence**:
-  - Breakpoints persist across ``continue`` commands but are cleared when the program exits. They are not saved to disk.
+- ``__main__`` for scripts without PyGEAI imports
+- Empty string (all modules) for scripts with PyGEAI imports
+- Inherited from module name for module debugging
 
-- **Logging**:
-  - The debugger logs to stdout with timestamps, including breakpoint hits, state changes, and errors. The log level is set to DEBUG by default.
+Users can override with ``--filter`` or ``--trace-all``.
 
-- **Frame Context**:
-  - When you move up/down the stack with ``up``/``down``, the current frame changes, affecting what ``locals``, ``globals``, and expression evaluation see.
+**Overhead**
+
+The debugger uses ``sys.settrace`` which has performance overhead. The module filter helps minimize this, but expect slower execution than running without the debugger.
+
+Troubleshooting
+---------------
+
+**Debugger Not Stopping**
+
+1. Check module filter matches your code
+2. Verify breakpoint module/function names are correct
+3. Use ``--trace-all`` to debug filtering issues
+
+**Source Code Not Available**
+
+Some modules (built-ins, compiled extensions) don't have accessible source. The debugger will notify you when source is unavailable.
+
+**Performance Issues**
+
+1. Reduce module filter scope
+2. Use specific breakpoints instead of wildcards
+3. Disable conditional breakpoints if not needed
+
+**Breakpoint not hitting**
+
+- Check that the module and function names match exactly (use ``lm`` to list loaded modules)
+- Verify the breakpoint is enabled (use ``b`` to list breakpoints)
+- Check if a condition is preventing the breakpoint from triggering
+
+**Can't see local variables**
+
+Make sure you're in the correct frame. Use ``where`` to see the stack and ``up``/``down`` to navigate.
 
 Code Examples
 -------------
@@ -445,34 +608,41 @@ Code Examples
 See the ``pygeai/tests/snippets/dbg/`` directory for complete working examples:
 
 - ``basic_debugging.py`` - Simple debugging with variable inspection
-- ``stepping_example.py`` - Demonstrates step, next, and return commands
-- ``stack_navigation.py`` - Shows stack traversal with up/down
+- ``file_debugging.py`` - Demonstrates debugging Python files
+- ``module_debugging.py`` - Shows module debugging capabilities
 - ``breakpoint_management.py`` - Examples of managing breakpoints
+- ``stack_navigation.py`` - Shows stack traversal with up/down
 
 Run these examples with:
 
 .. code-block:: bash
 
-    python -m pygeai.tests.snippets.dbg.basic_debugging
+    python pygeai/tests/snippets/dbg/basic_debugging.py
+    python pygeai/tests/snippets/dbg/file_debugging.py
+    python pygeai/tests/snippets/dbg/module_debugging.py
 
-Troubleshooting
----------------
+Notes
+-----
 
-**Debugger is too slow**
-    Adjust the ``module_filter`` to trace only the modules you care about. The default filter is ``"pygeai"``.
+- **Ctrl+D and Ctrl+C**:
+  - Pressing ``Ctrl+D`` at the ``(geai-dbg)`` prompt terminates the debugger gracefully.
+  - Pressing ``Ctrl+C`` resumes execution, equivalent to the ``continue`` command.
 
-**Breakpoint not hitting**
-    - Check that the module and function names match exactly (use ``lm`` to list loaded modules)
-    - Verify the breakpoint is enabled (use ``b`` to list breakpoints)
-    - Check if a condition is preventing the breakpoint from triggering
+- **Python Code Execution**:
+  - Arbitrary Python code executed at the prompt runs in the context of the current frame, with access to local and global variables.
 
-**Can't see local variables**
-    Make sure you're in the correct frame. Use ``where`` to see the stack and ``up``/``down`` to navigate.
+- **Breakpoint Persistence**:
+  - Breakpoints persist across ``continue`` commands but are cleared when the program exits. They are not saved to disk.
 
-**Source code not displaying**
-    The source file might not be accessible or the code might be in a compiled module. The debugger needs access to the ``.py`` source files.
+- **Logging**:
+  - The debugger logs to stdout with timestamps, including breakpoint hits, state changes, and errors.
+  - PyGEAI module logging is disabled by default. Enable it with ``-v/--verbose`` flag.
+  - When verbose mode is enabled, the log level can be controlled with ``--log-level`` (default: DEBUG).
+
+- **Frame Context**:
+  - When you move up/down the stack with ``up``/``down``, the current frame changes, affecting what ``locals``, ``globals``, and expression evaluation see.
 
-For issues or feature requests, contact the ``pygeai`` development team or file an issue on the project's GitHub repository.
+For issues or feature requests, contact the PyGEAI development team or file an issue on the project's GitHub repository.
 
 .. seealso::
 

pygeai/_docs/source/pygeai.core.common.rst

@@ -12,6 +12,14 @@ pygeai.core.common.config module
    :show-inheritance:
    :undoc-members:
 
+pygeai.core.common.constants module
+-----------------------------------
+
+.. automodule:: pygeai.core.common.constants
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 pygeai.core.common.decorators module
 ------------------------------------