ara-cli 0.1.10.5__py3-none-any.whl → 0.1.14.0__py3-none-any.whl

ara_cli/artefact_converter.py

@@ -0,0 +1,355 @@
+import os
+import logging
+from typing import Optional
+from ara_cli.prompt_handler import LLMSingleton
+from langfuse.api.resources.commons.errors import Error as LangfuseError, NotFoundError
+from ara_cli.classifier import Classifier
+from ara_cli.artefact_reader import ArtefactReader
+from ara_cli.artefact_creator import ArtefactCreator
+from ara_cli.error_handler import AraError
+from ara_cli.directory_navigator import DirectoryNavigator
+from ara_cli.artefact_deleter import ArtefactDeleter
+from ara_cli.children_contribution_updater import ChildrenContributionUpdater
+from ara_cli.artefact_models.artefact_load import artefact_from_content
+
+
+class AraArtefactConverter:
+    def __init__(self, file_system=None):
+        self.file_system = file_system or os
+        self.reader = ArtefactReader()
+        self.creator = ArtefactCreator(self.file_system)
+        self.children_updater = ChildrenContributionUpdater(self.file_system)
+
+    def convert(
+        self,
+        old_classifier: str,
+        artefact_name: str,
+        new_classifier: str,
+        merge: bool = False,
+        override: bool = False,
+        force: bool = False,
+        children_action: Optional[str] = None,
+        new_parent_classifier: Optional[str] = None,
+        new_parent_name: Optional[str] = None,
+        json_output: bool = False,
+    ):
+        self._validate_classifiers(old_classifier, new_classifier)
+
+        content = self._read_and_validate_source(artefact_name, old_classifier)
+
+        # Handle children contributions BEFORE conversion
+        if not self._handle_children_if_needed(
+            artefact_name,
+            old_classifier,
+            new_classifier,
+            force,
+            children_action,
+            new_parent_classifier,
+            new_parent_name,
+            json_output,
+        ):
+            return  # User cancelled
+
+        target_content_existing = self._resolve_target_content(
+            artefact_name, new_classifier, merge, override
+        )
+
+        self._execute_conversion(
+            old_classifier,
+            new_classifier,
+            artefact_name,
+            content,
+            target_content_existing,
+            merge,
+            override,
+        )
+
+        self._cleanup_after_conversion(old_classifier, new_classifier, artefact_name)
+
+    def _read_and_validate_source(self, artefact_name: str, classifier: str) -> str:
+        """Read source artefact and validate it can be parsed."""
+        content, artefact_info = self.reader.read_artefact_data(
+            artefact_name, classifier
+        )
+        if not content or not artefact_info:
+            raise AraError(
+                f"Artefact '{artefact_name}' of type '{classifier}' not found"
+            )
+
+        self._validate_artefact_parseable(content, artefact_name, is_source=True)
+        return content
+
+    def _validate_artefact_parseable(
+        self, content: str, artefact_name: str, is_source: bool = True
+    ) -> None:
+        """Validate that artefact content can be parsed."""
+        artefact_type = "input" if is_source else "target"
+        try:
+            artefact = artefact_from_content(content)
+            if artefact is None:
+                raise AraError(
+                    f'Invalid {artefact_type} artefact: {artefact_name}. Run "ara scan" and "ara autofix" first.'
+                )
+        except AraError:
+            raise
+        except Exception:
+            raise AraError(
+                f'Invalid {artefact_type} artefact: {artefact_name}. Run "ara scan" and "ara autofix" first.'
+            )
+
+    def _handle_children_if_needed(
+        self,
+        artefact_name: str,
+        old_classifier: str,
+        new_classifier: str,
+        force: bool,
+        children_action: Optional[str],
+        new_parent_classifier: Optional[str],
+        new_parent_name: Optional[str],
+        json_output: bool,
+    ) -> bool:
+        """Handle children contributions if classifier is changing. Returns True to continue."""
+        if old_classifier == new_classifier:
+            return True
+        return self.children_updater.update_children_contributions(
+            artefact_name,
+            old_classifier,
+            new_classifier,
+            force,
+            children_action=children_action,
+            new_parent_classifier=new_parent_classifier,
+            new_parent_name=new_parent_name,
+            json_output=json_output,
+        )
+
+    def _execute_conversion(
+        self,
+        old_classifier: str,
+        new_classifier: str,
+        artefact_name: str,
+        content: str,
+        target_content_existing: Optional[str],
+        merge: bool,
+        override: bool,
+    ) -> None:
+        """Execute the LLM conversion and write the result."""
+        target_class = self._get_target_class(new_classifier)
+
+        prompt = self._get_prompt(
+            old_classifier=old_classifier,
+            new_classifier=new_classifier,
+            artefact_name=artefact_name,
+            content=content,
+            target_content_existing=target_content_existing,
+            merge=merge,
+        )
+
+        action = "Merging" if merge and target_content_existing else "Converting"
+        print(
+            f"\n{action} '{artefact_name}' from {old_classifier} to {new_classifier}..."
+        )
+
+        converted_artefact = self._run_conversion_agent(prompt, target_class)
+        self._write_artefact(
+            new_classifier,
+            artefact_name,
+            converted_artefact.serialize(),
+            merge,
+            override,
+        )
+
+    def _cleanup_after_conversion(
+        self, old_classifier: str, new_classifier: str, artefact_name: str
+    ) -> None:
+        """Move data folder and delete old artefact after successful conversion."""
+        if old_classifier == new_classifier:
+            return
+        self._move_data_folder_content(old_classifier, new_classifier, artefact_name)
+        ArtefactDeleter(self.file_system).delete(
+            artefact_name, old_classifier, force=True
+        )
+
+    def _validate_classifiers(self, old_classifier: str, new_classifier: str):
+        if not Classifier.is_valid_classifier(old_classifier):
+            raise ValueError(f"Invalid classifier: {old_classifier}")
+        if not Classifier.is_valid_classifier(new_classifier):
+            raise ValueError(f"Invalid classifier: {new_classifier}")
+
+    def _move_data_folder_content(self, old_classifier, new_classifier, artefact_name):
+        import shutil
+
+        navigator = DirectoryNavigator()
+        navigator.navigate_to_target()
+
+        sub_directory_old = Classifier.get_sub_directory(old_classifier)
+        dir_path_old = self.file_system.path.join(
+            sub_directory_old, f"{artefact_name}.data"
+        )
+
+        sub_directory_new = Classifier.get_sub_directory(new_classifier)
+        dir_path_new = self.file_system.path.join(
+            sub_directory_new, f"{artefact_name}.data"
+        )
+
+        if self.file_system.path.exists(dir_path_old):
+            backup_folder_name = f"{artefact_name}.data.old"
+            destination_path = self.file_system.path.join(
+                dir_path_new, backup_folder_name
+            )
+
+            if not self.file_system.path.exists(dir_path_new):
+                os.makedirs(dir_path_new, exist_ok=True)
+
+            if self.file_system.path.exists(destination_path):
+                shutil.rmtree(destination_path)
+
+            try:
+                shutil.move(dir_path_old, destination_path)
+                print(f"Moved old data to {destination_path}")
+            except Exception as e:
+                print(f"Error moving data directory: {e}")
+
+    def _resolve_target_content(
+        self, artefact_name: str, new_classifier: str, merge: bool, override: bool
+    ):
+        if merge:
+            target_content_existing, _ = self.reader.read_artefact_data(
+                artefact_name, new_classifier
+            )
+            return target_content_existing
+
+        if override:
+            return None
+
+        # Check if target already exists
+        target_content, new_artefact_info = self.reader.read_artefact_data(
+            artefact_name, new_classifier
+        )
+        if new_artefact_info:
+            # Only validate if content is not None (artefact file exists and is readable)
+            if target_content is not None:
+                self._validate_artefact_parseable(
+                    target_content, artefact_name, is_source=False
+                )
+            raise ValueError(
+                f"Found already existing {new_classifier} {artefact_name}. Rerun the command with --override or --merge."
+            )
+        return None
+
+    def _get_target_class(self, new_classifier: str):
+        from ara_cli.artefact_models.artefact_mapping import artefact_type_mapping
+        from ara_cli.artefact_models.artefact_model import ArtefactType
+
+        target_type = ArtefactType(new_classifier)
+        target_class = artefact_type_mapping.get(target_type)
+
+        if not target_class:
+            raise AraError(f"No artefact class found for classifier: {new_classifier}")
+        return target_class
+
+    def _get_prompt(
+        self,
+        old_classifier,
+        new_classifier,
+        artefact_name,
+        content,
+        target_content_existing,
+        merge,
+    ):
+        try:
+            langfuse = LLMSingleton.get_instance().langfuse
+            if langfuse is None:
+                # This mimics the behavior if authentication failed or env vars missing in Singleton
+                raise Exception("Langfuse not initialized in Singleton")
+
+            if merge and target_content_existing:
+                prompt_template = langfuse.get_prompt("ara-cli/artefact-convert/merge")
+                return prompt_template.compile(
+                    old_classifier=old_classifier,
+                    new_classifier=new_classifier,
+                    artefact_name=artefact_name,
+                    content=content,
+                    target_content_existing=target_content_existing,
+                )
+            else:
+                prompt_template = langfuse.get_prompt(
+                    "ara-cli/artefact-convert/default"
+                )
+                return prompt_template.compile(
+                    old_classifier=old_classifier,
+                    new_classifier=new_classifier,
+                    artefact_name=artefact_name,
+                    content=content,
+                )
+
+        except (LangfuseError, NotFoundError, Exception) as e:
+            logging.info(f"Could not fetch Langfuse prompt: {e}. Using fallback.")
+            # Fallback prompts
+            formatting_instructions = (
+                "### Data Extraction Rules:\n"
+                "- **Users**: Extract usernames ONLY. Do NOT add '@' or 'user_' prefixes. "
+                "The system adds these automatically. (e.g., return 'hans', NOT '@user_hans').\n"
+                "- **Author**: Extract the author as 'creator_<name>'. Do NOT add the '@' symbol. "
+                "(e.g., return 'creator_unknown', NOT '@creator_unknown').\n"
+                f"- **Artefact Name**: Use strictly '{artefact_name}'.\n"
+                "- **Content**: Adapt the content to the target schema fields."
+            )
+
+            if merge and target_content_existing:
+                return (
+                    f"Merge the following {old_classifier} artefact into the existing {new_classifier} artefact. "
+                    "Combine the information from both, prioritizing the structure of the target artefact schema. "
+                    "Ensure no critical information is lost. "
+                    "\n\n"
+                    f"{formatting_instructions}"
+                    "\n\n"
+                    f"Source Artefact ({old_classifier}):\n```\n{content}\n```"
+                    f"\n\nTarget Artefact ({new_classifier}):\n```\n{target_content_existing}\n```"
+                )
+            else:
+                return (
+                    f"Convert the following {old_classifier} artefact to a {new_classifier} artefact. "
+                    "Preserve the core meaning, business value, and description. "
+                    "Map the content to the fields required by the target schema. "
+                    "\n\n"
+                    f"{formatting_instructions}"
+                    "\n\n"
+                    f"Source Artefact Content:\n```\n{content}\n```"
+                )
+
+    def _run_conversion_agent(self, prompt, target_class):
+        from ara_cli.llm_utils import create_pydantic_ai_agent
+
+        agent = create_pydantic_ai_agent(output_type=target_class, instrument=True)
+        try:
+            result = agent.run_sync(prompt)
+            return result.output
+        except Exception as e:
+            raise AraError(f"LLM conversion failed: {e}")
+
+    def _write_artefact(
+        self, new_classifier, artefact_name, artefact_content, merge, override
+    ):
+        from shutil import rmtree
+
+        navigator = DirectoryNavigator()
+        navigator.navigate_to_target()
+
+        sub_directory = Classifier.get_sub_directory(new_classifier)
+        file_path = self.file_system.path.join(
+            sub_directory, f"{artefact_name}.{new_classifier}"
+        )
+        dir_path = self.file_system.path.join(sub_directory, f"{artefact_name}.data")
+
+        if self.file_system.path.exists(file_path) and not (override or merge):
+            raise ValueError(f"Target file {file_path} already exists.")
+
+        if not merge:
+            rmtree(dir_path, ignore_errors=True)
+
+        os.makedirs(dir_path, exist_ok=True)
+
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(artefact_content)
+
+        print(f"Conversion successful. Created: {file_path}")

