Initial commit

app.py

@@ -0,0 +1,65 @@
+import gradio as gr
+import time
+from src.pipeline import generate_report
+from src.tools_loader import get_tools
+
+# Pre-load models/tools once to avoid cold start delays
+_ = get_tools()
+
+def process_inputs(target_variable: str, image_path: str):
+    """Gradio callback to generate SHAP explanation report."""
+    if not image_path:
+        return "**Please upload a SHAP summary plot image to begin.**"
+    if not target_variable.strip():
+        return "**Please enter a target variable (e.g., life expectancy).**"
+
+    start = time.time()
+    report = generate_report(target_variable.strip(), image_path)
+    elapsed = time.time() - start
+
+    return f"""### SHAP Explanation Report for **{target_variable.strip()}**
+
+{report}
+
+---
+*Generated in {elapsed:.1f} seconds*
+"""
+
+# Gradio App Interface
+with gr.Blocks(
+    theme=gr.themes.Soft(),
+    title="SHAP Summary Plot Explainer",
+    css="""
+    .input-section { max-width: 600px; margin: 0 auto; }
+    .report-output { margin-top: 30px; }
+    """
+) as demo:
+
+    # Header
+    gr.Markdown("# SHAP Summary Plot Explainer\n\nUpload a SHAP plot and specify your prediction target to get a detailed explanation.")
+
+    with gr.Column(elem_classes=["input-section"]):
+        target_input = gr.Textbox(
+            label="Target Variable",
+            placeholder="e.g., life expectancy, credit score, disease risk..."
+        )
+        shap_image = gr.Image(
+            type="filepath",
+            label="Upload SHAP Summary Plot Image",
+            height=350
+        )
+        generate_button = gr.Button("Generate Explanation", variant="primary")
+
+    with gr.Column(elem_classes=["report-output"]):
+        report_output = gr.Markdown("**Awaiting input...**")
+
+    # Link inputs to callback
+    generate_button.click(
+        fn=process_inputs,
+        inputs=[target_input, shap_image],
+        outputs=report_output,
+        show_progress="full"
+    )
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,4 @@
+crewai
+gradio>=4.27
+google-genai
+pydantic

src/config/agents.yaml

@@ -0,0 +1,10 @@
+shap_agent:
+  role: "SHAP Explanation Agent"
+  goal: >
+    Use the shap_vision_tool to analyze a SHAP summary plot image for a given target variable 
+    and return back the exact output. DO NOT add, interpret, or speculate beyond what the shap_vision_tool outputs.
+  backstory: >
+    A world-class Explainable AI (XAI) researcher AI trained in interpreting SHAP summary plots 
+    with precision and clarity. You specialize in transforming dense SHAP visualizations into 
+    insightful, structured natural language explanations without introducing any hallucinations 
+    or adding unverified inferences.

src/config/tasks.yaml

@@ -0,0 +1,8 @@
+shap_task:
+  description: >
+    Analyze the SHAP summary plot image at '{image_path}' for the target variable '{target_variable}'. 
+    Use the shap_vision_tool and return the exact output it generates. 
+    DO NOT add or modify anything beyond what the tool returns.
+  expected_output: >
+    The verbatim output generated by the shap_vision_tool based on the image and target variable.
+  agent: shap_agent

src/crew.py

@@ -0,0 +1,36 @@
+from crewai import Agent, Crew, Process, Task, LLM
+from crewai.project import CrewBase, agent, crew, task
+from .tools_loader import get_tools
+
+@CrewBase
+class ShapCrew:
+    """SHAP explainer crew"""
+
+    def __init__(self):
+        # Load tools once
+        self.tools = get_tools()
+        
+        # Initialize LLMs with optimal settings
+        self.llm = LLM(model="groq/meta-llama/llama-4-maverick-17b-128e-instruct", temperature=0.3)
+
+    @agent
+    def shap_agent(self) -> Agent:
+        return Agent(
+            config=self.agents_config['shap_agent'],
+            tools=[self.tools["shap_tool"]],
+            llm=self.llm,
+            allow_delegation=False,
+            verbose=False
+        )
+
+    @task
+    def shap_task(self) -> Task:
+        return Task(config=self.tasks_config['shap_task'])
+
+    @crew
+    def crew(self) -> Crew:
+        return Crew(
+            agents=self.agents,
+            tasks=self.tasks,
+            verbose=False
+        )

src/pipeline.py

