Prepare implementation scripts

VitjanZ · VitjanZ · commit cea32244ef69 · 2026-04-24T15:16:51.000+02:00
diff --git a/codeplain_REST_api.py b/codeplain_REST_api.py
@@ -143,6 +143,36 @@ def connection_check(self, client_version):
         }
         return self.post_request(endpoint_url, headers, payload, None, num_retries=0, silent=True)
 
+    def prepare_implementation(
+        self,
+        frid: str,
+        plain_source_tree: dict,
+        linked_resources: dict,
+        existing_files_content: dict,
+        memory_files_content: dict,
+        module_name: str,
+        required_modules: dict,
+        include_unittests: bool,
+        run_state: RunState,
+        prepare_implementation_script: str,
+    ) -> dict:
+        endpoint_url = f"{self.api_url}/prepare_implementation"
+        headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}
+
+        payload = {
+            "frid": frid,
+            "plain_source_tree": plain_source_tree,
+            "linked_resources": linked_resources,
+            "existing_files_content": existing_files_content,
+            "memory_files_content": memory_files_content,
+            "module_name": module_name,
+            "required_modules": required_modules,
+            "include_unittests": include_unittests,
+            "prepare_implementation_script": prepare_implementation_script,
+        }
+
+        return self.post_request(endpoint_url, headers, payload, run_state)
+
     def render_functional_requirement(
         self,
         frid: str,
@@ -154,6 +184,7 @@ def render_functional_requirement(
         required_modules: dict,
         include_unittests: bool,
         run_state: RunState,
+        implementation_information: Optional[str] = None,
     ) -> dict[str, str]:
         """
         Renders the content of a functionality based on the provided ID,
@@ -195,6 +226,9 @@ def render_functional_requirement(
             "include_unittests": include_unittests,
         }
 
+        if implementation_information is not None:
+            payload["implementation_information"] = implementation_information
+
         return self.post_request(endpoint_url, headers, payload, run_state)
 
     def fix_unittests_issue(
diff --git a/module_renderer.py b/module_renderer.py
@@ -173,6 +173,7 @@ def _build_render_context_for_module(
             unittests_script=self.args.unittests_script,
             conformance_tests_script=self.args.conformance_tests_script,
             prepare_environment_script=self.args.prepare_environment_script,
+            prepare_implementation_script=self.args.prepare_implementation_script,
             copy_build=self.args.copy_build,
             copy_conformance_tests=self.args.copy_conformance_tests,
             render_range=render_range,
diff --git a/plain2code_arguments.py b/plain2code_arguments.py
@@ -18,6 +18,7 @@
 CONFORMANCE_TESTS_SCRIPT_NAME = "conformance_tests_script"
 DEFAULT_LOG_FILE_NAME = "codeplain.log"
 PREPARE_ENVIRONMENT_SCRIPT_NAME = "prepare_environment_script"
+PREPARE_IMPLEMENTATION_SCRIPT_NAME = "prepare_implementation_script"
 
 
 def process_test_script_path(script_arg_name, config):
@@ -252,6 +253,14 @@ def create_parser():
         help="Path to a shell script that prepares the testing environment. The script should accept the source code folder path as its first argument.",
     )
 
+    parser.add_argument(
+        "--prepare-implementation-script",
+        type=str,
+        help="Path to a shell script that queries an LLM to produce additional implementation information. "
+        "The script receives a path to a file containing LLM query instructions as its first argument "
+        "and should print the LLM response to stdout.",
+    )
+
     parser.add_argument(
         "--test-script-timeout",
         type=int,
@@ -371,7 +380,7 @@ def parse_arguments():
     if args.full_plain and args.dry_run:
         parser.error("--full-plain and --dry-run are mutually exclusive")
 
-    script_arg_names = [UNIT_TESTS_SCRIPT_NAME, CONFORMANCE_TESTS_SCRIPT_NAME, PREPARE_ENVIRONMENT_SCRIPT_NAME]
+    script_arg_names = [UNIT_TESTS_SCRIPT_NAME, CONFORMANCE_TESTS_SCRIPT_NAME, PREPARE_ENVIRONMENT_SCRIPT_NAME, PREPARE_IMPLEMENTATION_SCRIPT_NAME]
     for script_name in script_arg_names:
         args = process_test_script_path(script_name, args)
 
diff --git a/render_machine/actions/prepare_implementation_information.py b/render_machine/actions/prepare_implementation_information.py
@@ -0,0 +1,77 @@
+import os
+import tempfile
+from typing import Any
+
+import render_machine.render_utils as render_utils
+from memory_management import MemoryManager
+from plain2code_console import console
+from render_machine.actions.base_action import BaseAction
+from render_machine.implementation_code_helpers import ImplementationCodeHelpers
+from render_machine.render_context import RenderContext
+from render_machine.render_types import RenderError
+
+
+class PrepareImplementationInformation(BaseAction):
+    SUCCESSFUL_OUTCOME = "implementation_information_prepared"
+    FAILED_OUTCOME = "implementation_information_preparation_failed"
+
+    def execute(self, render_context: RenderContext, _previous_action_payload: Any | None):
+        if render_context.verbose:
+            console.info(
+                f"Running prepare_implementation_script {render_context.prepare_implementation_script} "
+                f"for FRID {render_context.frid_context.frid}."
+            )
+
+        _, existing_files_content = ImplementationCodeHelpers.fetch_existing_files(render_context.build_folder)
+        _, memory_files_content = MemoryManager.fetch_memory_files(render_context.memory_manager.memory_folder)
+
+        with open(render_context.prepare_implementation_script, "r", encoding="utf-8") as f:
+            prepare_implementation_script_content = f.read()
+
+        api_response = render_context.codeplain_api.prepare_implementation(
+            frid=render_context.frid_context.frid,
+            plain_source_tree=render_context.plain_source_tree,
+            linked_resources=render_context.frid_context.linked_resources,
+            existing_files_content=existing_files_content,
+            memory_files_content=memory_files_content,
+            module_name=render_context.module_name,
+            required_modules=render_context.get_required_modules_functionalities(),
+            include_unittests=render_context.should_run_unit_tests(),
+            run_state=render_context.run_state,
+            prepare_implementation_script=prepare_implementation_script_content,
+        )
+        instructions = api_response.get("instructions", "")
+
+        tmp_path = None
+        try:
+            with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False, encoding="utf-8") as tmp:
+                tmp.write(instructions)
+                tmp_path = tmp.name
+
+            exit_code, implementation_information, script_output_path = render_utils.execute_script(
+                render_context.prepare_implementation_script,
+                [tmp_path],
+                render_context.verbose,
+                "Prepare Implementation Information",
+                timeout=render_context.test_script_timeout,
+                stop_event=render_context.stop_event,
+            )
+        finally:
+            if tmp_path and os.path.exists(tmp_path):
+                os.unlink(tmp_path)
+
+        if exit_code == 0:
+            render_context.frid_context.implementation_information = implementation_information
+            render_context.script_execution_history.latest_prepare_implementation_output_path = script_output_path
+            render_context.script_execution_history.should_update_script_outputs = True
+            return self.SUCCESSFUL_OUTCOME, None
+        else:
+            return (
+                self.FAILED_OUTCOME,
+                RenderError.encode(
+                    message="Prepare implementation information failed. Please check the prepare_implementation_script.",
+                    error_type="PREPARE_IMPLEMENTATION_ERROR",
+                    exit_code=exit_code,
+                    script=render_context.prepare_implementation_script,
+                ).to_payload(),
+            )
diff --git a/render_machine/actions/render_functional_requirement.py b/render_machine/actions/render_functional_requirement.py
@@ -50,6 +50,7 @@ def execute(self, render_context: RenderContext, _previous_action_payload: Any |
                 render_context.get_required_modules_functionalities(),
                 render_context.should_run_unit_tests(),
                 render_context.run_state,
+                implementation_information=render_context.frid_context.implementation_information,
             )
         except FunctionalRequirementTooComplex as e:
             error_message = f"The functionality:\n{render_context.frid_context.functional_requirement_text}\n is too complex to be implemented. Please break down the functionality into smaller parts ({str(e)})."
diff --git a/render_machine/render_context.py b/render_machine/render_context.py
@@ -44,6 +44,7 @@ def __init__(
         unittests_script: str,
         conformance_tests_script: str,
         prepare_environment_script: str,
+        prepare_implementation_script: str,
         copy_build: bool,
         copy_conformance_tests: bool,
         render_range: list[str] | None,
@@ -69,6 +70,7 @@ def __init__(
         self.unittests_script = unittests_script
         self.conformance_tests_script = conformance_tests_script
         self.prepare_environment_script = prepare_environment_script
+        self.prepare_implementation_script = prepare_implementation_script
         self.copy_build = copy_build
         self.copy_conformance_tests = copy_conformance_tests
         self.render_range = render_range
@@ -344,6 +346,10 @@ def start_refactoring_code(self):
     def finish_refactoring_code(self):
         pass
 
+    def start_prepare_implementation_information(self):
+        if self.prepare_implementation_script is None:
+            self.machine.dispatch(triggers.MARK_IMPLEMENTATION_INFORMATION_PREPARED)
+
     def start_testing_environment_preparation(self):
         if (
             self.prepare_environment_script is None
diff --git a/render_machine/render_types.py b/render_machine/render_types.py
@@ -13,6 +13,7 @@ class FridContext:
     functional_requirement_render_attempts: int = 0
     changed_files: set[str] = field(default_factory=set)
     refactoring_iteration: int = 0
+    implementation_information: Optional[str] = None
 
 
 @dataclass
@@ -109,6 +110,7 @@ class ScriptExecutionHistory:
     latest_unit_test_output_path: Optional[str] = None
     latest_conformance_test_output_path: Optional[str] = None
     latest_testing_environment_output_path: Optional[str] = None
+    latest_prepare_implementation_output_path: Optional[str] = None
     should_update_script_outputs: bool = False
 
 
diff --git a/render_machine/state_machine_config.py b/render_machine/state_machine_config.py
@@ -19,6 +19,7 @@
 from render_machine.actions.fix_conformance_test import FixConformanceTest
 from render_machine.actions.fix_unit_tests import FixUnitTests
 from render_machine.actions.prepare_repositories import PrepareRepositories
+from render_machine.actions.prepare_implementation_information import PrepareImplementationInformation
 from render_machine.actions.prepare_testing_environment import PrepareTestingEnvironment
 from render_machine.actions.refactor_code import RefactorCode
 from render_machine.actions.render_conformance_tests import RenderConformanceTests
@@ -77,6 +78,7 @@ def get_action_map(self) -> Dict[str, Any]:
         """Get the mapping of states to their corresponding actions."""
         return {
             States.RENDER_INITIALISED.value: PrepareRepositories(),
+            f"{States.IMPLEMENTING_FRID.value}_{States.PREPARE_IMPLEMENTATION_INFORMATION.value}": PrepareImplementationInformation(),
             f"{States.IMPLEMENTING_FRID.value}_{States.READY_FOR_FRID_IMPLEMENTATION.value}": RenderFunctionalRequirement(),
             f"{States.IMPLEMENTING_FRID.value}_{States.PROCESSING_UNIT_TESTS.value}_{States.UNIT_TESTS_READY.value}": RunUnitTests(),
             f"{States.IMPLEMENTING_FRID.value}_{States.PROCESSING_UNIT_TESTS.value}_{States.UNIT_TESTS_FAILED.value}": FixUnitTests(),
@@ -112,6 +114,8 @@ def get_action_result_triggers_map(self) -> Dict[str, str]:
         """Get the mapping of action outcomes to state machine triggers."""
         return {
             PrepareRepositories.SUCCESSFUL_OUTCOME: triggers.START_RENDER,
+            PrepareImplementationInformation.SUCCESSFUL_OUTCOME: triggers.MARK_IMPLEMENTATION_INFORMATION_PREPARED,
+            PrepareImplementationInformation.FAILED_OUTCOME: triggers.HANDLE_ERROR,
             RenderFunctionalRequirement.SUCCESSFUL_OUTCOME: triggers.RENDER_FUNCTIONAL_REQUIREMENT,
             RenderFunctionalRequirement.FUNCTIONAL_REQUIREMENT_TOO_COMPLEX_OUTCOME: triggers.HANDLE_ERROR,
             RunUnitTests.SUCCESSFUL_OUTCOME: triggers.MARK_UNIT_TESTS_PASSED,
@@ -221,11 +225,15 @@ def get_states(self, render_context: RenderContext) -> List[Any]:
             States.RENDER_INITIALISED.value,
             {
                 "name": States.IMPLEMENTING_FRID.value,
-                "initial": States.READY_FOR_FRID_IMPLEMENTATION.value,
+                "initial": States.PREPARE_IMPLEMENTATION_INFORMATION.value,
                 "on_enter": "start_implementing_frid",
                 "on_exit": "finish_implementing_frid",
                 "children": [
                     {"name": States.STEP_COMPLETED.value, "on_exit": "finish_frid_implementation_step"},
+                    {
+                        "name": States.PREPARE_IMPLEMENTATION_INFORMATION.value,
+                        "on_enter": "start_prepare_implementation_information",
+                    },
                     {"name": States.READY_FOR_FRID_IMPLEMENTATION.value, "on_enter": "check_frid_iteration_limit"},
                     self.get_processing_unit_tests_states(UnitTestsConfig.for_implementation(render_context)),
                     refactoring_code_states,
@@ -249,6 +257,11 @@ def get_transitions(self) -> List[Dict[str, Any]]:
                 "trigger": triggers.START_RENDER,
                 "dest": States.IMPLEMENTING_FRID.value,
             },
+            {
+                "source": f"{States.IMPLEMENTING_FRID.value}_{States.PREPARE_IMPLEMENTATION_INFORMATION.value}",
+                "trigger": triggers.MARK_IMPLEMENTATION_INFORMATION_PREPARED,
+                "dest": f"{States.IMPLEMENTING_FRID.value}_{States.READY_FOR_FRID_IMPLEMENTATION.value}",
+            },
             {
                 "source": f"{States.IMPLEMENTING_FRID.value}_{States.READY_FOR_FRID_IMPLEMENTATION.value}",
                 "trigger": triggers.RENDER_FUNCTIONAL_REQUIREMENT,
diff --git a/render_machine/states.py b/render_machine/states.py
@@ -23,6 +23,7 @@ class States(Enum):
     STEP_COMPLETED = "stepCompleted"
 
     # FRID implementation states
+    PREPARE_IMPLEMENTATION_INFORMATION = "prepareImplementationInformation"
     READY_FOR_FRID_IMPLEMENTATION = "readyForFridImplementation"
     FRID_FULLY_IMPLEMENTED = "fridFullyImplemented"
 
diff --git a/render_machine/triggers.py b/render_machine/triggers.py
@@ -19,6 +19,7 @@
 START_NEW_REFACTORING_ITERATION = "start_new_refactoring_iteration"
 MARK_CONFORMANCE_TESTS_READY = "mark_conformance_tests_ready"
 MARK_TESTING_ENVIRONMENT_PREPARED = "mark_testing_environment_prepared"
+MARK_IMPLEMENTATION_INFORMATION_PREPARED = "mark_implementation_information_prepared"
 MARK_CONFORMANCE_TESTS_FAILED = "mark_conformance_tests_failed"
 MOVE_TO_NEXT_CONFORMANCE_TEST = "move_to_next_conformance_test"
 MARK_ALL_CONFORMANCE_TESTS_PASSED = "mark_all_conformance_tests_passed"

Original file line number	Diff line number	Diff line change
`@@ -50,6 +50,7 @@ def execute(self, render_context: RenderContext, _previous_action_payload: Any \|`
`50`	`50`	`render_context.get_required_modules_functionalities(),`
`51`	`51`	`render_context.should_run_unit_tests(),`
`52`	`52`	`render_context.run_state,`
	`53`	`+ implementation_information=render_context.frid_context.implementation_information,`
`53`	`54`	`)`
`54`	`55`	`except FunctionalRequirementTooComplex as e:`
`55`	`56`	`error_message = f"The functionality:\n{render_context.frid_context.functional_requirement_text}\n is too complex to be implemented. Please break down the functionality into smaller parts ({str(e)})."`