ara_cli/artefact_creator.py

@@ -27,11 +27,21 @@ class ArtefactCreator:
             raise ValueError("classifier must not be None or empty!")
 
         # Standard prompt log artefact
-        self._copy_template_file(dir_path, template_path, f"template.{classifier}.prompt_log.md", f"{classifier}.prompt_log.md")
+        self._copy_template_file(
+            dir_path,
+            template_path,
+            f"template.{classifier}.prompt_log.md",
+            f"{classifier}.prompt_log.md",
+        )
 
         # Additional prompt log artefact for 'feature' classifier
-        if classifier == 'feature':
-            self._copy_template_file(dir_path, template_path, "template.steps.prompt_log.md", "steps.prompt_log.md")
+        if classifier == "feature":
+            self._copy_template_file(
+                dir_path,
+                template_path,
+                "template.steps.prompt_log.md",
+                "steps.prompt_log.md",
+            )
 
     def _copy_template_file(self, dir_path, template_path, source_name, dest_name):
         source = Path(template_path) / source_name
@@ -41,7 +51,9 @@ class ArtefactCreator:
             raise FileNotFoundError(f"Source file {source} not found!")
 
         if not destination.parent.exists():
-            raise NotADirectoryError(f"Destination directory {destination.parent} does not exist!")
+            raise NotADirectoryError(
+                f"Destination directory {destination.parent} does not exist!"
+            )
 
         copyfile(source, destination)
 
