Update src/services/journal_engine.py

src/services/journal_engine.py

@@ -11,12 +11,13 @@ from googleapiclient.http import MediaIoBaseUpload, MediaIoBaseDownload
 from google.oauth2.credentials import Credentials
 from ..config import get_user_keys, update_user_keys
 
+# Drive scope for application-specific data
 SCOPES = ['https://www.googleapis.com/auth/drive.appdata']
 
 class JournalEngine:
     @staticmethod
     def get_flow():
-        # [FIX] Essential for HF Spaces
+        # Allow OAuth over HTTP for local dev or specific hosting environments
         os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'
         return Flow.from_client_config(
             client_config={
@@ -33,6 +34,7 @@ class JournalEngine:
 
     @staticmethod
     def get_creds(uid):
+        # Load and parse user credentials from database
         user_data = get_user_keys(uid)
         token_json = user_data.get("google_token_json")
         if not token_json: return None
@@ -44,10 +46,12 @@ class JournalEngine:
 
     @staticmethod
     def get_drive_service(creds):
+        # Initialize Google Drive API client
         return build('drive', 'v3', credentials=creds)
 
     @staticmethod
     def load_journal(service, file_id):
+        # Download journal.json from Drive and parse to list
         try:
             request = service.files().get_media(fileId=file_id)
             fh = io.BytesIO()
@@ -63,6 +67,7 @@ class JournalEngine:
 
     @staticmethod
     def save_to_drive(service, file_id, journal_data):
+        # Upload current journal state to Drive
         media = MediaIoBaseUpload(
             io.BytesIO(json.dumps(journal_data).encode('utf-8')), 
             mimetype='application/json',
@@ -72,6 +77,7 @@ class JournalEngine:
 
     @staticmethod
     def initialize_journal(service):
+        # Find existing journal or create a new one in hidden app data folder
         try:
             response = service.files().list(
                 q="name='journal.json' and 'appDataFolder' in parents",
@@ -83,7 +89,6 @@ class JournalEngine:
             files = response.get('files', [])
             if files: return files[0]['id']
             
-            # Create if missing
             file_metadata = {'name': 'journal.json', 'parents': ['appDataFolder']}
             media = MediaIoBaseUpload(
                 io.BytesIO(json.dumps([]).encode('utf-8')), 
@@ -98,15 +103,14 @@ class JournalEngine:
 
     @classmethod
     def save_trade(cls, service, file_id, trade_data):
-        """Smart Update: Edits existing ID or Appends new UUID + Auto-Tags Date."""
+        # Add new trade with ID/date tags or update existing record
         journal = cls.load_journal(service, file_id)
         
-        # Temporal Injection
         if 'trade_date' in trade_data:
             try:
                 dt = datetime.datetime.strptime(trade_data['trade_date'], "%Y-%m-%d")
-                trade_data['week'] = dt.strftime("%Y-W%W") # e.g. 2026-W05
-                trade_data['month'] = dt.strftime("%Y-%m") # e.g. 2026-02
+                trade_data['week'] = dt.strftime("%Y-W%W")
+                trade_data['month'] = dt.strftime("%Y-%m")
             except ValueError:
                 pass
 
@@ -130,10 +134,9 @@ class JournalEngine:
 
     @classmethod
     def delete_trade(cls, service, file_id, trade_id):
-        """Removes a trade by UUID and saves the list."""
+        # Remove trade by ID and sync with Drive
         journal = cls.load_journal(service, file_id)
         
-        # Strict string comparison to avoid integer/string mismatch
         initial_len = len(journal)
         new_journal = [t for t in journal if str(t.get('id')) != str(trade_id)]
         
@@ -144,6 +147,7 @@ class JournalEngine:
 
     @staticmethod
     def parse_pnl(pnl_str):
+        # Clean PnL string and convert to float
         try:
             clean = re.sub(r'[^\d\.-]', '', str(pnl_str))
             return float(clean) if clean else 0.0
@@ -151,6 +155,7 @@ class JournalEngine:
 
     @classmethod
     def calculate_stats(cls, journal_data):
+        # Compute winrate, best trade, and dominant bias
         if not journal_data: return {"winrate": "0%", "best_trade": "--", "bias": "Neutral"}
         
         wins = [t for t in journal_data if cls.parse_pnl(t.get('pnl', 0)) > 0]
@@ -159,7 +164,6 @@ class JournalEngine:
         
         best_trade = max(journal_data, key=lambda x: cls.parse_pnl(x.get('pnl', 0)), default={})
         
-        # Handle conditional reviews as bias proxy if explicit bias missing
         biases = []
         for t in journal_data:
             if t.get('bias'): 
@@ -177,44 +181,32 @@ class JournalEngine:
     
     @staticmethod
     def prepare_ai_payload(journal_data):
-        """
-        Surgically converts filtered journal trades into a Markdown table.
-        Uses exact keys from trading_journal.html: trade_date, ticker, pnl, review, tags.
-        """
+        # Format journal entries into Markdown table for AI processing
         if not journal_data:
             return "No trading data available for the current filter."
 
         try:
-            # 1. Convert to DataFrame
             df = pd.DataFrame(journal_data)
-
-            # 2. Define the columns Gemini needs based on your HTML structure
-            # We map 'review' instead of 'notes' to align with your dashboard 
             essential_cols = [
                 'trade_date', 'ticker', 'strategy', 'rrr', 
                 'pnl', 'rules_followed', 'review', 'tags'
             ]
 
-            # 3. Filter to existing columns to prevent KeyError 
             existing_cols = [c for c in essential_cols if c in df.columns]
             df_filtered = df[existing_cols].copy()
 
-            # 4. Data Sanitization for AI Readability
             if 'tags' in df_filtered.columns:
-                # Handle both list and string formats for tags 
                 df_filtered['tags'] = df_filtered['tags'].apply(
                     lambda x: ", ".join(x) if isinstance(x, list) else x
                 )
             
             if 'rules_followed' in df_filtered.columns:
-                # Map boolean-like strings to human-readable terms 
                 df_filtered['rules_followed'] = df_filtered['rules_followed'].apply(
                     lambda x: "Disciplined" if str(x).lower() == "true" else "Mistake"
                 )
 
-            # 5. Export to Markdown table
             return df_filtered.to_markdown(index=False)
 
         except Exception as e:
-            print(f"Surgery Error in prepare_ai_payload: {e}")
+            print(f"Error in prepare_ai_payload: {e}")
             return f"Error preparing data for AI: {str(e)}"