hbllmutils.entry.code.todo

TODO Completion Command Line Interface Module.

This module provides command line interface functionality for completing TODO comments in Python source code files using Large Language Models (LLMs). It processes Python files or directories, identifies TODO comments, and generates appropriate code completions while maintaining code quality and consistency.

The module contains the following main components:

complete_todo_for_file() - Process a single Python file to complete its TODO comments
_get_llm_task() - Create and cache LLM task instances for TODO completion
_add_todo_subcommand() - Register the ‘todo’ subcommand with the CLI

The TODO completion process includes:

Source code analysis and dependency resolution
TODO comment identification and context extraction
LLM-based code generation with validation
AST-based syntax verification
Automatic file updates with completed code

Note

This module requires an LLM model to be configured either through command-line parameters or environment variables (OPENAI_MODEL_NAME, LLM_MODEL_NAME, or MODEL_NAME).

Warning

The quality of TODO completions depends on the LLM model used. More capable models typically produce better results. Processing large directories may consume significant API quota and time.

Example:

>>> # Process a single file
>>> from hbllmutils.entry.code.todo import complete_todo_for_file
>>> complete_todo_for_file(
...     'myproject/utils.py',
...     model_name='gpt-4',
...     timeout=240
... )

>>> # Use via command line
>>> # hbllmutils code todo -i myproject/utils.py -m gpt-4
>>> # hbllmutils code todo -i myproject/ -m gpt-4 --timeout 300
>>> # hbllmutils code todo -i src/ -p max_tokens=128000 -p temperature=0.7

complete_todo_for_file

Complete TODO comments in a single Python source file using LLM.

This function processes a Python source file to identify and complete TODO comments. It uses an LLM to generate appropriate code completions based on the context of each TODO, then validates and writes the completed code back to the original file.

The completion process includes:

Loading and analyzing the source file
Extracting TODO comments and their context
Generating completions using the configured LLM
Validating generated code for syntax correctness
Updating the file with completed code

Parameters:

file (str) – Path to the Python source file to process. Must be a valid file path pointing to a .py file with TODO comments to complete.
model_name (Optional[str]) – Name of the LLM model to use for completion (e.g., ‘gpt-4’). If None, uses the default model from configuration.
timeout (int) – Timeout in seconds for LLM API requests. Defaults to 240 seconds. Increase for complex files or slower models.
extra_params (Optional[Dict[str, Union[str, int, float]]]) – Additional parameters to pass to the LLM model as a dictionary. Common parameters include max_tokens, temperature, top_p, etc. If None, uses default model parameters.
ignore_modules (Optional[Tuple[str, ...]]) – Optional tuple of module names to explicitly ignore during dependency analysis. If None, uses default ignore list.
no_ignore_modules (Optional[Tuple[str, ...]]) – Optional tuple of module names to never ignore during dependency analysis. If None, no modules are forced to include.

Returns:

None. The function modifies the input file in place.

Return type:

None

Raises:

FileNotFoundError – If the specified file does not exist
ValueError – If the file is not a valid Python source file
RuntimeError – If TODO completion fails or generated code is invalid
PermissionError – If the file cannot be written due to permission issues

Note

This function overwrites the original file with the completed code. Consider backing up important files before processing.

Warning

The function uses max_retries=0, meaning it will not retry on failure. Ensure stable network connectivity and sufficient API quota before processing.

Warning

Generated code is validated for syntax but not for semantic correctness. Review completed TODOs to ensure they match intended functionality.

Example:

>>> from hbllmutils.entry.code.todo import complete_todo_for_file
>>> 
>>> # Complete TODOs in a single file
>>> complete_todo_for_file('myproject/utils.py', model_name='gpt-4')

>>> # With custom timeout and parameters
>>> complete_todo_for_file(
...     'myproject/models.py',
...     model_name='gpt-4',
...     timeout=300,
...     extra_params={'max_tokens': 128000, 'temperature': 0.7}
... )

>>> # Process with default model from environment
>>> import os
>>> os.environ['OPENAI_MODEL_NAME'] = 'gpt-4'
>>> complete_todo_for_file('myproject/views.py')
>>> 
>>> # With module filtering
>>> complete_todo_for_file(
...     'myproject/data.py',
...     model_name='gpt-4',
...     ignore_modules=('numpy', 'pandas'),
...     no_ignore_modules=('myproject.core',)
... )