@@ -59,7 +71,9 @@ class ArtefactCreator:
 
     def handle_existing_files(self, file_exists):
         if file_exists:
-            user_choice = input("File already exists. Do you want to overwrite the existing file and directory? (y/N): ")
+            user_choice = input(
+                "File already exists. Do you want to overwrite the existing file and directory? (y/N): "
+            )
             if user_choice.lower() != "y":
                 print("No changes were made to the existing file and directory.")
                 return False
@@ -68,14 +82,20 @@ class ArtefactCreator:
     def validate_template(self, template_path, classifier):
         template_name = f"template.{classifier}"
         if not self.template_exists(template_path, template_name):
-            raise FileNotFoundError(f"Template file '{template_name}' not found in the specified template path.")
+            raise FileNotFoundError(
+                f"Template file '{template_name}' not found in the specified template path."
+            )
 
-    def set_artefact_parent(self, artefact, parent_classifier, parent_file_name) -> Artefact:
-        classified_artefacts = ArtefactReader.read_artefacts()
+    def set_artefact_parent(
+        self, artefact, parent_classifier, parent_file_name
+    ) -> Artefact:
+        classified_artefacts = ArtefactReader(self.file_system).read_artefacts()
         if parent_classifier not in classified_artefacts:
             return artefact
         artefact_list = classified_artefacts[parent_classifier]
