feat: Implement async AI analysis for email threads

- Added `get_latest_email_date()` function in `database.py` to retrieve the most recent email date for a given account and folder.
- Enhanced `fetch_folder_emails()` in `zoho_client.py` to intelligently determine the start date for fetching emails based on the latest email date in the database.
- Introduced `analyze_and_update_threads_async()` for asynchronous analysis of email threads, allowing concurrent processing.
- Created a synchronous wrapper `analyze_and_update_threads()` for easier integration.
- Updated `fetch_emails()` to support database session and account email parameters.
- Added comprehensive documentation in `AI_ANALYSIS_GUIDE.md` detailing the new AI analysis functionality.
- Implemented tests for the new features, including `test_fetch_with_db.py`, `test_ai_analysis.py`, and `test_single_analysis.py`.
- Added error handling and logging improvements throughout the codebase.

test_ai_analysis.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""
+Test script to demonstrate the AI analysis functionality.
+This script shows how to use the new async thread analysis function.
+"""
+
+import os
+import sys
+
+# Add the src directory to the path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "src"))
+
+from database import (
+    SessionLocal,
+    Thread,
+    analyze_and_update_threads,
+    create_db_tables,
+    get_threads_needing_analysis,
+)
+
+
+def main():
+    """Main function to test the AI analysis."""
+
+    # Create database tables if they don't exist
+    create_db_tables()
+
+    # Example account email - replace with your actual account
+    account_email = "your-email@example.com"
+
+    # Get a database session
+    db = SessionLocal()
+    try:
+        # Check how many threads need analysis
+        threads_needing_analysis = get_threads_needing_analysis(db, account_email)
+        print(
+            f"Found {len(threads_needing_analysis)} threads needing analysis for {account_email}"
+        )
+
+        if not threads_needing_analysis:
+            print(
+                "No threads need analysis. Make sure you have ingested some emails first."
+            )
+
+            # Show all threads for this account
+            all_threads = (
+                db.query(Thread)
+                .filter(Thread.account_email == account_email.lower())
+                .all()
+            )
+            print(f"Total threads for {account_email}: {len(all_threads)}")
+
+            if all_threads:
+                print("Sample threads:")
+                for thread in all_threads[:3]:
+                    print(
+                        f"  Thread {thread.id}: {thread.subject} (analyzed: {thread.last_analyzed_at is not None})"
+                    )
+
+            return
+
+        print(f"Starting AI analysis for {len(threads_needing_analysis)} threads...")
+
+        # Run the analysis with max 3 concurrent tasks
+        analyze_and_update_threads(
+            account_email=account_email, max_concurrent=3, only_unanalyzed=True
+        )
+
+        print("Analysis complete!")
+
+        # Show results
+        analyzed_threads = (
+            db.query(Thread)
+            .filter(
+                Thread.account_email == account_email.lower(),
+                Thread.last_analyzed_at.isnot(None),
+            )
+            .all()
+        )
+
+        print(f"\nAnalyzed {len(analyzed_threads)} threads:")
+        for thread in analyzed_threads[:5]:  # Show first 5
+            print(f"  Thread {thread.id}: {thread.subject[:50]}...")
+            print(f"    Actionable: {thread.actionable}")
+            print(f"    Confidence: {thread.ai_confidence:.2f}")
+            print(f"    Summary: {thread.ai_summary[:100]}...")
+            print()
+
+    except Exception as e:
+        print(f"Error: {e}")
+        import traceback
+
+        traceback.print_exc()
+    finally:
+        db.close()
+
+
+if __name__ == "__main__":
+    main()