Add PDF to image and AI extraction support

Introduces ConvertTo-AITImage for converting PDFs to images, with automatic pdf2img installation and AI vision extraction. Updates README with usage examples, adds tests and test data for PDF extraction, and refactors prompt/context handling with new private helper functions. Bumps module version to 1.0.20.

Author: potatoqualitee

.gitignore

@@ -4,3 +4,4 @@ publish.ps1
 .vscode/settings.json
 /.claude
 nul
+Tests/pdf/immunization_page_001.png

README.md

@@ -299,6 +299,64 @@ This demonstrates what agentic CLIs do well: read complex requirements, maintain
 
 ## Advanced Usage
 
+### PDF to Structured Data Extraction
+
+Convert PDFs to images and extract structured data using AI vision:
+
+```powershell
+# Convert PDF to images and extract data as JSON
+$params = @{
+    Tool    = "Claude"
+    Prompt  = "Extract pet immunization data from this image"
+    Context = "./Tests/pdf/immunization.json"
+}
+
+Get-ChildItem ./Tests/pdf/immunization.pdf | ConvertTo-AITImage | Invoke-AITool @params
+```
+
+`ConvertTo-AITImage` automatically installs [pdf2img](https://github.com/potatoqualitee/pdf2img) on first use and converts PDFs to PNG images optimized for AI vision models. When you pass a single `.json` file as context, aitools automatically instructs the AI to return raw JSON (no markdown fences) for direct parsing with `ConvertFrom-Json`.
+
+**Free Tier Example: Extract and Write to SQL Server**
+
+Using Copilot's free tier with GPT-5-mini, you can extract structured data and write directly to a database:
+
+```powershell
+$params = @{
+    Tool    = "Copilot"
+    Model   = "gpt-5-mini"
+    Raw     = $true
+    Prompt  = "Extract data from this image as JSON matching the context schema."
+    Context = "./Tests/pdf/immunization.json"
+}
+
+Get-ChildItem ./Tests/pdf/immunization.pdf |
+    ConvertTo-AITImage |
+    Invoke-AITool @params |
+    ConvertFrom-Json |
+    Select-Object -ExpandProperty vaccinations |
+    Write-DbaDataTable -SqlInstance localhost -Database tempdb -Table vaccinations -AutoCreateTable
+```
+
+> **Tip:** Free tier models can be inconsistent. For reliable results at minimal cost, use Claude Haiku 4.5 (`claude-haiku-4-5`) at $0.33 per 1K calls - it's remarkably capable for structured extraction. GPT-5-mini is the best free option; avoid GPT-4.1 for this task.
+
+If the model returns extra data, filter the JSON objects:
+
+```powershell
+# Filter to only records containing "immunization"
+... | ConvertFrom-Json | Where-Object { $PSItem -match "immunization" }
+```
+
+```powershell
+# Pipeline-friendly: returns FileInfo objects
+$images = Get-ChildItem *.pdf | ConvertTo-AITImage
+
+# Adjust DPI for quality vs file size tradeoff
+Get-ChildItem document.pdf | ConvertTo-AITImage -DPI 300
+
+# Mix PDFs with other files using -PassThru
+Get-ChildItem ./docs | ConvertTo-AITImage -PassThru | Invoke-AITool -Prompt "Analyze these files"
+```
+
 ### Working with Images
 
 **Image Analysis and Code Generation (Codex, Claude, Gemini)**

Tests/aitools.Tests.ps1

@@ -29,7 +29,8 @@ Describe 'AITools Module Integration Tests' {
                 'Update-AITool',
                 'Uninstall-AITool',
                 'Update-PesterTest',
-                'Get-AITPrompt'
+                'Get-AITPrompt',
+                'ConvertTo-AITImage'
             )
 
             foreach ($command in $commands) {
@@ -257,6 +258,78 @@ function Get-TestData {
         }
     }
 
+    Context 'ConvertTo-AITImage' {
+        BeforeAll {
+            $script:pdfPath = Join-Path $PSScriptRoot 'pdf' 'immunization.pdf'
+            $script:jsonSchemaPath = Join-Path $PSScriptRoot 'pdf' 'immunization.json'
+        }
+
+        It 'Should have test PDF file' {
+            Test-Path $script:pdfPath | Should -Be $true
+        }
+
+        It 'Should have JSON schema file' {
+            Test-Path $script:jsonSchemaPath | Should -Be $true
+        }
+
+        It 'Should convert PDF to PNG images' {
+            $images = Get-ChildItem $script:pdfPath | ConvertTo-AITImage
+            $images | Should -Not -BeNullOrEmpty
+            $images | ForEach-Object {
+                $_.Extension | Should -Be '.png'
+                $_.Exists | Should -Be $true
+            }
+            Write-Host "Generated $($images.Count) image(s) from PDF"
+
+            # Store for cleanup
+            $script:generatedImages = $images
+        }
+
+        It 'Should return FileInfo objects' {
+            $images = Get-ChildItem $script:pdfPath | ConvertTo-AITImage
+            $images | ForEach-Object {
+                $_ | Should -BeOfType [System.IO.FileInfo]
+            }
+        }
+
+        It 'Should extract immunization data from PDF using AI vision' {
+            $images = Get-ChildItem $script:pdfPath | ConvertTo-AITImage
+
+            $prompt = @"
+Extract the pet immunization data from this veterinary record image.
+Return ONLY valid JSON matching the schema structure provided in the context file.
+Parse all vaccination entries including vaccine names, dates administered, and veterinarian names.
+"@
+
+            $result = $images | Invoke-AITool -Tool Claude -Prompt $prompt -Context $script:jsonSchemaPath
+
+            $result | Should -Not -BeNullOrEmpty
+            $result.Success | Should -Be $true
+            $result.Result | Should -Not -BeNullOrEmpty
+
+            # Try to parse the result as JSON to verify it's valid
+            try {
+                # Extract JSON from the result (may be wrapped in markdown code blocks)
+                $jsonText = $result.Result -replace '(?s)```json\s*', '' -replace '(?s)```\s*$', ''
+                $jsonResult = $jsonText | ConvertFrom-Json
+                Write-Host "Parsed JSON with pet_name: $($jsonResult.pet_name)"
+            } catch {
+                Write-Host "Note: Result may not be pure JSON: $($result.Result.Substring(0, [Math]::Min(200, $result.Result.Length)))"
+            }
+
+            Write-Host "AI extraction completed successfully"
+        }
+
+        AfterAll {
+            # Clean up generated images
+            if ($script:generatedImages) {
+                $script:generatedImages | Remove-Item -Force -ErrorAction SilentlyContinue
+            }
+            # Also clean up any leftover images from the PDF directory
+            $pdfDir = Split-Path $script:pdfPath -Parent
+            Get-ChildItem -Path $pdfDir -Filter '*.png' -ErrorAction SilentlyContinue | Remove-Item -Force -ErrorAction SilentlyContinue
+        }
+    }
 }
 
 AfterAll {

Tests/pdf/immunization.json

@@ -0,0 +1,65 @@
+{
+    "name": "pet",
+    "strict": true,
+    "schema": {
+        "type": "object",
+        "properties": {
+            "pet_name": {
+                "type": "string",
+                "description": "What is the name of the pet?"
+            },
+            "owner_name": {
+                "type": "string",
+                "description": "What is the name of the pet's owner?"
+            },
+            "pet_breed": {
+                "type": "string",
+                "description": "What is the breed of the pet?"
+            },
+            "vaccinations": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "vaccine_name": {
+                            "type": "string",
+                            "description": "What is the name of the vaccine administered?"
+                        },
+                        "date_administered_1": {
+                            "type": "string",
+                            "description": "When was the first dose of the vaccine administered?"
+                        },
+                        "date_administered_2": {
+                            "type": "string",
+                            "description": "When was the second dose of the vaccine administered?"
+                        },
+                        "date_administered_3": {
+                            "type": "string",
+                            "description": "When was the third dose of the vaccine administered?"
+                        },
+                        "veterinarian": {
+                            "type": "string",
+                            "description": "Who is the veterinarian that administered the first dose?"
+                        }
+                    },
+                    "required": [
+                        "vaccine_name",
+                        "date_administered_1",
+                        "date_administered_2",
+                        "date_administered_3",
+                        "veterinarian"
+                    ],
+                    "additionalProperties": false
+                },
+                "description": "What vaccinations were given to the pet, including the vaccine names, administration dates, and veterinarian names?"
+            }
+        },
+        "required": [
+            "pet_name",
+            "owner_name",
+            "pet_breed",
+            "vaccinations"
+        ],
+        "additionalProperties": false
+    }
+}