-        matching_artefacts = list(filter(lambda a: a.file_name == parent_file_name, artefact_list))
+        matching_artefacts = list(
+            filter(lambda a: a.file_name == parent_file_name, artefact_list)
+        )
         if not matching_artefacts:
             artefact_names_list = [a.file_name for a in artefact_list]
             suggest_close_name_matches(parent_file_name, artefact_names_list)
@@ -83,17 +103,23 @@ class ArtefactCreator:
         artefact._parent = matching_artefacts[0]
         return artefact
 
-    def run(self, filename, classifier, parent_classifier=None, parent_name=None, rule=None):
+    def run(
+        self, filename, classifier, parent_classifier=None, parent_name=None, rule=None
+    ):
         # make sure this function is always called from the ara top level directory
         original_directory = os.getcwd()
         navigator = DirectoryNavigator()
         navigator.navigate_to_target()
 
         if not Classifier.is_valid_classifier(classifier):
-            raise ValueError("Invalid classifier provided. Please provide a valid classifier.")
+            raise ValueError(
+                "Invalid classifier provided. Please provide a valid classifier."
+            )
 
         sub_directory = Classifier.get_sub_directory(classifier)
-        file_path = self.file_system.path.join(sub_directory, f"{filename}.{classifier}")
+        file_path = self.file_system.path.join(
+            sub_directory, f"{filename}.{classifier}"
+        )
         dir_path = self.file_system.path.join(sub_directory, f"{filename}.data")
 
         file_exists = self.file_system.path.exists(file_path)