@@ -0,0 +1,10 @@
+from .crew import ShapCrew
+
+def generate_report(target_variable: str, image_path: str) -> str:
+    """Generate a SHAP explanation report based on user input"""
+    crew = ShapCrew().crew()
+    result = crew.kickoff(inputs={
+        "target_variable": target_variable,
+        "image_path": image_path
+    })
+    return str(result).strip()

src/tools/shap_vision_tool.py

@@ -0,0 +1,80 @@
+from crewai.tools import BaseTool
+from pydantic import BaseModel
+from typing import Optional
+from google import genai
+from google.genai.types import Part, GenerateContentConfig
+import os
+import textwrap
+
+class ShapVisionToolSchema(BaseModel):
+    target_variable: str
+    image_path: str
+    prompt: Optional[str] = None
+
+class ShapVisionTool(BaseTool):
+    name: str = "shap_vision_tool"
+    description: str = (
+        "Generates a detailed feature attribution explanation from a SHAP summary plot image, "
+        "based on a user-defined prediction target (e.g., life expectancy, credit risk, etc.) "
+        "using Gemini 2.5 Flash."
+    )
+    args_schema: type = ShapVisionToolSchema
+    metadata: dict = {}
+
+    def _run(self, target_variable: str, image_path: str, prompt: Optional[str] = None) -> str:
+        target_variable = target_variable.strip()
+
+        api_key = self.metadata.get("GEMINI_API_KEY")
+        if not api_key:
+            raise ValueError("GEMINI_API_KEY not found in metadata.")
+        client = genai.Client(api_key=api_key)
+
+        system_prompt = (
+            "You are a world-class explainable AI (XAI) researcher with deep expertise in interpreting SHAP summary plots. "
+            "You are known for your ability to translate dense SHAP visualizations into clear, insightful, and technically grounded explanations."
+        )
+
+        if prompt is None:
+            prompt = textwrap.dedent(f"""
+                You have been given a SHAP summary plot image that visualizes how different features impact the predictions of a model trained to estimate **{target_variable}**.
+
+                Your task is to analyze this SHAP summary plot and produce a detailed written report that includes:
+
+                1. **What the SHAP summary plot represents**, including color meaning, axis explanation, and general structure.
+                2. **The most important features** in determining {target_variable}, based on the plot.
+                3. **Direction of influence** for each top feature (e.g., high values of poverty_rate decrease predicted {target_variable}).
+                4. **Shape, spread, and variability** of SHAP distributions for top features (e.g., stable effect vs. heterogeneous impact).
+                5. **Interesting patterns** (e.g., non-linear effects, counterintuitive findings, wide spreads, or sharp clusters).
+                6. **Interpretation of results** in real-world terms (socioeconomic, environmental, or demographic implications).
+                7. **Caveats and limitations** in interpreting SHAP summary plots.
+
+                Be analytical, structured, and use your expertise to interpret the image intelligently, not just describe it. Write the output as if preparing it for a technical report or presentation.
+            """)
+
+        ext = os.path.splitext(image_path)[-1].lower()
+        if ext == ".png":
+            mime_type = "image/png"
+        elif ext in [".jpg", ".jpeg"]:
+            mime_type = "image/jpeg"
+        else:
+            raise ValueError(f"Unsupported image type: {ext}")
+
+        with open(image_path, "rb") as f:
+            image_bytes = f.read()
+
+        parts = [
+            Part.from_bytes(data=image_bytes, mime_type=mime_type),
+            prompt
+        ]
+
+        response = client.models.generate_content(
+            model="gemini-2.5-flash",
+            contents=parts,
+            config=GenerateContentConfig(
+                system_instruction=system_prompt,
+                temperature=0.4,
+                max_output_tokens=2048
+            )
+        )
+
+        return response.text.strip()

src/tools_loader.py

@@ -0,0 +1,16 @@
+import os
+from pathlib import Path
+from .tools.shap_vision_tool import ShapVisionTool # Import SHAP vision tool
+
+def get_tools():
+    """Create and return all configured tools"""
+    
+    # Get paths and API keys
+    groq_key = os.getenv("GROQ_API_KEY")              # Retrieve GROQ API key from environment
+    gemini_key = os.getenv("GEMINI_API_KEY")          # Retrieve Gemini API key from environment
+    
+    # Create tool
+    shap_tool = ShapVisionTool(metadata={"GEMINI_API_KEY": gemini_key})  # Initialize SHAP vision tool with Gemini API key
+    
+    # Return all tools in a dictionary
+    return {"vision_tool": shap_tool}