explainio-airflow-agent 0.1.1__tar.gz

explainio_airflow_agent-0.1.1/MANIFEST.in

@@ -0,0 +1 @@
+include cost_agent/README.md

explainio_airflow_agent-0.1.1/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: explainio-airflow-agent
+Version: 0.1.1
+Summary: Explain.io FinOps Airflow Cost Agent
+Home-page: https://explain.io
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Apache Airflow
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 💸 Explain.io - Airflow Cost Agent
+
+[![Beta](https://img.shields.io/badge/Status-Beta-blue.svg)]()
+[![Python](https://img.shields.io/badge/Python-3.9+-yellow.svg)]()
+[![Airflow](https://img.shields.io/badge/Airflow-2.0+-red.svg)]()
+
+**Explain.io** is a FinOps tool for Data Engineers. This lightweight Airflow plugin automatically attributes Google Cloud BigQuery compute costs to the exact DAG and Task that triggered them.
+
+No more guessing which pipeline caused the bill spike. No more changing your SQL or Python code to add tracking tags.
+
+## ✨ Features
+* **Zero Code Changes:** Just add a single `on_success_callback` to your DAG definition.
+* **Zero Blast Radius:** Network requests run asynchronously in a separate thread. If the Explain.io API goes down, your DAG **will still succeed**. Exceptions are silently swallowed and logged.
+* **Instant Dashboard:** View your pipeline costs, projected monthly spend, and heaviest DAGs at [explain-io.vercel.app](https://explain-io.vercel.app) *(Update this link to your actual domain later)*.
+
+---
+
+## 🚀 Installation
+
+Install the package directly from GitHub into your Airflow environment:
+
+```bash
+pip install explainio-airflow-agent
+```

explainio_airflow_agent-0.1.1/README.md

@@ -0,0 +1,119 @@
+# Explain.io - Core Platform (Monorepo)
+
+Explain.io is a B2B SaaS platform that provides active cost attribution for data pipelines (Airflow + BigQuery).
+
+This repository contains the core infrastructure: the FastAPI backend that ingests webhook payloads from Airflow agents, and the Next.js frontend dashboard where users view their cost analytics.
+
+> **🤖 AI Assistant / LLM Notice:**
+> Before writing any code, please read the `agents.md` file in the root directory for strict architectural guidelines, security rules, and tech stack versions.
+
+---
+
+## 🏗 Repository Structure
+
+```text
+explain-io/
+├── backend/                # FastAPI backend & Background Workers
+│   ├── main.py             # API entry point & webhook ingestion
+│   ├── worker.py           # apscheduler tasks (GCP cost calculation)
+│   ├── pyproject.toml      # Python dependencies (managed via uv)
+│   └── .env                # Backend secrets (Service Role)
+├── frontend/               # Next.js App Router Dashboard
+│   ├── app/                # React components & pages
+│   ├── utils/supabase/     # @supabase/ssr client/server utilities
+│   ├── package.json        # Node dependencies
+│   └── .env.local          # Frontend secrets (Anon Key)
+├── database/               # SQL Migrations
+│   └── 0001_initial.sql    # Supabase schema & RLS policies
+└── agents.md               # Strict context and rules for AI agents
+```
+
+## 🚀 Tech Stack
+
+*   **Frontend**: Next.js (App Router), React, TypeScript, Tailwind CSS, Recharts.
+*   **Backend**: FastAPI, Python 3.12+, `uv` (Package Manager), `apscheduler`.
+*   **Database & Auth**: Supabase (PostgreSQL), strict Row Level Security (RLS).
+*   **Hosting**: Vercel (Frontend), Render (Backend).
+
+## 💻 Local Development Setup
+
+### Prerequisites
+
+*   Node.js (v18+)
+*   Python (3.12+)
+*   `uv` (Extremely fast Python package manager)
+*   A Supabase project with the schema applied from `database/0001_initial.sql`.
+
+### 1. Database Setup
+
+1.  Create a Supabase project.
+2.  Run the SQL from `database/0001_initial.sql` in the SQL Editor to create tables and RLS policies.
+3.  Grab your anon public key and service_role secret key from the Supabase API settings.
+
+### 2. Backend Setup (`/backend`)
+
+The backend is responsible for ingesting agent data and querying GCP APIs.
+
+```bash
+cd backend
+
+# 1. Install dependencies using uv
+uv sync
+
+# 2. Set up environment variables
+cp .env.example .env
+```
+
+Backend `.env` format:
+
+```ini
+SUPABASE_URL="https://your-project.supabase.co"
+SUPABASE_KEY="your_secret_SERVICE_ROLE_key" # Bypass RLS
+GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/gcp-service-account.json"
+```
+
+Run the backend locally:
+
+```bash
+uv run uvicorn main:app --reload --port 8000
+```
+
+### 3. Frontend Setup (`/frontend`)
+
+The frontend is the customer-facing dashboard.
+
+```bash
+cd frontend
+
+# 1. Install dependencies
+npm install
+
+# 2. Set up environment variables
+cp .env.example .env.local
+```
+
+Frontend `.env.local` format:
+
+```ini
+NEXT_PUBLIC_SUPABASE_URL="https://your-project.supabase.co"
+NEXT_PUBLIC_SUPABASE_ANON_KEY="your_public_ANON_key" # Obeys RLS
+```
+
+Run the frontend locally:
+
+```bash
+npm run dev
+```
+
+The dashboard will be available at `http://localhost:3000`.
+
+## 🔒 Security Posture
+
+*   **Frontend Authentication**: Handled via `@supabase/ssr`.
+*   **Database Security**: Locked down completely by Postgres RLS. The API keys verify identity, but RLS guarantees tenant isolation (a user can only see rows in `cost_ledger` matching their `user_id` in `user_projects`).
+*   **Backend Ingestion**: Uses user-generated API keys (stored in `api_keys` table) passed via Bearer token to map incoming DAG runs to the correct `project_id`.
+
+## 🚢 Deployment
+
+*   **Frontend**: Auto-deploys via Vercel integration on pushes to `main`.
+*   **Backend**: Auto-deploys via Render integration on pushes to `main`. Ensure the Render Root Directory is set to `backend/`.

explainio_airflow_agent-0.1.1/cost_agent/README.md

@@ -0,0 +1,24 @@
+# 💸 Explain.io - Airflow Cost Agent
+
+[![Beta](https://img.shields.io/badge/Status-Beta-blue.svg)]()
+[![Python](https://img.shields.io/badge/Python-3.9+-yellow.svg)]()
+[![Airflow](https://img.shields.io/badge/Airflow-2.0+-red.svg)]()
+
+**Explain.io** is a FinOps tool for Data Engineers. This lightweight Airflow plugin automatically attributes Google Cloud BigQuery compute costs to the exact DAG and Task that triggered them.
+
+No more guessing which pipeline caused the bill spike. No more changing your SQL or Python code to add tracking tags.
+
+## ✨ Features
+* **Zero Code Changes:** Just add a single `on_success_callback` to your DAG definition.
+* **Zero Blast Radius:** Network requests run asynchronously in a separate thread. If the Explain.io API goes down, your DAG **will still succeed**. Exceptions are silently swallowed and logged.
+* **Instant Dashboard:** View your pipeline costs, projected monthly spend, and heaviest DAGs at [explain-io.vercel.app](https://explain-io.vercel.app) *(Update this link to your actual domain later)*.
+
+---
+
+## 🚀 Installation
+
+Install the package directly from GitHub into your Airflow environment:
+
+```bash
+pip install explainio-airflow-agent
+```

explainio_airflow_agent-0.1.1/cost_agent/__init__.py

@@ -0,0 +1,6 @@
+from airflow.plugins_manager import AirflowPlugin
+from cost_agent.listener import CostAgentListener
+
+class CostAgentPlugin(AirflowPlugin):
+    name = "cost_agent_plugin"
+    listeners = [CostAgentListener()]

explainio_airflow_agent-0.1.1/cost_agent/client.py

@@ -0,0 +1,38 @@
+import requests
+import logging
+import os
+import threading
+
+log = logging.getLogger(__name__)
+
+# Your SaaS Backend URL
+# Default points to the production API, can be overridden by EXPLAIN_IO_API_URL for local dev
+API_URL = os.getenv("EXPLAIN_IO_API_URL", "https://api.explain.io/api/v1/ingest")
+
+
+def _send_async(payload, api_key):
+    """Running in a separate thread to avoid blocking the scheduler loop"""
+    try:
+        headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
+        log.info("Cost Agent: Sending payload inside _send_async")
+        log.info(payload)
+        response = requests.post(API_URL, json=payload, headers=headers, timeout=5)
+        if response.status_code != 200:
+            log.warning(f"Cost Agent: Server rejected payload {response.status_code}")
+    except Exception as e:
+        # Never crash the user's pipeline because of a network error
+        log.debug(f"Cost Agent: Failed to send event: {e}")
+
+
+def send_event(payload):
+    """Spawns a thread to send data"""
+    # 1. Get API Key from Environment (The "License")
+    api_key = os.getenv("EXPLAIN_IO_API_KEY")
+    if not api_key:
+        log.info("Cost Agent: Plugin disabled (no EXPLAIN_IO_API_KEY found)")
+        return  # Plugin disabled if no key
+
+    # Actually spawn a thread to be truly async
+    thread = threading.Thread(target=_send_async, args=(payload, api_key))
+    thread.daemon = True
+    thread.start()

explainio_airflow_agent-0.1.1/cost_agent/extractors.py

@@ -0,0 +1,45 @@
+import logging
+
+# Dual support for Airflow 2.x and 3.x
+try:
+    from airflow.sdk.execution_time.task_runner import RuntimeTaskInstance as TI
+    IS_V3 = True
+except ImportError:
+    from airflow.models.taskinstance import TaskInstance as TI
+    IS_V3 = False
+
+log = logging.getLogger(__name__)
+
+def extract_job_metadata(task_instance):
+    """
+    Inspects a TaskInstance to find the external Cloud Job ID.
+    Works for both Airflow 2.x and 3.x.
+    """
+    # Duck-typing: Both versions have task and operator_name
+    operator_name = getattr(task_instance.task, 'operator_name', None) or task_instance.task.__class__.__name__
+
+    if "BigQuery" in operator_name:
+        return _extract_bigquery_id(task_instance)
+    return None
+
+def _extract_bigquery_id(ti):
+    try:
+        # Airflow 3.0 uses RuntimeTaskInstance, 2.x uses standard TI
+        # Both support xcom_pull
+        job_id = ti.xcom_pull(task_ids=ti.task_id, key='return_value')
+        
+        # Access attributes carefully
+        task = ti.task
+        project_id = getattr(task, 'project_id', None)
+        location = getattr(task, 'location', 'US')
+
+        if job_id and isinstance(job_id, str):
+            return {
+                "provider": "gcp_bigquery",
+                "job_id": job_id,
+                "project_id": project_id,
+                "location": location,
+            }
+    except Exception as e:
+        log.debug(f"Could not extract BQ ID for {ti.task_id}: {e}")
+    return None

explainio_airflow_agent-0.1.1/cost_agent/listener.py

@@ -0,0 +1,24 @@
+import logging
+from airflow.listeners import hookimpl
+from cost_agent.extractors import extract_job_metadata
+from cost_agent.client import send_event
+
+log = logging.getLogger(__name__)
+
+class CostAgentListener:
+    @hookimpl
+    def on_task_instance_success(self, previous_state, task_instance):
+        try:
+            metadata = extract_job_metadata(task_instance)
+            if not metadata:
+                return
+
+            payload = {
+                "dag_id": task_instance.dag_id,
+                "task_id": task_instance.task_id,
+                "execution_date": task_instance.start_date.isoformat(),
+                "cloud_metadata": metadata
+            }
+            send_event(payload)
+        except Exception:
+            log.exception("Cost Agent: unexpected error in on_task_instance_success — swallowed to protect pipeline")

explainio_airflow_agent-0.1.1/explainio_airflow_agent.egg-info/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: explainio-airflow-agent
+Version: 0.1.1
+Summary: Explain.io FinOps Airflow Cost Agent
+Home-page: https://explain.io
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Apache Airflow
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 💸 Explain.io - Airflow Cost Agent
+
+[![Beta](https://img.shields.io/badge/Status-Beta-blue.svg)]()
+[![Python](https://img.shields.io/badge/Python-3.9+-yellow.svg)]()
+[![Airflow](https://img.shields.io/badge/Airflow-2.0+-red.svg)]()
+
+**Explain.io** is a FinOps tool for Data Engineers. This lightweight Airflow plugin automatically attributes Google Cloud BigQuery compute costs to the exact DAG and Task that triggered them.
+
+No more guessing which pipeline caused the bill spike. No more changing your SQL or Python code to add tracking tags.
+
+## ✨ Features
+* **Zero Code Changes:** Just add a single `on_success_callback` to your DAG definition.
+* **Zero Blast Radius:** Network requests run asynchronously in a separate thread. If the Explain.io API goes down, your DAG **will still succeed**. Exceptions are silently swallowed and logged.
+* **Instant Dashboard:** View your pipeline costs, projected monthly spend, and heaviest DAGs at [explain-io.vercel.app](https://explain-io.vercel.app) *(Update this link to your actual domain later)*.
+
+---
+
+## 🚀 Installation
+
+Install the package directly from GitHub into your Airflow environment:
+
+```bash
+pip install explainio-airflow-agent
+```

explainio_airflow_agent-0.1.1/explainio_airflow_agent.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+MANIFEST.in
+README.md
+setup.py
+cost_agent/README.md
+cost_agent/__init__.py
+cost_agent/client.py
+cost_agent/extractors.py
+cost_agent/listener.py
+explainio_airflow_agent.egg-info/PKG-INFO
+explainio_airflow_agent.egg-info/SOURCES.txt
+explainio_airflow_agent.egg-info/dependency_links.txt
+explainio_airflow_agent.egg-info/requires.txt
+explainio_airflow_agent.egg-info/top_level.txt
+tests/test_aggregator.py
+tests/test_extractors.py
+tests/test_mailer.py
+tests/test_scheduler.py

explainio_airflow_agent-0.1.1/explainio_airflow_agent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

explainio_airflow_agent-0.1.1/explainio_airflow_agent.egg-info/requires.txt

@@ -0,0 +1 @@
+requests

explainio_airflow_agent-0.1.1/explainio_airflow_agent.egg-info/top_level.txt

@@ -0,0 +1 @@
+cost_agent

explainio_airflow_agent-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

explainio_airflow_agent-0.1.1/setup.py

@@ -0,0 +1,21 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="explainio-airflow-agent",
+    version="0.1.1",
+    packages=find_packages(include=["cost_agent", "cost_agent.*"]),
+    install_requires=[
+        "requests",
+    ],
+    description="Explain.io FinOps Airflow Cost Agent",
+    long_description=open("cost_agent/README.md").read(),
+    long_description_content_type="text/markdown",
+    url="https://explain.io",
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Framework :: Apache Airflow",
+    ],
+    python_requires=">=3.9",
+)

explainio_airflow_agent-0.1.1/tests/test_aggregator.py

@@ -0,0 +1,96 @@
+import pytest
+from unittest.mock import MagicMock
+from datetime import date, datetime, timedelta
+from backend.aggregator import get_daily_summary
+
+@pytest.fixture
+def mock_supabase():
+    return MagicMock()
+
+def test_get_daily_summary_calculates_correctly(mock_supabase):
+    # Setup
+    user_id = "test-user-id"
+    today = date(2026, 4, 15)
+    
+    # Mock data for today's RPC response
+    today_summary = {
+        "total_cost": 70.0,
+        "top_dags": [
+            {"dag_id": "dag3", "cost": 30.0},
+            {"dag_id": "dag2", "cost": 20.0},
+            {"dag_id": "dag1", "cost": 15.0}
+        ]
+    }
+    
+    # Mock data for last week's RPC response
+    last_week_summary = {
+        "total_cost": 50.0,
+        "top_dags": [{"dag_id": "dag1", "cost": 50.0}]
+    }
+    
+    mock_response_today = MagicMock()
+    mock_response_today.data = [today_summary]
+    
+    mock_response_last_week = MagicMock()
+    mock_response_last_week.data = [last_week_summary]
+    
+    mock_supabase.rpc.return_value.execute.side_effect = [
+        mock_response_today,
+        mock_response_last_week
+    ]
+    
+    # Execute
+    summary = get_daily_summary(mock_supabase, user_id, today)
+    
+    # Verify
+    assert summary["total_cost"] == 70.0
+    assert len(summary["top_dags"]) == 3
+    assert summary["top_dags"][0]["dag_id"] == "dag3"
+    assert summary["top_dags"][1]["dag_id"] == "dag2"
+    assert summary["top_dags"][2]["dag_id"] == "dag1"
+    
+    # % change: (70 - 50) / 50 * 100 = 40%
+    assert summary["prev_week_comparison"] == 40.0
+
+def test_get_daily_summary_handles_no_data(mock_supabase):
+    # Setup
+    user_id = "test-user-id"
+    today = date(2026, 4, 15)
+    
+    mock_response_empty = MagicMock()
+    mock_response_empty.data = []
+    
+    mock_supabase.rpc.return_value.execute.return_value = mock_response_empty
+    
+    # Execute
+    summary = get_daily_summary(mock_supabase, user_id, today)
+    
+    # Verify
+    assert summary["total_cost"] == 0.0
+    assert summary["top_dags"] == []
+    assert summary["prev_week_comparison"] == 0.0
+
+def test_get_daily_summary_handles_division_by_zero(mock_supabase):
+    # Setup
+    user_id = "test-user-id"
+    today = date(2026, 4, 15)
+    
+    # Data for today
+    mock_response_today = MagicMock()
+    mock_response_today.data = [{"total_cost": 10.0, "top_dags": [{"dag_id": "dag1", "cost": 10.0}]}]
+    
+    # No data for last week
+    mock_response_last_week = MagicMock()
+    mock_response_last_week.data = []
+    
+    mock_supabase.rpc.return_value.execute.side_effect = [
+        mock_response_today,
+        mock_response_last_week
+    ]
+    
+    # Execute
+    summary = get_daily_summary(mock_supabase, user_id, today)
+    
+    # Verify
+    assert summary["total_cost"] == 10.0
+    assert summary["prev_week_comparison"] == 100.0

explainio_airflow_agent-0.1.1/tests/test_extractors.py

@@ -0,0 +1,60 @@
+import sys
+from unittest.mock import MagicMock, patch
+
+def test_extract_job_metadata_v2_mock():
+    # Mocking TaskInstance for Airflow 2.x
+    mock_ti = MagicMock()
+    mock_ti.task_id = "test_bq_task"
+    mock_ti.xcom_pull.return_value = "job_12345"
+    
+    mock_task = MagicMock()
+    # Airflow 2.x might not have operator_name on task object directly, but often it's on the TI's task
+    mock_task.operator_name = "BigQueryInsertJobOperator"
+    mock_task.project_id = "my-project"
+    mock_task.location = "EU"
+    mock_ti.task = mock_task
+
+    from cost_agent.extractors import extract_job_metadata
+    
+    metadata = extract_job_metadata(mock_ti)
+    
+    print(f"V2 Metadata: {metadata}")
+    assert metadata is not None
+    assert metadata["job_id"] == "job_12345"
+    assert metadata["project_id"] == "my-project"
+    assert metadata["location"] == "EU"
+
+def test_extract_job_metadata_v3_mock():
+    # Mocking RuntimeTaskInstance for Airflow 3.x
+    mock_ti = MagicMock()
+    mock_ti.task_id = "test_bq_task_v3"
+    mock_ti.xcom_pull.return_value = "job_v3_6789"
+    
+    # In Airflow 3, the structure is similar but might use duck-typing
+    mock_task = MagicMock()
+    mock_task.operator_name = "BigQueryInsertJobOperator"
+    mock_task.project_id = "my-v3-project"
+    mock_task.location = "US"
+    mock_ti.task = mock_task
+
+    from cost_agent.extractors import extract_job_metadata
+    
+    metadata = extract_job_metadata(mock_ti)
+    
+    print(f"V3 Metadata: {metadata}")
+    assert metadata is not None
+    assert metadata["job_id"] == "job_v3_6789"
+    assert metadata["project_id"] == "my-v3-project"
+    assert metadata["location"] == "US"
+
+if __name__ == "__main__":
+    try:
+        test_extract_job_metadata_v2_mock()
+        print("✅ Airflow 2.x Mock Test Passed")
+        test_extract_job_metadata_v3_mock()
+        print("✅ Airflow 3.x Mock Test Passed")
+    except Exception as e:
+        print(f"❌ Test Failed: {e}")
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)

explainio_airflow_agent-0.1.1/tests/test_mailer.py

@@ -0,0 +1,82 @@
+import pytest
+import os
+from unittest.mock import patch, MagicMock
+from backend.mailer import send_digest_email
+
+@patch("resend.Emails.send")
+@patch.dict(os.environ, {"RESEND_API_KEY": "re_test_key"})
+def test_send_digest_email_calls_resend(mock_send):
+    # Setup
+    user_email = "test@example.com"
+    summary_data = {
+        "total_cost": 75.50,
+        "top_dags": [
+            {"dag_id": "daily_ingestion", "cost": 45.00},
+            {"dag_id": "user_sync", "cost": 20.50},
+            {"dag_id": "backup_job", "cost": 10.00}
+        ],
+        "prev_week_comparison": 15.5
+    }
+    
+    # Execute
+    send_digest_email(user_email, summary_data)
+    
+    # Verify
+    mock_send.assert_called_once()
+    call_args = mock_send.call_args[1]
+    
+    assert call_args["to"] == user_email
+    assert "Explain.io" in call_args["subject"]
+    assert "$75.50" in call_args["html"]
+    assert "daily_ingestion" in call_args["html"]
+    assert "15.5%" in call_args["html"]
+    assert "https://explain.io/dashboard" in call_args["html"]
+
+@patch("resend.Emails.send")
+@patch.dict(os.environ, {"RESEND_API_KEY": "re_test_key"})
+def test_send_digest_email_handles_negative_comparison(mock_send):
+    # Setup
+    user_email = "test@example.com"
+    summary_data = {
+        "total_cost": 40.00,
+        "top_dags": [
+            {"dag_id": "daily_ingestion", "cost": 40.00}
+        ],
+        "prev_week_comparison": -10.0
+    }
+    
+    # Execute
+    send_digest_email(user_email, summary_data)
+    
+    # Verify
+    mock_send.assert_called_once()
+    call_args = mock_send.call_args[1]
+    
+    assert "-10.0%" in call_args["html"]
+
+@patch("resend.Emails.send")
+@patch.dict(os.environ, {"RESEND_API_KEY": "re_test_key"})
+def test_send_digest_email_handles_exception(mock_send):
+    # Setup
+    mock_send.side_effect = Exception("API Error")
+    user_email = "test@example.com"
+    summary_data = {"total_cost": 10.0, "top_dags": [], "prev_week_comparison": 0.0}
+    
+    # Execute
+    result = send_digest_email(user_email, summary_data)
+    
+    # Verify
+    assert result is None
+    mock_send.assert_called_once()
+
+@patch.dict(os.environ, {}, clear=True)
+def test_send_digest_email_handles_missing_api_key():
+    # Setup
+    user_email = "test@example.com"
+    summary_data = {"total_cost": 10.0, "top_dags": [], "prev_week_comparison": 0.0}
+    
+    # Execute
+    result = send_digest_email(user_email, summary_data)
+    
+    # Verify
+    assert result is None

explainio_airflow_agent-0.1.1/tests/test_scheduler.py

@@ -0,0 +1,86 @@
+import pytest
+from unittest.mock import patch, MagicMock
+from datetime import datetime, timedelta, timezone
+from backend.main import dispatch_daily_digests
+
+@patch("backend.main.supabase")
+@patch("backend.main.aggregator.get_daily_summary")
+@patch("backend.main.mailer.send_digest_email")
+def test_dispatch_daily_digests_success(mock_send, mock_summary, mock_supabase):
+    # Setup
+    yesterday = datetime.now(timezone.utc).date() - timedelta(days=1)
+    
+    # Mock user settings query
+    mock_users = [
+        {"user_id": "user1", "email_digest_enabled": True, "email": "user1@example.com"},
+        {"user_id": "user2", "email_digest_enabled": True, "email": "user2@example.com"}
+    ]
+    
+    # Mock supabase.table("user_settings").select(...).eq(...).execute()
+    mock_query = MagicMock()
+    mock_query.execute.return_value = MagicMock(data=mock_users)
+    mock_supabase.table.return_value.select.return_value.eq.return_value = mock_query
+    
+    # Mock aggregator data
+    mock_summary.side_effect = [
+        {"total_cost": 10.5, "top_dags": [{"dag_id": "dag1", "cost": 10.5}], "prev_week_comparison": 5.0},
+        {"total_cost": 0.0, "top_dags": [], "prev_week_comparison": 0.0} # No data for user2
+    ]
+    
+    # Execute
+    dispatch_daily_digests()
+    
+    # Verify
+    # Should be called for both users
+    assert mock_summary.call_count == 2
+    mock_summary.assert_any_call(mock_supabase, "user1", yesterday)
+    mock_summary.assert_any_call(mock_supabase, "user2", yesterday)
+    
+    # Should only send email for user1 (data exists)
+    assert mock_send.call_count == 1
+    mock_send.assert_called_once_with("user1@example.com", {"total_cost": 10.5, "top_dags": [{"dag_id": "dag1", "cost": 10.5}], "prev_week_comparison": 5.0})
+
+@patch("backend.main.supabase")
+@patch("backend.main.aggregator.get_daily_summary")
+@patch("backend.main.mailer.send_digest_email")
+def test_dispatch_daily_digests_no_users(mock_send, mock_summary, mock_supabase):
+    # Setup
+    mock_supabase.table.return_value.select.return_value.eq.return_value.execute.return_value = MagicMock(data=[])
+    
+    # Execute
+    dispatch_daily_digests()
+    
+    # Verify
+    assert mock_summary.call_count == 0
+    assert mock_send.call_count == 0
+
+@patch("backend.main.supabase")
+@patch("backend.main.aggregator.get_daily_summary")
+@patch("backend.main.mailer.send_digest_email")
+def test_dispatch_daily_digests_failure_isolation(mock_send, mock_summary, mock_supabase):
+    # Setup: user1 fails, but user2 should still succeed
+    yesterday = datetime.now(timezone.utc).date() - timedelta(days=1)
+    
+    mock_users = [
+        {"user_id": "fail_user", "email": "fail@example.com"},
+        {"user_id": "success_user", "email": "success@example.com"}
+    ]
+    
+    mock_query = MagicMock()
+    mock_query.execute.return_value = MagicMock(data=mock_users)
+    mock_supabase.table.return_value.select.return_value.eq.return_value = mock_query
+    
+    # user1 raises an exception, user2 returns valid data
+    mock_summary.side_effect = [
+        Exception("DB Error for user1"),
+        {"total_cost": 20.0, "top_dags": [], "prev_week_comparison": 0.0}
+    ]
+    
+    # Execute
+    dispatch_daily_digests()
+    
+    # Verify
+    assert mock_summary.call_count == 2
+    # Email should be sent for success_user despite fail_user error
+    assert mock_send.call_count == 1
+    mock_send.assert_called_once_with("success@example.com", {"total_cost": 20.0, "top_dags": [], "prev_week_comparison": 0.0})