@@ -105,9 +131,7 @@ class ArtefactCreator:
 
         if parent_classifier and parent_name:
             artefact.set_contribution(
-                artefact_name=parent_name,
-                classifier=parent_classifier,
-                rule=rule
+                artefact_name=parent_name, classifier=parent_classifier, rule=rule
             )
         else:
             artefact.set_contribution(None, None, None)
@@ -115,7 +139,7 @@ class ArtefactCreator:
         artefact_content = artefact.serialize()
         rmtree(dir_path, ignore_errors=True)
         os.makedirs(dir_path, exist_ok=True)
-        with open(file_path, 'w', encoding='utf-8') as artefact_file:
+        with open(file_path, "w", encoding="utf-8") as artefact_file:
             artefact_file.write(artefact_content)
 
         relative_file_path = os.path.relpath(file_path, original_directory)
@@ -138,6 +162,6 @@ class ArtefactCreator:
         with open(file_path, "r", encoding="utf-8") as file:
             for line in file:
                 if line.strip().startswith(title):
-                    return line.split(':')[1].strip()
+                    return line.split(":")[1].strip()
 
         raise ValueError(f"Title not found in the parent file {file_path}")

ara_cli/artefact_lister.py

@@ -28,7 +28,7 @@ class ArtefactLister:
     def list_files(
         self, tags=None, navigate_to_target=False, list_filter: ListFilter | None = None
     ):
-        artefact_list = ArtefactReader.read_artefacts(tags=tags)
+        artefact_list = ArtefactReader(self.file_system).read_artefacts(tags=tags)
         artefact_list = self.filter_artefacts(artefact_list, list_filter)
 
         filtered_artefact_list = {
@@ -54,7 +54,7 @@ class ArtefactLister:
             )
 
         artefacts_by_classifier = {classifier: []}
