shuttersort 0.1.0__tar.gz

shuttersort-0.1.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: shuttersort
+Version: 0.1.0
+Summary: AI-powered media folder analyzer and pruner using local Vision models
+Author-email: camiloavilacm <camiloavilacm@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/camiloavilacm/ShutterSort
+Project-URL: Repository, https://github.com/camiloavilacm/ShutterSort
+Project-URL: Issues, https://github.com/camiloavilacm/ShutterSort/issues
+Keywords: media,cleanup,ollama,vision,ai,photos,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ollama>=0.1.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: rawpy>=0.18.0
+Requires-Dist: opencv-python-headless>=4.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+
+# ShutterSort
+
+AI-powered media folder analyzer and pruner. Scan your photo libraries, get intelligent scene analysis from a local Vision model, detect duplicates, and clean up with confidence.
+
+```
+pip install shuttersort
+shuttersort
+```
+
+## What It Does
+
+| Feature | Description |
+|---------|-------------|
+| **AI Scene Analysis** | Classifies folders as landscape, portrait, event, junk, etc. using `llama3.2-vision` |
+| **Quality Scoring** | Rates each folder 1-10 based on composition, lighting, and content value |
+| **People Detection** | Counts people and describes appearances, emotions, and context |
+| **Duplicate Detection** | Finds duplicate files across folders using content hashing (first 1MB + file size) |
+| **Interactive Cleanup** | Review each folder in a Rich table, then Keep, Delete (to Trash), Open, or Skip |
+| **RAW Support** | Extracts previews from Sony ARW files using `rawpy` |
+| **Video Support** | Extracts 3 representative frames from MP4s using OpenCV |
+| **100% Local** | All AI runs locally via Ollama — no cloud, no uploads, no API keys |
+
+## Quick Install
+
+### Prerequisites
+
+1. **Python 3.10+**
+   ```bash
+   python3 --version  # Must be 3.10 or higher
+   ```
+
+2. **Ollama** installed and running
+   ```bash
+   # Install Ollama (macOS)
+   brew install ollama
+
+   # Start the Ollama service
+   ollama serve
+
+   # Pull the vision model (required)
+   ollama pull llama3.2-vision
+   ```
+
+3. **macOS Full Disk Access** (required for scanning Desktop, Downloads, Documents)
+   - Open **System Settings** → **Privacy & Security** → **Full Disk Access**
+   - Click the **+** button and add your terminal app:
+     - **Terminal.app**: `/System/Applications/Utilities/Terminal.app`
+     - **iTerm2**: `/Applications/iTerm.app`
+     - **VS Code Terminal**: `/Applications/Visual Studio Code.app`
+   - Restart your terminal after granting access
+
+   Without Full Disk Access, macOS will silently return empty results when scanning protected folders.
+
+### Install ShutterSort
+
+```bash
+pip install shuttersort
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/camiloavilacm/ShutterSort.git
+cd ShutterSort
+pip install -e .
+```
+
+## Usage
+
+### Basic Scan (Default Paths)
+
+Scans `~/Desktop`, `~/Downloads`, and `~/Documents`:
+
+```bash
+shuttersort
+```
+
+### Custom Paths
+
+```bash
+# Single path
+shuttersort --path ~/Photos
+
+# Multiple paths
+shuttersort --path ~/Photos ~/Pictures ~/ExternalDrive
+
+# Shorthand
+shuttersort -p ~/Photos
+```
+
+### Different Model
+
+```bash
+shuttersort --model llava
+shuttersort -m llava
+```
+
+### Dry Run (Preview Only)
+
+See what would be deleted without actually deleting anything:
+
+```bash
+shuttersort --dry-run
+```
+
+### Verbose Output
+
+Show detailed debug logging:
+
+```bash
+shuttersort --verbose
+shuttersort -v
+```
+
+### Non-Interactive Mode
+
+Just show the summary table without the interactive review prompts:
+
+```bash
+shuttersort --no-interactive
+```
+
+## How It Works
+
+ShutterSort uses a **three-agent architecture**:
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  LibrarianAgent │────>│  CuratorAgent   │────>│ DecisionAgent   │
+│                 │     │                 │     │                 │
+│ • Walks folders │     │ • Calls Ollama  │     │ • Rich table    │
+│ • Finds media   │     │ • Analyzes imgs │     │ • [K/D/O/S] loop│
+│ • Extracts ARW  │     │ • Scores 1-10   │     │ • AppleScript   │
+│ • Finds dupes   │     │ • Detects people│     │ • Trash to Finder│
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+1. **LibrarianAgent** walks your folders, finds all media files (JPG, PNG, ARW, MP4), extracts previews from RAW files, and detects duplicates.
+2. **CuratorAgent** sends up to 5 representative images per folder to `llama3.2-vision` and returns a structured analysis (scene type, score, people count, emotions).
+3. **DecisionAgent** presents everything in a color-coded Rich table and walks you through each folder with an interactive `[K]eep / [D]elete / [O]pen / [S]kip` loop.
+
+### Duplicate Detection
+
+Files are matched by a composite key: **MD5 hash of the first 1MB + file size**. When duplicates are found across folders, ShutterSort suggests keeping the copy in the folder with the higher AI score.
+
+### Delete Behavior (Trash vs Permanent)
+
+When you choose **Delete**, ShutterSort uses **AppleScript** to move files to the macOS Trash:
+
+```applescript
+tell application "Finder" to delete POSIX file "/path/to/file"
+```
+
+This is equivalent to right-clicking a file and selecting "Move to Trash." Files can be recovered from the Trash until you empty it. ShutterSort **never** permanently deletes files.
+
+### Temporary File Handling
+
+All extracted previews (from ARW files) and video frames (from MP4s) are saved to temporary files using Python's `tempfile` module. These are cleaned up automatically after analysis. The `gc.collect()` call after ARW processing ensures native C memory from `rawpy` is released promptly, keeping RAM usage low on 16GB machines.
+
+## Output Example
+
+```
+ShutterSort — Folder Analysis Summary
+┏━━━┳━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
+┃ # ┃ Score ┃ Scene     ┃ People ┃ Folder           ┃ Summary                           ┃ Size     ┃ Pic%   ┃ Vid%   ┃ Dupes ┃
+┡━━━╇━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
+│ 1 │ 8/10  │ landscape │ 2      │ .../vacation     │ Beautiful beach photos from vac…  │ 245.30 MB│ 100%   │ 0%     │ No    │
+│ 2 │ 2/10  │ junk      │ 0      │ .../screenshots  │ Screenshots of documents and re…  │ 12.50 MB │ 100%   │ 0%     │ Yes   │
+│ 3 │ 9/10  │ event     │ 6      │ .../family       │ Birthday party with family memb…  │ 512.00 MB│ 80%    │ 20%    │ No    │
+└───┴───────┴───────────┴────────┴──────────────────┴───────────────────────────────────┴──────────┴────────┴────────┴───────┘
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| **"No media folders found"** | Check Full Disk Access for your terminal app (see Prerequisites above) |
+| **Ollama connection refused** | Run `ollama serve` in another terminal tab |
+| **Model not found** | Run `ollama pull llama3.2-vision` |
+| **ARW files fail to process** | Ensure `rawpy` is installed: `pip install rawpy` |
+| **Slow analysis** | Large folders take longer; use `--verbose` to see progress |
+| **JSON parse errors** | The retry loop handles this automatically (up to 3 retries) |
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+Quick start for contributors:
+
+```bash
+git clone https://github.com/camiloavilacm/ShutterSort.git
+cd ShutterSort
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest -m "not integration"
+```
+
+### Branching Model
+
+- `main` — Production (auto-publishes to PyPI)
+- `develop` — Staging (auto-publishes to TestPyPI)
+- `feature/*` — Feature branches (PR → develop)
+
+### CI/CD
+
+Every PR runs lint (ruff), type checks (mypy), and tests (pytest) on Python 3.10–3.13.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

shuttersort-0.1.0/README.md

@@ -0,0 +1,210 @@
+# ShutterSort
+
+AI-powered media folder analyzer and pruner. Scan your photo libraries, get intelligent scene analysis from a local Vision model, detect duplicates, and clean up with confidence.
+
+```
+pip install shuttersort
+shuttersort
+```
+
+## What It Does
+
+| Feature | Description |
+|---------|-------------|
+| **AI Scene Analysis** | Classifies folders as landscape, portrait, event, junk, etc. using `llama3.2-vision` |
+| **Quality Scoring** | Rates each folder 1-10 based on composition, lighting, and content value |
+| **People Detection** | Counts people and describes appearances, emotions, and context |
+| **Duplicate Detection** | Finds duplicate files across folders using content hashing (first 1MB + file size) |
+| **Interactive Cleanup** | Review each folder in a Rich table, then Keep, Delete (to Trash), Open, or Skip |
+| **RAW Support** | Extracts previews from Sony ARW files using `rawpy` |
+| **Video Support** | Extracts 3 representative frames from MP4s using OpenCV |
+| **100% Local** | All AI runs locally via Ollama — no cloud, no uploads, no API keys |
+
+## Quick Install
+
+### Prerequisites
+
+1. **Python 3.10+**
+   ```bash
+   python3 --version  # Must be 3.10 or higher
+   ```
+
+2. **Ollama** installed and running
+   ```bash
+   # Install Ollama (macOS)
+   brew install ollama
+
+   # Start the Ollama service
+   ollama serve
+
+   # Pull the vision model (required)
+   ollama pull llama3.2-vision
+   ```
+
+3. **macOS Full Disk Access** (required for scanning Desktop, Downloads, Documents)
+   - Open **System Settings** → **Privacy & Security** → **Full Disk Access**
+   - Click the **+** button and add your terminal app:
+     - **Terminal.app**: `/System/Applications/Utilities/Terminal.app`
+     - **iTerm2**: `/Applications/iTerm.app`
+     - **VS Code Terminal**: `/Applications/Visual Studio Code.app`
+   - Restart your terminal after granting access
+
+   Without Full Disk Access, macOS will silently return empty results when scanning protected folders.
+
+### Install ShutterSort
+
+```bash
+pip install shuttersort
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/camiloavilacm/ShutterSort.git
+cd ShutterSort
+pip install -e .
+```
+
+## Usage
+
+### Basic Scan (Default Paths)
+
+Scans `~/Desktop`, `~/Downloads`, and `~/Documents`:
+
+```bash
+shuttersort
+```
+
+### Custom Paths
+
+```bash
+# Single path
+shuttersort --path ~/Photos
+
+# Multiple paths
+shuttersort --path ~/Photos ~/Pictures ~/ExternalDrive
+
+# Shorthand
+shuttersort -p ~/Photos
+```
+
+### Different Model
+
+```bash
+shuttersort --model llava
+shuttersort -m llava
+```
+
+### Dry Run (Preview Only)
+
+See what would be deleted without actually deleting anything:
+
+```bash
+shuttersort --dry-run
+```
+
+### Verbose Output
+
+Show detailed debug logging:
+
+```bash
+shuttersort --verbose
+shuttersort -v
+```
+
+### Non-Interactive Mode
+
+Just show the summary table without the interactive review prompts:
+
+```bash
+shuttersort --no-interactive
+```
+
+## How It Works
+
+ShutterSort uses a **three-agent architecture**:
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  LibrarianAgent │────>│  CuratorAgent   │────>│ DecisionAgent   │
+│                 │     │                 │     │                 │
+│ • Walks folders │     │ • Calls Ollama  │     │ • Rich table    │
+│ • Finds media   │     │ • Analyzes imgs │     │ • [K/D/O/S] loop│
+│ • Extracts ARW  │     │ • Scores 1-10   │     │ • AppleScript   │
+│ • Finds dupes   │     │ • Detects people│     │ • Trash to Finder│
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+1. **LibrarianAgent** walks your folders, finds all media files (JPG, PNG, ARW, MP4), extracts previews from RAW files, and detects duplicates.
+2. **CuratorAgent** sends up to 5 representative images per folder to `llama3.2-vision` and returns a structured analysis (scene type, score, people count, emotions).
+3. **DecisionAgent** presents everything in a color-coded Rich table and walks you through each folder with an interactive `[K]eep / [D]elete / [O]pen / [S]kip` loop.
+
+### Duplicate Detection
+
+Files are matched by a composite key: **MD5 hash of the first 1MB + file size**. When duplicates are found across folders, ShutterSort suggests keeping the copy in the folder with the higher AI score.
+
+### Delete Behavior (Trash vs Permanent)
+
+When you choose **Delete**, ShutterSort uses **AppleScript** to move files to the macOS Trash:
+
+```applescript
+tell application "Finder" to delete POSIX file "/path/to/file"
+```
+
+This is equivalent to right-clicking a file and selecting "Move to Trash." Files can be recovered from the Trash until you empty it. ShutterSort **never** permanently deletes files.
+
+### Temporary File Handling
+
+All extracted previews (from ARW files) and video frames (from MP4s) are saved to temporary files using Python's `tempfile` module. These are cleaned up automatically after analysis. The `gc.collect()` call after ARW processing ensures native C memory from `rawpy` is released promptly, keeping RAM usage low on 16GB machines.
+
+## Output Example
+
+```
+ShutterSort — Folder Analysis Summary
+┏━━━┳━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
+┃ # ┃ Score ┃ Scene     ┃ People ┃ Folder           ┃ Summary                           ┃ Size     ┃ Pic%   ┃ Vid%   ┃ Dupes ┃
+┡━━━╇━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
+│ 1 │ 8/10  │ landscape │ 2      │ .../vacation     │ Beautiful beach photos from vac…  │ 245.30 MB│ 100%   │ 0%     │ No    │
+│ 2 │ 2/10  │ junk      │ 0      │ .../screenshots  │ Screenshots of documents and re…  │ 12.50 MB │ 100%   │ 0%     │ Yes   │
+│ 3 │ 9/10  │ event     │ 6      │ .../family       │ Birthday party with family memb…  │ 512.00 MB│ 80%    │ 20%    │ No    │
+└───┴───────┴───────────┴────────┴──────────────────┴───────────────────────────────────┴──────────┴────────┴────────┴───────┘
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| **"No media folders found"** | Check Full Disk Access for your terminal app (see Prerequisites above) |
+| **Ollama connection refused** | Run `ollama serve` in another terminal tab |
+| **Model not found** | Run `ollama pull llama3.2-vision` |
+| **ARW files fail to process** | Ensure `rawpy` is installed: `pip install rawpy` |
+| **Slow analysis** | Large folders take longer; use `--verbose` to see progress |
+| **JSON parse errors** | The retry loop handles this automatically (up to 3 retries) |
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+Quick start for contributors:
+
+```bash
+git clone https://github.com/camiloavilacm/ShutterSort.git
+cd ShutterSort
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest -m "not integration"
+```
+
+### Branching Model
+
+- `main` — Production (auto-publishes to PyPI)
+- `develop` — Staging (auto-publishes to TestPyPI)
+- `feature/*` — Feature branches (PR → develop)
+
+### CI/CD
+
+Every PR runs lint (ruff), type checks (mypy), and tests (pytest) on Python 3.10–3.13.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

shuttersort-0.1.0/media_pruner/__init__.py

@@ -0,0 +1,18 @@
+"""ShutterSort - AI-powered media folder analyzer and pruner.
+
+An agent-based CLI tool that scans local media folders, analyzes them
+with a local Vision Language Model (Ollama/llama3.2-vision), detects
+duplicates, and provides an interactive cleanup interface.
+
+Architecture:
+    - LibrarianAgent: Manages file system, extracts previews/frames, finds duplicates
+    - CuratorAgent: Vision analysis via Ollama, returns typed AnalysisResult
+    - DecisionAgent: Interactive review, Rich tables, AppleScript trash
+
+Usage:
+    shuttersort --path ~/Desktop
+    shuttersort --path ~/Photos --model llama3.2-vision
+"""
+
+__version__ = "0.1.0"
+__author__ = "camiloavilacm"

shuttersort-0.1.0/media_pruner/agent_base.py

@@ -0,0 +1,206 @@
+"""Base agent class with Ollama interface and automatic retry logic.
+
+This module defines the MediaAgent abstract base class (ABC) that provides:
+    - Ollama API connection management
+    - Automatic retry with "reflection" on JSON parse failures
+    - Shared logging and configuration
+
+The retry loop is a key "agentic" feature: if the LLM returns malformed JSON,
+instead of crashing, the agent sends the error back to the model and asks it
+to self-correct. This mimics how a human would say "that didn't make sense,
+try again."
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any
+
+from .models import AnalysisResult
+from .utils import parse_json_with_retry
+
+# ---------------------------------------------------------------------------
+# Logger setup
+# ---------------------------------------------------------------------------
+# We use Python's built-in logging module instead of print() because:
+# - Logs can be directed to files, stdout, or both
+# - Log levels (DEBUG, INFO, WARNING, ERROR) provide filtering control
+# - Each log entry includes timestamp, level, and source module
+# ---------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+class MediaAgent(ABC):
+    """Abstract base class for all agents in the ShutterSort system.
+
+    This class provides the shared infrastructure that all agents need:
+    - Connection to Ollama
+    - Retry logic for LLM calls
+    - Logging
+
+    Subclasses must implement their specific behavior via abstract methods.
+    This is the Template Method pattern: the base class defines the skeleton
+    of an algorithm (the retry loop), and subclasses fill in the details.
+
+    Attributes:
+        model: The Ollama model name (e.g., 'llama3.2-vision').
+        max_retries: Maximum number of retry attempts on JSON parse failure.
+        ollama_client: The Ollama client instance (set in __init__).
+    """
+
+    def __init__(
+        self,
+        model: str = "llama3.2-vision",
+        max_retries: int = 3,
+        ollama_client: Any = None,
+    ) -> None:
+        """Initialize the MediaAgent.
+
+        Args:
+            model: The Ollama model to use for vision analysis.
+            max_retries: How many times to retry on JSON parse failure.
+            ollama_client: Optional pre-configured Ollama client (for testing).
+                          If None, a new ollama.Client() is created.
+        """
+        self.model = model
+        self.max_retries = max_retries
+
+        # Lazy import of ollama to avoid import errors when the package
+        # isn't installed yet (e.g., during `pip install` phase).
+        if ollama_client is not None:
+            self.ollama_client = ollama_client
+        else:
+            import ollama
+
+            self.ollama_client = ollama.Client()
+
+    # -----------------------------------------------------------------------
+    # Retry loop with reflection
+    # -----------------------------------------------------------------------
+    def call_ollama_with_retry(
+        self,
+        prompt: str,
+        images: list[bytes] | None = None,
+    ) -> AnalysisResult:
+        """Call Ollama with automatic retry on JSON parse failure.
+
+        This is the core "agentic" behavior. The flow is:
+        1. Send prompt + images to Ollama
+        2. Try to parse the response as JSON
+        3. If parsing fails, send the error back to Ollama and retry
+        4. Repeat up to max_retries times
+        5. If all retries fail, raise the last exception
+
+        The "reflection" happens in step 3: we tell the model exactly what
+        went wrong ("Invalid JSON: ...") so it can self-correct. This is
+        much more effective than a blind retry.
+
+        Args:
+            prompt: The text prompt to send to the model.
+            images: Optional list of image bytes (JPEG-encoded).
+
+        Returns:
+            A typed AnalysisResult with the model's analysis.
+
+        Raises:
+            ValueError: If all retries fail to produce valid JSON.
+            Exception: If Ollama itself fails (network error, etc.).
+        """
+        last_error: Exception | None = None
+        current_prompt = prompt
+
+        for attempt in range(1, self.max_retries + 1):
+            try:
+                logger.info(
+                    "Calling Ollama (attempt %d/%d, model=%s)",
+                    attempt,
+                    self.max_retries,
+                    self.model,
+                )
+
+                # Build the message for Ollama
+                # The ollama Python client accepts images as base64 or bytes
+                kwargs: dict[str, Any] = {
+                    "model": self.model,
+                    "messages": [
+                        {
+                            "role": "user",
+                            "content": current_prompt,
+                        }
+                    ],
+                }
+
+                if images:
+                    kwargs["images"] = images
+
+                # Call the Ollama API
+                response = self.ollama_client.chat(**kwargs)
+                response_text: str = response["message"]["content"]
+
+                # Try to parse the response as JSON
+                parsed = parse_json_with_retry(response_text)
+
+                # Convert the parsed dict to an AnalysisResult
+                # Using .get() with defaults provides safety against missing fields
+                result = AnalysisResult(
+                    scene_type=parsed.get("scene_type", "other"),
+                    score=int(parsed.get("score", 1)),
+                    summary=parsed.get("summary", ""),
+                    people_count=int(parsed.get("people_count", 0)),
+                    people_description=parsed.get("people_description", ""),
+                    emotions_detected=parsed.get("emotions_detected", ""),
+                    raw_json=response_text,
+                )
+
+                logger.info(
+                    "Ollama response parsed successfully: scene=%s, score=%d",
+                    result.scene_type,
+                    result.score,
+                )
+                return result
+
+            except (ValueError, KeyError) as exc:
+                # JSON parse error or missing field — retry with reflection
+                last_error = exc
+                logger.warning(
+                    "Attempt %d failed: %s. Retrying with error feedback...",
+                    attempt,
+                    exc,
+                )
+
+                # "Reflect" the error back to the model
+                # This tells the model what went wrong and asks it to fix it
+                current_prompt = (
+                    f"{prompt}\n\n"
+                    f"ERROR: Your previous response could not be parsed. "
+                    f"Details: {exc}\n\n"
+                    f"Please respond with ONLY a valid JSON object matching "
+                    f"the required schema. Do NOT include any text before or "
+                    f"after the JSON. Do NOT use markdown code blocks."
+                )
+
+        # All retries exhausted
+        raise ValueError(
+            f"Failed to get valid JSON from Ollama after {self.max_retries} "
+            f"attempts. Last error: {last_error}"
+        ) from last_error
+
+    # -----------------------------------------------------------------------
+    # Abstract method: each agent defines its own execution logic
+    # -----------------------------------------------------------------------
+    @abstractmethod
+    def execute(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute the agent's primary task.
+
+        Each concrete agent implements this method with its specific logic.
+        This is the entry point for the agent's work.
+
+        Args:
+            *args: Positional arguments specific to the agent.
+            **kwargs: Keyword arguments specific to the agent.
+
+        Returns:
+            The result of the agent's execution (type varies by agent).
+        """
+        ...