Skip to content

v3.1.0 - Interactive Python Selection & LLM-Based Insights

Choose a tag to compare

View all tags
@randynov randynov released this 22 Oct 14:41
· 68 commits to main since this release
v3.1.0
79612aa

🚨 Breaking Changes

  • Mail Rule Configuration: Users must re-run ./setup-mail-rule.sh to regenerate Mail rule script with new Python selection
    • Previous Mail scripts used dynamic which python3 detection (could select wrong Python)
    • New Mail scripts use user-selected Python path configured during setup
    • Action required: Run ./setup-mail-rule.sh to interactively select and configure Python installation

✨ Features

Interactive Python Selection with User-Friendly UI

  • Problem fixed: ModuleNotFoundError when Mail rule auto-selected wrong Python installation (e.g., miniconda without dependencies)
  • New setup experience:
    • Detects all Python installations (system, Homebrew, Miniconda, Anaconda)
    • Automatically verifies dependencies against Summarizer/requirements.txt
    • Groups display by status: ✓ Ready to use / ○ Needs setup / ⚠ Not recommended
    • Uses plain language names: "Miniconda Python 3.12" instead of /Users/you/miniconda/bin/python3
    • Detects PEP 668 restrictions on Python 3.14+ to prevent incompatible selections
    • Offers automated dependency installation via pip (with confirmation)
    • Option to install Python 3.11 via Homebrew when no suitable Python exists
    • Smart default selection: press Enter to use recommended ready-to-use Python

LLM-Based Cross-Article Insights

  • Intelligent pattern detection: Replaced regex-based pattern matching with LLM analysis
    • Identifies emerging themes across articles
    • Detects methodological patterns and research approaches
    • Highlights knowledge gaps and underexplored areas
  • Improved executive summary:
    • Better decimal preservation in sentence splitting (e.g., "11.2 months")
    • Increased word limit to 40 for complete findings
  • Publisher metadata fallback: Articles without title sources now use publisher field from alert data

Bullet Validation with Retry

  • Validates 4-bullet structure with required labels:
    • KEY FINDING, TACTICAL WIN [tag], MARKET SIGNAL [tag], CONCERN
  • Retries once on validation failure (max 2 attempts per article)
  • Ensures consistent summary format across all articles

🐛 Bug Fixes

Test Suite Alignment

  • Fixed 9 test failures caused by recent code changes
  • Updated mocks for content-type header checking (binary detection)
  • Added topic parameter support in test fixtures
  • Updated assertions to match 4-bullet validation requirements
  • All 43 tests now passing

Documentation Accuracy

  • Fixed dependencies: Added missing python-dotenv to requirements.txt
  • Fixed SMTP env vars: Corrected help text to use SMTP_* (not GMAIL_*)
  • Removed obsolete: Cleaned up Playwright references (not used in current codebase)
  • Line endings: Added .gitattributes to enforce Unix LF for scripts

📚 Documentation

LM Studio Configuration

  • Added clear LM Studio setup section to SETUP.md
  • Documented Ollama as optional fallback (not required)
  • Clarified configuration priority and backend fallback behavior
  • Added LM Studio troubleshooting section

Mail Rule Setup

  • Updated CLAUDE.md with new interactive Python selection process
  • Documented PEP 668 detection and handling
  • Added guidance for dependency installation

🔧 Changes Since v3.0.0

5 commits:

  1. Interactive Python selection with user-friendly UI
  2. Test suite fixes (9 → 0 failures)
  3. Documentation cleanup (SMTP config notes)
  4. Documentation alignment with code implementation
  5. Digest formatting improvements and LLM-based insights

Files changed: 13 files, +567 insertions, -98 deletions

Key files:

  • setup-mail-rule.sh - Complete rewrite of Python detection and selection
  • Summarizer/templates/process-alert.scpt - Use {{PYTHON_PATH}} template variable
  • digest_renderer.py - LLM-based cross-article insights
  • summarizer.py - Bullet validation with retry logic
  • config.py - Cross-article insights prompt, increased token limit
  • CLAUDE.md, README.md, SETUP.md, TROUBLESHOOTING.md - Comprehensive updates

📝 Upgrade Instructions

For Existing Users

  1. Re-run Mail rule setup (required):

    cd /path/to/AppletScriptorium
git pull
./setup-mail-rule.sh

  2. Select your Python installation:

    • Look for installations marked with ✓ (ready to use)
    • Press Enter to use the recommended option
    • Or select a different number if needed

  3. Install missing dependencies if prompted:

    • Script will offer to auto-install via pip
    • Or install manually: python3 -m pip install --user -r Summarizer/requirements.txt

For New Users

Follow the standard setup in docs/SETUP.md - the new interactive Python selection will guide you through configuration automatically.

✅ Benefits

  • Reliable Python detection: No more ModuleNotFoundError from wrong Python selection
  • User-friendly setup: Non-technical users can easily select correct Python installation
  • Smarter insights: LLM-based cross-article analysis replaces brittle regex patterns
  • Better quality: Bullet validation ensures consistent summary structure
  • Accurate docs: All documentation now matches actual implementation
Assets 2
Loading