Code Execution Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_quality/_models/flextqualitymodels_part_02.py
• src/flext_quality/utilities.py
• src/flext_quality/mcp/tools.py
• AGENTS.md
• pyproject.toml

Code Execution Integration provides a structured framework for running external scripts, shell commands, and Model Context Protocol (MCP) tools within the flext-quality environment. It enables the orchestration of quality workflows by allowing the system to invoke various runtimes such as Python, Ruff, and basedpyright to perform analysis or maintenance tasks.

The system uses typed request and result models to ensure consistent data exchange between the orchestration layer and the execution environments. This integration supports both synchronous shell commands and deferred execution requests.

Execution Architecture

The execution architecture relies on standardized models to define requests and capture results from subprocesses. The ExecutionRequest model specifies the script path, runtime environment, and arguments, while the ExecutionResult model captures the outcome, including exit codes and standard streams.

The diagram shows the flow from an execution request through the utility runner to the final result processing.
Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:490-520, src/flext_quality/utilities.py:165-180

Key Execution Models

The system uses Pydantic-based models to define the contract for code execution.

Model	Field	Type	Description
ExecutionRequest	script_path	Path	Path to the script file.
	runtime	str	Runtime identifier (e.g., 'python', 'ruff').
	args	t.StrSequence	List of command-line arguments.
	timeout_ms	int	Execution timeout in milliseconds.
ExecutionResult	success	bool	True if process exited with code 0.
	exit_code	int	The raw process return code.
	stdout	str	Captured standard output.
	stderr	str	Captured standard error.

Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:490-520

Shell Command Utility

The FlextQualityUtilities class provides a run_shell_command method to execute raw shell commands with defined timeouts. This utility converts millisecond timeouts to seconds for compatibility with underlying CLI runners and validates return codes to return a result object.

Command Execution Process

1. Input Reception: Receives a sequence of strings representing the command and a timeout in milliseconds.
2. Timeout Conversion: Divides the millisecond timeout by c.Quality.MS_TO_SECONDS_DIVISOR.
3. Process Invocation: Uses u.Cli.run_raw to execute the command.
4. Result Validation: Checks the raw_return_code. If non-zero, it returns a failure result containing stderr.
5. Output Capture: Returns the stdout on successful execution.

Sources: src/flext_quality/utilities.py:165-180

MCP Tool Integration

Code execution is exposed to external agents through Model Context Protocol (MCP) tools. The FlextQualityMcpTools class implements methods like execute_hook and search_code, which orchestrate complex workflows by calling internal managers and integration clients.

The sequence diagram illustrates how an MCP tool call triggers a hook execution that may involve running shell commands.
Sources: src/flext_quality/mcp/tools.py:73-88, src/flext_quality/utilities.py:165-180

Tool Capabilities

• Hook Execution: Manually triggers registered hooks via execute_hook.
• Semantic Search: Utilizes claude-context and claude-mem clients to build and return search commands for code and memory.
• Rule Validation: Executes a rules engine to validate code paths against defined YAML rules.

Sources: src/flext_quality/mcp/tools.py:18-105, AGENTS.md:21-25

Integration with Quality Runtimes

The system specifically targets several runtimes for quality analysis. These are configured through dependencies and utilized by CLI commands to assemble execution strings.

• Python: Primary runtime for internal scripts and pytest.
• Ruff: Used for linting and formatting operations.
• basedpyright: Handles static type checking.
• Bandit: Performs security vulnerability analysis.

Sources: pyproject.toml:30-55, AGENTS.md:30-35

Scheduled Maintenance Tasks

Maintenance tasks use the code execution framework to perform periodic operations. The MaintenanceConfig allows users to define named tasks with specific shell commands and timeouts.

The class diagram shows the relationship between maintenance configurations, task definitions, and schedule entries.
Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:35-130

Tasks are executed according to the ScheduleEntry settings, with error handling policies such as max_retries and retry_delay applied to the execution flow.
Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:65-85

Summary

Code Execution Integration serves as the bridge between high-level quality orchestration and low-level process execution. By providing typed interfaces for requests and results, and integrating with MCP tools, it allows flext-quality to maintain strict control over external analysis tools while providing a flexible environment for automated maintenance and search operations.