Refactor/rename article to attachment (#321)

* refactor: rename parameter article to attachment, change validate_doc to flag

* docs: rename article to attachment

* chore: add warning that article is missing for readme generation

* revert: remove warning that article is missing for generating readme

Author: DRMPN

README.md

@@ -36,8 +36,6 @@ It also generates advices and recommendations for the repository.
 
 OSA is currently under development, so not all features are implemented.
 
-
-
 ---
 
 ## How it works?
@@ -170,18 +168,18 @@ Run Open-Source-Advisor using the following command:
 [<img align="center" src="https://img.shields.io/badge/Pip-3776AB.svg?style={badge_style}&logo=pypi&logoColor=white" />](https://pypi.org/project/pip/)
 
 ```sh
-python -m osa_tool.run -r {repository} [--api {api}] [--base-url {base_url}] [--model {model_name}] [--article {article}] [--convert-notebooks {notebook_paths}]
+python -m osa_tool.run -r {repository} [--api {api}] [--base-url {base_url}] [--model {model_name}] [--attachment {article}] [--convert-notebooks {notebook_paths}]
 ```
 
 **Using `docker`** &nbsp;
 [<img align="center" src="https://img.shields.io/badge/Docker-2CA5E0.svg?style={badge_style}&logo=docker&logoColor=white" />](https://www.docker.com/)
 
 ```sh
-docker run --env-file .env {image-name} -r {repository} [--api {api}] [--base-url {base_url}] [--model {model_name}] [--article {article}] [--convert-notebooks {notebook_paths}]
+docker run --env-file .env {image-name} -r {repository} [--api {api}] [--base-url {base_url}] [--model {model_name}] [--attachment {article}] [--convert-notebooks {notebook_paths}]
 ```
 
-The --article option enables you to choose a README template for a repository based on an article. You can provide
-either a link to a PDF file of the article or a path to a local PDF file after the --article option. If you are using
+The --attachment option enables you to choose a README template for a repository based on an article. You can provide
+either a link to a PDF file of the article or a path to a local PDF file after the --attachment option. If you are using
 Docker, ensure that you upload the PDF file to the OSA folder before building the image, then, specify the path as
 /app/OSA/... or just use volume mounting to access the file.
 
@@ -201,7 +199,7 @@ documentation, see the [Workflow Generator README](./osa_tool/workflow/README.md
 | `--top_p`            | Nucleus sampling probability                                                        | `None`                      |
 | `--temperature`      | Sampling temperature to use for the LLM output (0 = deterministic, 1 = creative).   | `None`                      |
 | `--max_tokens`       | Maximum number of tokens the model can generate in a single response                | `None`                      |
-| `--article`          | Link to the pdf file of the article                                                 | `None`                      |
+| `--attachment`       | Path to a local PDF or .docx file, or a URL to a PDF resource                       | `None`                      |
 | `-m`, `--mode`       | Operation mode for repository processing: `basic`, `auto` (default), or `advanced`. | `auto`                      |
 | `--delete-dir`       | Enable deleting the downloaded repository after processing                          | `disabled`                  |
 | `--no-fork`          | Avoid create fork for target repository                                             | `False`                     |

docs/index.md

@@ -137,18 +137,18 @@ Run Open-Source-Advisor using the following command:
 [<img align="center" src="https://img.shields.io/badge/Pip-3776AB.svg?style={badge_style}&logo=pypi&logoColor=white" />](https://pypi.org/project/pip/)
 
 ```sh
-python -m osa_tool.run -r {repository} [--api {api}] [--base-url {base_url}] [--model {model_name}] [--article {article}]
+python -m osa_tool.run -r {repository} [--api {api}] [--base-url {base_url}] [--model {model_name}] [--attachment {article}]
 ```
 
 **Using `docker`** &nbsp;
 [<img align="center" src="https://img.shields.io/badge/Docker-2CA5E0.svg?style={badge_style}&logo=docker&logoColor=white" />](https://www.docker.com/)
 
 ```sh
-docker run --env-file .env {image-name} -r {repository} [--api {api}] [--base-url {base_url}] [--model {model_name}] [--article {article}]
+docker run --env-file .env {image-name} -r {repository} [--api {api}] [--base-url {base_url}] [--model {model_name}] [--attachment {article}]
 ```
 
-The --article option enables you to choose a README template for a repository based on an article. You can provide
-either a link to a PDF file of the article or a path to a local PDF file after the --article option. If you are using
+The --attachment option enables you to choose a README template for a repository based on an article. You can provide
+either a link to a PDF file of the article or a path to a local PDF file after the --attachment option. If you are using
 Docker, ensure that you upload the PDF file to the OSA folder before building the image, then, specify the path as
 /app/OSA/... or just use volume mounting to access the file.
 
@@ -168,7 +168,7 @@ documentation, see the [GitHub Action Workflow Generator README](../osa_tool/git
 | `--top_p`            | Nucleus sampling probability                                                        | `None`                      |
 | `--temperature`      | Sampling temperature to use for the LLM output (0 = deterministic, 1 = creative).   | `None`                      |
 | `--max_tokens`       | Maximum number of tokens the model can generate in a single response                | `None`                      |
-| `--article`          | Link to the pdf file of the article                                                 | `None`                      |
+| `--attachment`       | Path to a local PDF or .docx file, or a URL to a PDF resource                       | `None`                      |
 | `-m`, `--mode`       | Operation mode for repository processing: `basic`, `auto` (default), or `advanced`. | `auto`                      |
 | `--delete-dir`       | Enable deleting the downloaded repository after processing                          | `disabled`                  |
 | `--no-fork`          | Avoid create fork for target repository                                             | `False`                     |

osa_tool/config/settings/arguments.yaml

@@ -72,14 +72,14 @@ top_p:
   description: "Nucleus sampling probability (1.0 = all tokens considered)."
   example: 0.8, 0.95
 
-article:
-  aliases: [ "--article" ]
+attachment:
+  aliases: [ "--attachment" ]
   type: str
   description: |
-    Select a README template for a repository with an article.
-    Or provide a link to the pdf file.
+    Path to a local PDF file (for articles) or .docx file (for documents). 
+    Alternatively, accept a publicly accessible HTTP/HTTPS URL pointing to a PDF resource.
   const: ""
-  example: "path/to/file"
+  example: path/to/document.docx, "https://example.com/article.pdf"
 
 translate_dirs:
   aliases: [ "--translate-dirs" ]
@@ -173,10 +173,8 @@ validate_paper:
 
 validate_doc:
   aliases: ["--validate-doc"]
-  type: str
+  type: flag
   description: "Check whether the experiments proposed in an attached documentation file can be reproduced using the selected repository."
-  const: ""
-  example: "path/to/file"
 
 workflow:
   generate_workflows:

osa_tool/config/settings/config.toml

@@ -25,7 +25,7 @@ mode = "auto"
 web_mode = false
 # output = ""
 # branch = ""
-# article = ""
+# attachment = ""
 translate_dirs = false
 translate_readme = []
 # convert_notebooks = []

osa_tool/run.py

@@ -18,7 +18,7 @@
 from osa_tool.docs_generator.docs_run import generate_documentation
 from osa_tool.docs_generator.license import compile_license_file
 from osa_tool.git_agent.git_agent import GitHubAgent, GitLabAgent, GitverseAgent
-from osa_tool.logger import setup_logging, logger
+from osa_tool.logger import logger, setup_logging
 from osa_tool.organization.repo_organizer import RepoOrganizer
 from osa_tool.osatreesitter.docgen import DocGen
 from osa_tool.osatreesitter.osa_treesitter import OSA_TreeSitter
@@ -32,7 +32,12 @@
 )
 from osa_tool.translation.dir_translator import DirectoryTranslator
 from osa_tool.translation.readme_translator import ReadmeTranslator
-from osa_tool.utils import delete_repository, parse_folder_name, rich_section, osa_project_root
+from osa_tool.utils import (
+    delete_repository,
+    osa_project_root,
+    parse_folder_name,
+    rich_section,
+)
 from osa_tool.validation.doc_validator import DocValidator
 from osa_tool.validation.paper_validator import PaperValidator
 from osa_tool.validation.report_generator import (
@@ -120,9 +125,9 @@ def main():
                 git_agent.upload_report(analytics.filename, analytics.output_path)
 
         # NOTE: Must run first - switches GitHub branches
-        if path_to_doc := plan.get("validate_doc"):
+        if plan.get("validate_doc"):
             rich_section("Document validation")
-            content = DocValidator(config).validate(path_to_doc)
+            content = DocValidator(config).validate(plan.get("attachment"))
             va_re_gen = ValidationReportGenerator(config, git_agent.metadata, sourcerank)
             va_re_gen.build_pdf("Document", content)
             if create_fork:
@@ -131,7 +136,7 @@ def main():
         # NOTE: Must run first - switches GitHub branches
         if plan.get("validate_paper"):
             rich_section("Paper validation")
-            content = PaperValidator(config).validate(plan.get("article"))
+            content = PaperValidator(config).validate(plan.get("attachment"))
             va_re_gen = ValidationReportGenerator(config, git_agent.metadata, sourcerank)
             va_re_gen.build_pdf("Paper", content)
             if create_fork:
@@ -171,7 +176,7 @@ def main():
         # Readme generation
         if plan.get("readme"):
             rich_section("README generation")
-            readme_agent = ReadmeAgent(config, plan.get("article"), plan.get("refine_readme"), git_agent.metadata)
+            readme_agent = ReadmeAgent(config, plan.get("attachment"), plan.get("refine_readme"), git_agent.metadata)
             readme_agent.generate_readme()
 
         # Readme translation

osa_tool/scheduler/README.md

@@ -73,33 +73,33 @@ In **custom mode**:
 
 - A list of editable actions is displayed.
 - Available commands:
-    - `help` or `?` — displays a table with descriptions of all editable keys.
-    - `multi-bool` — enables batch editing of boolean-type keys.
-    - `done` — finishes the editing session and displays the current plan.
+  - `help` or `?` — displays a table with descriptions of all editable keys.
+  - `multi-bool` — enables batch editing of boolean-type keys.
+  - `done` — finishes the editing session and displays the current plan.
 - To edit an action, enter its name.
 - For each selected action:
-    - If it is a **boolean value** (True/False), a prompt will request setting it to:
-        - `y` — enable
-        - `n` — disable
-        - `skip` — leave unchanged
-    - If it is a **string** or **list**:
-        - A new value can be entered.
-        - Leave empty to skip.
-        - Enter `None` to explicitly disable the value.
-    - Before entering a new value, the system will display:
-        - A short description.
-        - Allowed values (if available).
-        - An example (if available).
-        - The current value.
+  - If it is a **boolean value** (True/False), a prompt will request setting it to:
+    - `y` — enable
+    - `n` — disable
+    - `skip` — leave unchanged
+  - If it is a **string** or **list**:
+    - A new value can be entered.
+    - Leave empty to skip.
+    - Enter `None` to explicitly disable the value.
+  - Before entering a new value, the system will display:
+    - A short description.
+    - Allowed values (if available).
+    - An example (if available).
+    - The current value.
 
 Once the user type `done`:
 
 - The updated tables with planned actions and inactive actions will be displayed again.
 - The program will prompt the user one more time to confirm the updated plan
 - Available options:
-    - Confirm with `y` or **Enter**
-    - Cancel with `n`
-    - Re-enter manual editing mode with `custom`
+  - Confirm with `y` or **Enter**
+  - Cancel with `n`
+  - Re-enter manual editing mode with `custom`
 
 This interactive loop continues until the user explicitly confirms or cancels the operation.
 
@@ -120,7 +120,7 @@ to the repository.
 | top_p                | `--top_p`                | str  | Nucleus sampling probability                                                                                                       | `null`                           | —                           |
 | temperature          | `--temperature`          | str  | Sampling temperature to use for the LLM output (0 = deterministic, 1 = creative).                                                  | `null`                           | —                           |
 | max_tokens           | `--max_tokens`           | str  | Maximum number of tokens the model can generate in a single response                                                               | `1500`                           | —                           |
-| article              | `--article`              | str  | README template for a repository with an article, or a link to a PDF file                                                          | `null`                           | —                           |
+| attachment           | `--attachment`           | str  | Path to a local PDF or .docx file, or a URL to a PDF resource                                                                      | `null`                           | —                           |
 | translate_dirs       | `--translate-dirs`       | flag | Enable automatic translation of directory names into English                                                                       | `false`                          | —                           |
 | convert_notebooks    | `--convert-notebooks`    | list | Convert Jupyter notebooks to `.py` format. Provide paths, or leave empty for repo directory                                        | —                                | —                           |
 | delete_dir           | `--delete-dir`           | flag | Delete the downloaded repository after processing                                                                                  | `false`                          | —                           |
@@ -132,7 +132,7 @@ to the repository.
 | report               | `--report`               | flag | Analyze the repository and generate a PDF report                                                                                   | `false`                          | —                           |
 | readme               | `--readme`               | flag | Generate a `README.md` file based on repository content                                                                            | `false`                          | —                           |
 | refine_readme        | `--refine-readme`        | flag | Enable advanced README refinement. This process requires a powerful LLM model (such as GPT-4 or equivalent) for optimal results    | `false`                          | —                           |
-| requirements         | `--requirements `        | flag | Generate or refine a requirements.txt file based on repository content.                                                            | `false`                          | —                           |
+| requirements         | `--requirements`         | flag | Generate or refine a requirements.txt file based on repository content.                                                            | `false`                          | —                           |
 | organize             | `--organize`             | flag | Organize the repository by adding standard `tests` and `examples` directories if missing                                           | `false`                          | —                           |
 | about                | `--about`                | flag | Generate About section with tags                                                                                                   | `false`                          | —                           |
 | generate_workflows   | `--generate-workflows`   | flag | Generate GitHub Action workflows for the repository                                                                                | `false`                          | —                           |
@@ -149,3 +149,5 @@ to the repository.
 | branches             | `--branches`             | list | Branches to trigger workflows on                                                                                                   | `[]`                             | —                           |
 | codecov_token        | `--codecov-token`        | flag | Use Codecov token for coverage upload                                                                                              | `false`                          | —                           |
 | include_codecov      | `--include-codecov`      | flag | Include Codecov coverage step in unit tests workflow                                                                               | `true`                           | —                           |
+| validate_paper       | `--validate-paper`       | flag | Check whether the experiments proposed in an attached research paper can be reproduced using the selected repository               | `false`                          | —                           |
+| validate_doc         | `--validate-paper`       | flag | Check whether the experiments proposed in an attached documentation file can be reproduced using the selected repository           | `false`                          | —                           |

osa_tool/validation/doc_validator.py

@@ -51,7 +51,7 @@ def _encode_image(self, image_path: str):
         with open(image_path, "rb") as image_file:
             return base64.b64encode(image_file.read()).decode("utf-8")
 
-    def validate(self, path_to_doc: str) -> str:
+    def validate(self, path_to_doc: str | None) -> str:
         """
         Validate a documentation file against the code repository.
 
@@ -61,6 +61,8 @@ def validate(self, path_to_doc: str) -> str:
         Returns:
             str: Validation result from the language model.
         """
+        if not path_to_doc:
+            raise ValueError("Document is missing! Please pass it using --attachment argument.")
         try:
             # self.describe_image("/home/ilya/OSA/docx2txt-test-dir/image19.jpeg")
             doc_info = self.process_doc(path_to_doc)

osa_tool/validation/paper_validator.py

@@ -1,8 +1,8 @@
 from osa_tool.config.settings import ConfigLoader
+from osa_tool.logger import logger
 from osa_tool.models.models import ModelHandler, ModelHandlerFactory
 from osa_tool.readmegen.context.article_content import PdfParser
 from osa_tool.readmegen.context.article_path import get_pdf_path
-from osa_tool.logger import logger
 from osa_tool.validation.code_analyzer import CodeAnalyzer
 from osa_tool.validation.prompt_builder import PromptBuilder
 
@@ -42,7 +42,7 @@ def validate(self, article: str | None) -> str:
             Exception: If an error occurs during validation.
         """
         if not article:
-            raise ValueError("Article is missing! Please pass it using --article argument.")
+            raise ValueError("Article is missing! Please pass it using --attachment argument.")
         try:
             paper_info = self.process_paper(article)
             code_files = self.code_analyzer.get_code_files()