Instruction on prepare_prompt.py script

Owner: Vadim Rudakov, rudakow.wadim@gmail.com Version: 0.3.1 Birth: 2026-01-25 Last Modified: 2026-01-30

1. Architectural Overview: The SVA Principle¶

This script prepares prompt files (“Layer 3: Prompts-as-Infrastructure”) for LLM consumption by removing metadata, stripping special characters, and converting to a YAML-like output format.

This tool is designed to transform structured prompt files into clean, readable formats suitable for copying into LLM interfaces or automated prompt injection. It supports multiple input formats with automatic detection based on file extension.

It adheres to the Smallest Viable Architecture (SVA) principle.

2. Key Capabilities & Logic¶

A. Supported Input Formats¶

The script auto-detects format from file extension:

B. Processing Operations¶

C. Math Expression Preservation¶

The script uses context-aware character stripping to preserve multiplication operators in mathematical expressions:

This ensures formulas like WRC = (E * 0.35) + (A * 0.25) remain meaningful rather than becoming WRC = (E 0.35) + (A 0.25).

Formatting characters (**bold**, `code`) are still stripped as they are visual noise for LLM consumption.

D. Output Formats¶

3. Technical Architecture¶

The script uses a handler-based architecture with format auto-detection:

4. Operational Guide¶

Configuration Reference¶

• Primary Script: tools/scripts/prepare_prompt.py

• Pre-commit Config: .pre-commit-config.yaml

• CI Config: .github/workflows/quality.yml

Command Line Interface¶

prepare_prompt.py <file> [--input-format FORMAT] [--output-format yaml|plain] [--stdin] [--verbose]

Exit Codes:

• 0 = Success

• 1 = Error (file not found, invalid format, etc.)

Manual Execution Commands¶

Run these from the repository root using uv for consistent environment resolution:

Examples¶

1. Process a prompt file (YAML-like output):

2. Extract plain text values only:

3. Process with verbose output:

5. Validation Layers¶

Layer 1: Logic Tests Pre-commit Hook¶

A meta-check ensures the script logic remains sound:

- id: test-prepare-prompt
  name: Test Prepare Prompt script
  entry: uv run --active pytest tools/tests/test_prepare_prompt.py
  language: python
  files: ^tools/(scripts/prepare_prompt\.py|scripts/paths\.py|tests/test_prepare_prompt\.py)$
  pass_filenames: false

This triggers whenever the script, its tests, or shared configuration change.

Layer 2: GitHub Action (Continuous Integration)¶

The CI pipeline in quality.yml runs the test suite when relevant files change:

prepare-prompt:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Install uv
      uses: astral-sh/setup-uv@v3
    - name: Get changed files
      id: changed
      uses: tj-actions/changed-files@v45
      with:
        files_yaml: |
          logic:
            - tools/scripts/prepare_prompt.py
            - tools/tests/test_prepare_prompt.py
            - tools/scripts/paths.py
    - name: Run Logic Tests
      if: steps.changed.outputs.logic_any_changed == 'true'
      run: uv run pytest tools/tests/test_prepare_prompt.py

6. Test Suite Documentation¶

The script is accompanied by a comprehensive test suite (test_prepare_prompt.py) that ensures reliability.

Test Classes and Coverage¶

Key Test Scenarios¶

• Format Detection: Auto-detect from extension, explicit override

• All Input Formats: JSON, YAML, TOML, Markdown, plain text

• Invalid Input: Syntax errors for each format

• Metadata Removal: Verification across all formats

• Character Stripping: Special characters removed from output

• Math Preservation: Multiplication operators preserved in formulas (E * 0.35)

• Stdin Mode: Reading from stdin with format specification

• Output Formats: Both yaml and plain output

• Error Handling: File not found, invalid format

Running the Tests¶

To run the full suite, execute from the repository root:

$ uv run pytest tools/tests/test_prepare_prompt.py