Tests/pdf/immunization.pdf

@@ -9,7 +9,7 @@
     RootModule        = 'aitools.psm1'
 
     # Version number of this module.
-    ModuleVersion     = '1.0.15'
+    ModuleVersion     = '1.0.20'
 
     # ID used to uniquely identify this module
     GUID              = 'c90f5001-c492-4fbe-8ab3-f03599951bd0'
@@ -18,7 +18,7 @@
     Author            = 'Chrissy LeMaire'
 
     # Copyright statement for this module
-    Copyright         = '2025 Chrissy LeMaire'
+    Copyright         = '2026 Chrissy LeMaire'
 
     # Description of the functionality provided by this module
     Description       = 'PowerShell wrapper for AI coding assistants. Batch process files using Claude Code, Aider, Gemini CLI, GitHub Copilot CLI, and Codex CLI with unified commands and pipeline support.'
@@ -38,6 +38,7 @@
     # Public functions
     FunctionsToExport = @(
         'Clear-AIToolConfig',
+        'ConvertTo-AITImage',
         'Get-AITool',
         'Get-AIToolConfig',
         'Get-AITPrompt',

aitools.psd1

@@ -286,6 +286,7 @@ Register-PSFTeppArgumentCompleter -Command Get-AITPrompt -Parameter Name -Name P
 
 $exportedFunctions = @(
     'Clear-AIToolConfig',
+    'ConvertTo-AITImage',
     'Get-AITool',
     'Get-AIToolConfig',
     'Get-AITPrompt',