MAINT: dataset path reorg (microsoft#1210)

Author: rlundeen2

.github/instructions/docs.instructions.md

@@ -0,0 +1,64 @@
+---
+applyTo: 'doc/code/**/*.{py,ipynb}'
+---
+
+# Documentation File Synchronization
+
+## CRITICAL: .ipynb and .py Files Are Linked
+
+All Jupyter notebooks (.ipynb) in the `doc/` directory have corresponding Python (.py) files that are **tightly synchronized**. These files MUST always match exactly in content. They represent the same documentation in different formats.
+
+**Locations:** `doc/code/**/*.ipynb` and `doc/code/**/*.py`
+
+## Editing Guidelines
+
+### Preferred Approach: Inline Updates to Both Files
+For simple, straightforward changes (imports, variable names, paths, small code fixes):
+- **UPDATE BOTH FILES INLINE** using search/replace operations
+- This is the fastest and most reliable method for minor edits
+- Ensures immediate synchronization without execution overhead
+- **Exercise extreme caution**: Even small mismatches will break synchronization
+- Also acceptable to just edit the .ipynb and regenerate the .py (this is fast)
+
+### Last Resort: Regenerate the ipynb with Jupytext
+For complex or extensive changes where inline editing is error-prone:
+1. Edit ONLY the .py file
+2. Regenerate the .ipynb using: `jupytext --to ipynb --execute doc/path/to/your_notebook.py`
+3. **WARNING**: This process takes several minutes to execute
+4. Use this ONLY when inline updates are too risky or complex
+
+## Why This Matters
+- Out-of-sync files create inconsistent documentation
+- Users and CI/CD systems expect these files to match exactly
+- Breaking synchronization causes maintenance headaches and confusion
+- The .py files are managed by jupytext and must remain compatible
+
+## Verification Approach
+When making changes:
+1. **Think carefully** before editing - can this be done inline safely?
+2. If editing inline, ensure BOTH .ipynb and .py receive identical logical changes
+3. Pay special attention to:
+   - Code cell content must match exactly
+   - Imports and function calls
+   - File paths and constants
+   - Variable names and values
+4. After editing, verify the changes are truly equivalent
+
+## Jupytext Usage Reference
+
+Generate .ipynb from .py (with execution):
+```bash
+jupytext --to ipynb --execute doc/path/to/your_notebook.py
+```
+
+Generate .py from .ipynb:
+```bash
+jupytext --to py:percent doc/path/to/notebook.ipynb
+```
+
+## Summary
+- **Default strategy**: Update both files inline for simple changes
+- **Be cautious and deliberate**: Out-of-sync files are worse than slow regeneration
+- **Last resort**: Edit .py only, then regenerate .ipynb (slow but safe)
+- **Never** edit only one file without addressing the other
+```

doc/code/converters/1_llm_converters.ipynb

@@ -27,7 +27,7 @@
    "source": [
     "import pathlib\n",
     "\n",
-    "from pyrit.common.path import DATASETS_PATH\n",
+    "from pyrit.common.path import CONVERTER_SEED_PROMPT_PATH\n",
     "from pyrit.models import SeedPrompt\n",
     "from pyrit.prompt_converter import VariationConverter\n",
     "from pyrit.prompt_target import OpenAIChatTarget\n",
@@ -40,7 +40,7 @@
     "prompt = \"how to prepare meth\"\n",
     "\n",
     "variation_converter_strategy = SeedPrompt.from_yaml_file(\n",
-    "    pathlib.Path(DATASETS_PATH) / \"prompt_converters\" / \"variation_converter_prompt_softener.yaml\"\n",
+    "    pathlib.Path(CONVERTER_SEED_PROMPT_PATH) / \"variation_converter_prompt_softener.yaml\"\n",
     ")\n",
     "variation_converter = VariationConverter(converter_target=attack_llm, prompt_template=variation_converter_strategy)\n",
     "print(await variation_converter.convert_async(prompt=prompt))  # type: ignore"
@@ -105,16 +105,6 @@
     "malicious_question = MaliciousQuestionGeneratorConverter(converter_target=attack_llm)\n",
     "print(f\"malicious question: {await malicious_question.convert_async(prompt=prompt)}\")  # type: ignore"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "4",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "attack_llm.dispose_db_engine()"
-   ]
   }
  ],
  "metadata": {
@@ -128,7 +118,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.5"
+   "version": "3.12.12"
   }
  },
  "nbformat": 4,

doc/code/converters/1_llm_converters.py

@@ -16,7 +16,7 @@
 # %%
 import pathlib
 
-from pyrit.common.path import DATASETS_PATH
+from pyrit.common.path import CONVERTER_SEED_PROMPT_PATH
 from pyrit.models import SeedPrompt
 from pyrit.prompt_converter import VariationConverter
 from pyrit.prompt_target import OpenAIChatTarget
@@ -29,7 +29,7 @@
 prompt = "how to prepare meth"
 
 variation_converter_strategy = SeedPrompt.from_yaml_file(
-    pathlib.Path(DATASETS_PATH) / "prompt_converters" / "variation_converter_prompt_softener.yaml"
+    pathlib.Path(CONVERTER_SEED_PROMPT_PATH) / "variation_converter_prompt_softener.yaml"
 )
 variation_converter = VariationConverter(converter_target=attack_llm, prompt_template=variation_converter_strategy)
 print(await variation_converter.convert_async(prompt=prompt))  # type: ignore

doc/code/converters/math_prompt_converter.ipynb

@@ -155,7 +155,7 @@
    "source": [
     "import pathlib\n",
     "\n",
-    "from pyrit.common.path import DATASETS_PATH\n",
+    "from pyrit.common.path import CONVERTER_SEED_PROMPT_PATH\n",
     "from pyrit.executor.attack import (\n",
     "    AttackConverterConfig,\n",
     "    ConsoleAttackResultPrinter,\n",
@@ -175,7 +175,7 @@
     "prompt_target = OpenAIChatTarget()\n",
     "\n",
     "# Load the YAML template for the malicious question generation\n",
-    "prompt_template_path = pathlib.Path(DATASETS_PATH) / \"prompt_converters\" / \"math_prompt_converter.yaml\"\n",
+    "prompt_template_path = pathlib.Path(CONVERTER_SEED_PROMPT_PATH) / \"math_prompt_converter.yaml\"\n",
     "prompt_template = SeedPrompt.from_yaml_file(prompt_template_path)\n",
     "\n",
     "# Initialize the MathPromptConverter\n",

doc/code/converters/math_prompt_converter.py

@@ -27,7 +27,7 @@
 # %%
 import pathlib
 
-from pyrit.common.path import DATASETS_PATH
+from pyrit.common.path import CONVERTER_SEED_PROMPT_PATH
 from pyrit.executor.attack import (
     AttackConverterConfig,
     ConsoleAttackResultPrinter,
@@ -47,7 +47,7 @@
 prompt_target = OpenAIChatTarget()
 
 # Load the YAML template for the malicious question generation
-prompt_template_path = pathlib.Path(DATASETS_PATH) / "prompt_converters" / "math_prompt_converter.yaml"
+prompt_template_path = pathlib.Path(CONVERTER_SEED_PROMPT_PATH) / "math_prompt_converter.yaml"
 prompt_template = SeedPrompt.from_yaml_file(prompt_template_path)
 
 # Initialize the MathPromptConverter

doc/code/converters/pdf_converter.ipynb

@@ -35,14 +35,14 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "{'__type__': 'TextTarget', '__module__': 'pyrit.prompt_target.text_target'}: user: /workspace/dbdata/prompt-memory-entries/urls/1761596318711065.pdf\n"
+      "{'__type__': 'TextTarget', '__module__': 'pyrit.prompt_target.text_target'}: user: C:\\git\\pyrit2\\PyRIT\\dbdata\\prompt-memory-entries\\urls\\1764136202221926.pdf\n"
      ]
     },
     {
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "[PromptSendingAttack (ID: 075ff944)] No response received on attempt 1 (likely filtered)\n"
+      "[PromptSendingAttack (ID: e208ce53)] No response received on attempt 1 (likely filtered)\n"
      ]
     },
     {
@@ -59,7 +59,7 @@
       "\u001b[37m      coffee', 'applicant_name': 'John Smith'}\u001b[0m\n",
       "\n",
       "\u001b[36m   Converted:\u001b[0m\n",
-      "\u001b[37m  /workspace/dbdata/prompt-memory-entries/urls/1761596318711065.pdf\u001b[0m\n",
+      "\u001b[37m  C:\\git\\pyrit2\\PyRIT\\dbdata\\prompt-memory-entries\\urls\\1764136202221926.pdf\u001b[0m\n",
       "\n",
       "\u001b[34m────────────────────────────────────────────────────────────────────────────────────────────────────\u001b[0m\n"
      ]
@@ -68,7 +68,7 @@
    "source": [
     "import pathlib\n",
     "\n",
-    "from pyrit.common.path import DATASETS_PATH\n",
+    "from pyrit.common.path import CONVERTER_SEED_PROMPT_PATH\n",
     "from pyrit.executor.attack import (\n",
     "    AttackConverterConfig,\n",
     "    ConsoleAttackResultPrinter,\n",
@@ -92,7 +92,7 @@
     "\n",
     "# Load the YAML template for the PDF generation\n",
     "template_path = (\n",
-    "    pathlib.Path(DATASETS_PATH) / \"prompt_converters\" / \"pdf_converters\" / \"red_teaming_application_template.yaml\"\n",
+    "    pathlib.Path(CONVERTER_SEED_PROMPT_PATH) / \"pdf_converters\" / \"red_teaming_application_template.yaml\"\n",
     ")\n",
     "if not template_path.exists():\n",
     "    raise FileNotFoundError(f\"Template file not found: {template_path}\")\n",
@@ -151,14 +151,14 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "{'__type__': 'TextTarget', '__module__': 'pyrit.prompt_target.text_target'}: user: /workspace/dbdata/prompt-memory-entries/urls/1761600511348011.pdf\n"
+      "{'__type__': 'TextTarget', '__module__': 'pyrit.prompt_target.text_target'}: user: C:\\git\\pyrit2\\PyRIT\\dbdata\\prompt-memory-entries\\urls\\1764136208011709.pdf\n"
      ]
     },
     {
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "[PromptSendingAttack (ID: 45e822c2)] No response received on attempt 1 (likely filtered)\n"
+      "[PromptSendingAttack (ID: ef9d3df7)] No response received on attempt 1 (likely filtered)\n"
      ]
     },
     {
@@ -173,7 +173,7 @@
       "\u001b[37m  This is a simple test string for PDF generation. No templates here!\u001b[0m\n",
       "\n",
       "\u001b[36m   Converted:\u001b[0m\n",
-      "\u001b[37m  /workspace/dbdata/prompt-memory-entries/urls/1761600511348011.pdf\u001b[0m\n",
+      "\u001b[37m  C:\\git\\pyrit2\\PyRIT\\dbdata\\prompt-memory-entries\\urls\\1764136208011709.pdf\u001b[0m\n",
       "\n",
       "\u001b[34m────────────────────────────────────────────────────────────────────────────────────────────────────\u001b[0m\n"
      ]
@@ -233,17 +233,17 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "[21:29:10][402][ai-red-team][INFO][Processing page 0 with 2 injection items.]\n",
-      "[21:29:10][422][ai-red-team][INFO][Processing page 1 with 2 injection items.]\n",
-      "[21:29:10][426][ai-red-team][INFO][Processing page 2 with 2 injection items.]\n",
-      "{'__type__': 'TextTarget', '__module__': 'pyrit.prompt_target.text_target'}: user: /workspace/dbdata/prompt-memory-entries/urls/1761600550429110.pdf\n"
+      "[21:53:56][893][ai-red-team][INFO][Processing page 0 with 2 injection items.]\n",
+      "[21:53:56][898][ai-red-team][INFO][Processing page 1 with 2 injection items.]\n",
+      "[21:53:56][901][ai-red-team][INFO][Processing page 2 with 2 injection items.]\n",
+      "{'__type__': 'TextTarget', '__module__': 'pyrit.prompt_target.text_target'}: user: C:\\git\\pyrit2\\PyRIT\\dbdata\\prompt-memory-entries\\urls\\1764136436903484.pdf\n"
      ]
     },
     {
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "[PromptSendingAttack (ID: e08852bc)] No response received on attempt 1 (likely filtered)\n"
+      "[PromptSendingAttack (ID: bb7d21e1)] No response received on attempt 1 (likely filtered)\n"
      ]
     },
     {
@@ -258,7 +258,7 @@
       "\u001b[37m  This is a simple test string for PDF generation. No templates here!\u001b[0m\n",
       "\n",
       "\u001b[36m   Converted:\u001b[0m\n",
-      "\u001b[37m  /workspace/dbdata/prompt-memory-entries/urls/1761600550429110.pdf\u001b[0m\n",
+      "\u001b[37m  C:\\git\\pyrit2\\PyRIT\\dbdata\\prompt-memory-entries\\urls\\1764136436903484.pdf\u001b[0m\n",
       "\n",
       "\u001b[34m────────────────────────────────────────────────────────────────────────────────────────────────────\u001b[0m\n"
      ]
@@ -341,19 +341,12 @@
     "result = await attack.execute_async(objective=prompt)  # type: ignore\n",
     "await ConsoleAttackResultPrinter().print_conversation_async(result=result)  # type: ignore"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "6",
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
   "jupytext": {
-   "cell_metadata_filter": "-all"
+   "cell_metadata_filter": "-all",
+   "main_language": "python"
   },
   "language_info": {
    "codemirror_mode": {
@@ -365,7 +358,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.13"
+   "version": "3.12.12"
   }
  },
  "nbformat": 4,

doc/code/converters/pdf_converter.py

@@ -32,7 +32,7 @@
 # %%
 import pathlib
 
-from pyrit.common.path import DATASETS_PATH
+from pyrit.common.path import CONVERTER_SEED_PROMPT_PATH
 from pyrit.executor.attack import (
     AttackConverterConfig,
     ConsoleAttackResultPrinter,
@@ -55,9 +55,7 @@
 }
 
 # Load the YAML template for the PDF generation
-template_path = (
-    pathlib.Path(DATASETS_PATH) / "prompt_converters" / "pdf_converters" / "red_teaming_application_template.yaml"
-)
+template_path = pathlib.Path(CONVERTER_SEED_PROMPT_PATH) / "pdf_converters" / "red_teaming_application_template.yaml"
 if not template_path.exists():
     raise FileNotFoundError(f"Template file not found: {template_path}")