Generation Attempt

class codestral_ros2_gen.generators.generation_attempt.AttemptMetrics(attempt_time, success, final_state, tests_passed, tests_failed, tests_skipped, prompt_tokens, completion_tokens, total_tokens, error=None)[source]

Bases: object

Dataclass representing metrics for a single generation attempt.

This class stores and provides access to various performance metrics collected during a code generation attempt, including timing, success status, test results, and token usage.

Parameters:

attempt_time (float)
success (bool)
final_state (str)
tests_passed (int)
tests_failed (int)
tests_skipped (int)
prompt_tokens (int)
completion_tokens (int)
total_tokens (int)
error (str | None)

attempt_time

Total time in seconds taken for this attempt.

Type:: float

success

Final state of the attempt (True for SUCCESS, False for FAILURE).

Type:: bool

final_state

Final state of the attempt: SUCCESS or other in case of FAILURE.

Type:: str

tests_passed

Number of tests passed.

Type:: int

tests_failed

Number of tests failed.

Type:: int

tests_skipped

Number of tests skipped.

Type:: int

prompt_tokens

Number of tokens used in the prompt.

Type:: int

completion_tokens

Number of tokens used in the completion.

Type:: int

total_tokens

Total number of tokens used.

Type:: int

error

Error message if any error occurred in case of FAILURE.

Type:: Optional[str]

Internal Attributes:: _fields_order (list[str]): Internal list defining the order of fields for reports.

property as_dict: dict[str, Any]

Convert metrics to a dictionary.

Returns:: Dictionary representation of all metrics.
Return type:: dict[str, Any]

property as_series: Series

Convert metrics to a pandas Series with proper ordering.

Returns:: Series containing all metrics with field names as index.
Return type:: pd.Series

class codestral_ros2_gen.generators.generation_attempt.AttemptState(value)[source]

Bases: Enum

Enum representing valid states during a generation attempt.

This enum defines the possible states a generation attempt can be in, from initialization through success or failure.

INITIALIZE

Starting state for the attempt.

Type:: int

GENERATE

Code generation is in progress.

Type:: int

PARSE

Parsing the generated code.

Type:: int

SAVE

Saving the parsed code to disk.

Type:: int

TEST

Running tests on the saved code.

Type:: int

SUCCESS

Generation attempt succeeded.

Type:: int

FAILURE

Generation attempt failed.

Type:: int

codestral_ros2_gen.generators.generation_attempt.attempt_state(func)[source]

Decorator for methods representing a state in GenerationAttempt.

This decorator wraps methods in the GenerationAttempt class to:

Catch exceptions and set error state.
Log errors when they occur.
Transition to FAILURE state on error.

When an exception occurs in the wrapped method, the decorator sets the error message, logs the error, transitions to FAILURE state, and returns None.

Parameters:: func (Callable) – The method to wrap.
Returns:: Wrapped method with error handling and state transition logic, or None if exception occurs.
Return type:: Callable | None

Example

@attempt_state
def _some_state_method(self):
    # Method implementation that might raise an exception
    # If exception occurs, state transitions to FAILURE
    # and the decorator returns None

class codestral_ros2_gen.generators.generation_attempt.GenerationAttempt(model, config)[source]

Bases: object

A state machine that orchestrates a single generation attempt using Mistral AI.

This class handles the complete lifecycle of a code generation attempt, including:

Generating code by interacting with the Mistral client.
Parsing generated code with ROS2CodeParser.
Saving parsed code using a provided callback.
Running tests on the generated code using ROS2Runner.

The class implements a state machine pattern to manage transitions between different phases of the generation process.

Parameters:

model (MistralClient)
config (dict)

model

Instance of the Mistral client for code generation.

Type:: MistralClient

config

Configuration dictionary including generation timeout and test settings.

Type:: dict

state

Current state of the attempt.

Type:: AttemptState

previous_state

Previous state of the attempt.

Type:: Optional[AttemptState]

start_time

Timestamp when the attempt started.

Type:: float

generated_code

Raw code generated by the model.

Type:: Optional[str]

parsed_code

Parsed and optionally formatted code.

Type:: Optional[str]

usage

Model usage information.

Type:: Optional[ModelUsage]

test_counts

Tuple of test counts (passed, failed, skipped).

Type:: tuple[int, int, int]

error

Error description if the attempt failed.

Type:: Optional[str]

__init__(model, config)[source]

Initialize a GenerationAttempt.

Sets up the state machine with the given model and configuration.

Parameters:

model (MistralClient) – Mistral client instance for code generation.
config (dict) – Configuration settings including generation timeout and test settings.

run(output_path, prompt, save_callback)[source]

Run the complete generation attempt process.

Executes the full generation cycle through all states (initialize, generate, parse, save, test) and returns success status and metrics.

Parameters:

output_path (Path) – Destination file path for the generated code.
prompt (str) – The prompt to generate code from.
save_callback (Callable[[str, Path], bool]) – Function that saves the code to the specified path.

Returns:

Tuple containing success status (bool) and metrics (AttemptMetrics).

Return type:

tuple[bool, AttemptMetrics]

_initialize()[source]

Initialize the attempt by clearing errors and preparing for generation.

This method is the entry point for the state machine, resetting the error state and transitioning to the GENERATE state.

Raises:: RuntimeError – If initialization fails.

_generate(prompt)[source]

Generate code using the Mistral client.

Calls the Mistral client’s complete() method with the provided prompt and records the generated code and model usage details.

Parameters:: prompt (str) – The prompt to generate code from.
Raises:: RuntimeError – If code generation fails or times out.

_parse()[source]

Parse the generated code.

Uses ROS2CodeParser to extract and optionally format the generated code. Transitions to the SAVE state if parsing succeeds.

Raises:: RuntimeError – If parsing fails or no valid code is extracted.

_save(output_path, save_callback)[source]

Save the parsed code to a file.

Invokes the provided save_callback with the parsed code and output path. Transitions to the TEST state if saving succeeds.

Parameters:

output_path (Path) – Destination file path for the generated code.
save_callback (Callable[[str, Path], bool]) – Function that saves the code to the specified path.

Raises:

RuntimeError – If the save operation fails.

_test()[source]

Execute tests on the saved code using ROS2Runner.

Retrieves test configuration from the config and runs tests on the generated code. Transitions to SUCCESS if tests pass, or FAILURE if they fail.

Raises:: RuntimeError – If test configuration is missing or tests fail.