-        ArtefactReader.step_through_value_chain(
+        ArtefactReader(self.file_system).step_through_value_chain(
             artefact_name=artefact_name,
             classifier=classifier,
             artefacts_by_classifier=artefacts_by_classifier,
@@ -79,7 +79,7 @@ class ArtefactLister:
                 artefact_name, [info["title"] for info in artefact_info]
             )
 
-        child_artefacts = ArtefactReader.find_children(
+        child_artefacts = ArtefactReader(self.file_system).find_children(
             artefact_name=artefact_name, classifier=classifier
         )
 

ara_cli/artefact_models/artefact_model.py

@@ -185,7 +185,7 @@ class Artefact(BaseModel, ABC):
         description="Optional list of tags (0-many)",
     )
     author: Optional[str] = Field(
-        default="creator_unknown",
+        default=None,
         description="Author of the artefact, must be a single entry of the form 'creator_<someone>'."
     )
     title: str = Field(

ara_cli/artefact_models/artefact_templates.py

@@ -30,7 +30,6 @@ def _default_vision(title: str, use_default_contribution: bool) -> VisionArtefac
     )
     return VisionArtefact(
         tags=[],
-        author="creator_unknown",
         title=title,
         description="<further optional description to understand the vision, markdown capable text formatting>",
         intent=intent,
@@ -46,7 +45,6 @@ def _default_businessgoal(title: str, use_default_contribution: bool) -> Busines
     )
     return BusinessgoalArtefact(
         tags=[],
-        author="creator_unknown",
         title=title,
         description="<further optional description to understand the businessgoal, markdown capable text formatting>",
         intent=intent,
@@ -60,7 +58,6 @@ def _default_capability(title: str, use_default_contribution: bool) -> Capabilit
     )
     return CapabilityArtefact(
         tags=[],
-        author="creator_unknown",
         title=title,
         description="<further optional description to understand the capability, markdown capable text formatting>",
         intent=intent,
@@ -81,7 +78,6 @@ def _default_epic(title: str, use_default_contribution: bool) -> EpicArtefact:
     ]
     return EpicArtefact(
         tags=[],
-        author="creator_unknown",
         title=title,
         description="<further optional description to understand the epic, markdown capable text formatting>",
         intent=intent,
@@ -103,7 +99,6 @@ def _default_userstory(title: str, use_default_contribution: bool) -> UserstoryA
     ]
     return UserstoryArtefact(
         tags=[],
-        author="creator_unknown",
         title=title,
         description="<further optional description to understand the userstory, markdown capable text formatting>",
         intent=intent,
@@ -116,7 +111,6 @@ def _default_userstory(title: str, use_default_contribution: bool) -> UserstoryA
 def _default_example(title: str, use_default_contribution: bool) -> ExampleArtefact:
     return ExampleArtefact(
         tags=[],
-        author="creator_unknown",
         title=title,
         description="<further optional description to understand the example, markdown capable text formatting>",
         contribution=default_contribution() if use_default_contribution else None
@@ -137,7 +131,6 @@ def _default_keyfeature(title: str, use_default_contribution: bool) -> Keyfeatur
     AND some other result is to be expected>"""
     return KeyfeatureArtefact(
         tags=[],
-        author="creator_unknown",
         title=title,
         description=description,
         intent=intent,
@@ -193,7 +186,6 @@ def _default_feature(title: str, use_default_contribution: bool) -> FeatureArtef
 
     return FeatureArtefact(
         tags=[],
-        author="creator_unknown",
         title=title,
         description=description,
         intent=intent,
@@ -224,7 +216,6 @@ def _default_issue(title: str, use_default_contribution: bool) -> IssueArtefact:
 
     return IssueArtefact(
         tags=[],
-        author="creator_unknown",
         title=title,
         description=description,
         additional_description=additional_description,

ara_cli/artefact_models/feature_artefact_model.py

@@ -149,10 +149,10 @@ class Scenario(BaseModel):
         return steps
 
     @model_validator(mode='after')
-    def check_no_placeholders(cls, values: 'Scenario') -> 'Scenario':
+    def check_no_placeholders(self) -> 'Scenario':
         """Ensure regular scenarios don't contain placeholders that should be in scenario outlines."""
         placeholders = set()
-        for step in values.steps:
+        for step in self.steps:
             # Skip validation if step contains docstring placeholders (during parsing)
             if '__DOCSTRING_PLACEHOLDER_' in step:
                 continue
@@ -170,7 +170,7 @@ class Scenario(BaseModel):
                 f"Scenario Contains Placeholders ({placeholder_list}) but is not a Scenario Outline. "
                 f"Use 'Scenario Outline:' instead of 'Scenario:' and provide an Examples table."
             )
-        return values
+        return self
 
     @classmethod
     def from_lines(cls, lines: List[str], start_idx: int) -> Tuple['Scenario', int]:
@@ -219,18 +219,18 @@ class ScenarioOutline(BaseModel):
         return v
 
     @model_validator(mode='after')
-    def check_placeholders(cls, values: 'ScenarioOutline') -> 'ScenarioOutline':
+    def check_placeholders(self) -> 'ScenarioOutline':
         """Ensure all placeholders in steps have corresponding values in examples."""
         placeholders = set()
-        for step in values.steps:
+        for step in self.steps:
             found = re.findall(r'<([^>]+)>', step)
             placeholders.update(found)
-        for example in values.examples:
+        for example in self.examples:
             missing = placeholders - set(example.values.keys())
             if missing:
                 raise ValueError(
                     f"Example is missing values for placeholders: {missing}")
-        return values
+        return self
 
     @classmethod
     def from_lines(cls, lines: List[str], start_idx: int) -> Tuple['ScenarioOutline', int]:
@@ -298,7 +298,7 @@ class FeatureArtefact(Artefact):
     def validate_artefact_type(cls, v):
         if v != ArtefactType.feature:
             raise ValueError(
-                f"FeatureArtefact must have artefact_type of '{ArtefactType.feature}', not '{v}'")
+                f"FeatureArtefact must have artefact_type of '{ArtefactType.feature.value}', not '{v}'")
         return v
 
     @classmethod