aimodelshare 0.1.21__py3-none-any.whl → 0.1.62__py3-none-any.whl

aimodelshare/moral_compass/apps/tutorial.py

@@ -0,0 +1,198 @@
+"""
+Tutorial Gradio application for onboarding users to the Justice & Equity Challenge.
+
+This app teaches:
+1. How to advance slideshow-style steps
+2. How to interact with sliders/buttons
+3. How model prediction output appears
+
+Structure:
+- Factory function `create_tutorial_app()` returns a Gradio Blocks object
+- Convenience wrapper `launch_tutorial_app()` launches it inline (for notebooks)
+"""
+import contextlib
+import os
+
+
+def _build_synthetic_model():
+    """Build a tiny linear regression model on synthetic study habit data."""
+    import numpy as np
+    from sklearn.linear_model import LinearRegression
+
+    rng = np.random.default_rng(7)
+    n = 200
+    hours_study = rng.uniform(0, 12, n)
+    hours_sleep = rng.uniform(4, 10, n)
+    attendance = rng.uniform(50, 100, n)
+    exam_score = 5 * hours_study + 3 * hours_sleep + 0.5 * attendance + rng.normal(0, 10, n)
+
+    X = np.column_stack([hours_study, hours_sleep, attendance])
+    y = exam_score
+    lin_reg = LinearRegression().fit(X, y)
+
+    def predict_exam(sl, slp, att):
+        pred = float(lin_reg.predict([[sl, slp, att]])[0])
+        import numpy as np
+        pred = float(np.clip(pred, 0, 100))
+        return f"{round(pred, 1)}%"
+
+    return predict_exam
+
+
+def create_tutorial_app(theme_primary_hue: str = "indigo") -> "gr.Blocks":
+    """Create the tutorial Gradio Blocks app (not launched yet)."""
+    try:
+        import gradio as gr
+    except ImportError as e:
+        raise ImportError(
+            "Gradio is required for the tutorial app. Install with `pip install gradio`."
+        ) from e
+
+    predict_exam = _build_synthetic_model()
+
+    css = """
+    #prediction_output_textbox textarea {
+        font-size: 2.5rem !important;
+        font-weight: bold !important;
+        color: #1E40AF !important;
+        text-align: center !important;
+    }
+    """
+
+    with gr.Blocks(theme=gr.themes.Soft(primary_hue=theme_primary_hue), css=css) as demo:
+        gr.Markdown("<h1 style='text-align:center;'>👋 How to Use an App (A Quick Tutorial)</h1>")
+        gr.Markdown(
+            """
+            <div style='text-align:left; font-size:20px; max-width: 800px; margin: auto;
+                        padding: 15px; background-color: #f7f7f7; border-radius: 8px;'>
+            This is a simple, 3-step tutorial.<br><br>
+            <b>Your Task:</b> Just read the instructions for each step and click the "Next" button to continue.
+            </div>
+            """
+        )
+        gr.HTML("<hr style='margin:24px 0;'>")
+
+        # Step 1
+        with gr.Column(visible=True) as step_1_container:
+            gr.Markdown("<h2 style='text-align:center;'>Step 1: How to Use \"Slideshows\"</h2>")
+            gr.Markdown(
+                """
+                <div style='font-size: 28px; text-align: center; background:#E3F2FD;
+                             padding:28px; border-radius:16px; min-height: 150px;'>
+                  <b>This is a "Slideshow" step.</b><br><br>
+                  Some apps are just for reading. Your only task is to click the "Next" button to move to the next step.
+                </div>
+                """
+            )
+            step_1_next = gr.Button("Next Step ▶️", variant="primary")
+
+        # Step 2
+        with gr.Column(visible=False) as step_2_container:
+            gr.Markdown("<h2 style='text-align:center;'>Step 2: How to Use \"Interactive Demos\"</h2>")
+            gr.Markdown(
+                """
+                <div style='font-size: 20px; text-align: left; background:#FFF3E0;
+                            padding:20px; border-radius:16px;'>
+                  <b>This is an "Interactive Demo."</b><br><br>
+                  Just follow the numbered steps below (from top to bottom) to see how it works!
+                </div>
+                """
+            )
+            gr.HTML("<br>")
+            gr.Markdown(
+                """
+                <div style="font-size: 24px; text-align:left; padding-left: 10px;">
+                  <b>[ 1 ] Use these sliders to change the inputs.</b>
+                </div>
+                """
+            )
+            s_hours = gr.Slider(0, 12, step=0.5, value=6, label="Hours Studied per Week")
+            s_sleep = gr.Slider(4, 10, step=0.5, value=7, label="Hours of Sleep per Night")
+            s_att = gr.Slider(50, 100, step=1, value=90, label="Class Attendance %")
+
+            gr.HTML("<hr style='margin: 20px 0;'>")
+
+            gr.Markdown(
+                """
+                <div style="font-size: 24px; text-align:left; padding-left: 10px;">
+                  <b>[ 2 ] Click this button to run.</b>
+                </div>
+                """
+            )
+            with gr.Row():
+                gr.HTML(visible=False)
+                go = gr.Button("🔮 Predict", variant="primary", scale=2)
+                gr.HTML(visible=False)
+
+            gr.HTML("<hr style='margin: 20px 0;'>")
+
+            gr.Markdown(
+                """
+                <div style="font-size: 24px; text-align:left; padding-left: 10px;">
+                  <b>[ 3 ] See the result here!</b>
+                </div>
+                """
+            )
+            out = gr.Textbox(
+                label="🔮 Predicted Exam Score", elem_id="prediction_output_textbox", interactive=False
+            )
+            go.click(predict_exam, [s_hours, s_sleep, s_att], out)
+
+            gr.HTML("<hr style='margin: 15px 0;'>")
+            with gr.Row():
+                step_2_back = gr.Button("◀️ Back")
+                step_2_next = gr.Button("Finish Tutorial ▶️", variant="primary")
+
+        # Step 3
+        with gr.Column(visible=False) as step_3_container:
+            gr.Markdown(
+                """
+                <div style='text-align:center;'>
+                  <h2 style='text-align:center; font-size: 2.5rem;'>✅ Tutorial Complete!</h2>
+                  <div style='font-size: 1.5rem; background:#E8F5E9; padding:28px; border-radius:16px;
+                              border: 2px solid #4CAF50;'>
+                    You've mastered the basics!<br><br>
+                    Your next step is <b>outside</b> this app window.<br><br>
+                    <h1 style='margin:0; font-size: 3rem;'>👇 SCROLL DOWN 👇</h1><br>
+                    Look below this app to find <b>Section 3</b> and begin the challenge!
+                  </div>
+                </div>
+                """
+            )
+            with gr.Row():
+                step_3_back = gr.Button("◀️ Back")
+
+        # Visibility logic (correct ordering & syntax)
+        step_1_next.click(
+            lambda: (gr.update(visible=False), gr.update(visible=True), gr.update(visible=False)),
+            inputs=None,
+            outputs=[step_1_container, step_2_container, step_3_container],
+        )
+        step_2_back.click(
+            lambda: (gr.update(visible=True), gr.update(visible=False), gr.update(visible=False)),
+            inputs=None,
+            outputs=[step_1_container, step_2_container, step_3_container],
+        )
+        step_2_next.click(
+            lambda: (gr.update(visible=False), gr.update(visible=False), gr.update(visible=True)),
+            inputs=None,
+            outputs=[step_1_container, step_2_container, step_3_container],
+        )
+        step_3_back.click(
+            lambda: (gr.update(visible=False), gr.update(visible=True), gr.update(visible=False)),
+            inputs=None,
+            outputs=[step_1_container, step_2_container, step_3_container],
+        )
+
+    return demo
+
+
+def launch_tutorial_app(height: int = 950, share: bool = False, debug: bool = False) -> None:
+    """Convenience wrapper to create and launch the tutorial app inline."""
+    demo = create_tutorial_app()
+    try:
+        import gradio as gr  # noqa: F401
+    except ImportError as e:
+        raise ImportError("Gradio must be installed to launch the tutorial app.") from e
+    with contextlib.redirect_stdout(open(os.devnull, 'w')), contextlib.redirect_stderr(open(os.devnull, 'w')):
+        demo.launch(share=share, inline=True, debug=debug, height=height)

aimodelshare/moral_compass/challenge.py

@@ -0,0 +1,365 @@
+"""
+Challenge Manager for Moral Compass system.
+
+Provides a local state manager for tracking multi-metric progress
+and syncing with the Moral Compass API.
+"""
+
+from typing import Dict, Optional, List
+from dataclasses import dataclass
+from .api_client import MoralcompassApiClient
+
+
+@dataclass
+class Question:
+    """Represents a challenge question"""
+    id: str
+    text: str
+    options: List[str]
+    correct_index: int
+
+
+@dataclass
+class Task:
+    """Represents a challenge task"""
+    id: str
+    title: str
+    description: str
+    questions: List[Question]
+
+
+class JusticeAndEquityChallenge:
+    """
+    Justice & Equity Challenge with predefined tasks and questions.
+    
+    Contains 6 tasks (A-F) with associated questions for teaching
+    ethical AI principles related to fairness and bias.
+    """
+    
+    def __init__(self):
+        """Initialize the Justice & Equity Challenge with tasks A-F"""
+        self.tasks = [
+            Task(
+                id="A",
+                title="Understanding Algorithmic Bias",
+                description="Learn about different types of bias in AI systems",
+                questions=[
+                    Question(
+                        id="A1",
+                        text="What is algorithmic bias?",
+                        options=[
+                            "Bias in the training data",
+                            "Systematic and repeatable errors in computer systems",
+                            "User preference bias",
+                            "Network latency bias"
+                        ],
+                        correct_index=1
+                    )
+                ]
+            ),
+            Task(
+                id="B",
+                title="Identifying Protected Attributes",
+                description="Understanding which attributes require fairness considerations",
+                questions=[
+                    Question(
+                        id="B1",
+                        text="Which is a protected attribute in fairness?",
+                        options=[
+                            "Email address",
+                            "Race or ethnicity",
+                            "Browser type",
+                            "Screen resolution"
+                        ],
+                        correct_index=1
+                    )
+                ]
+            ),
+            Task(
+                id="C",
+                title="Measuring Disparate Impact",
+                description="Learn to measure fairness using statistical metrics",
+                questions=[
+                    Question(
+                        id="C1",
+                        text="What is disparate impact?",
+                        options=[
+                            "Equal outcome rates across groups",
+                            "Different outcome rates for different groups",
+                            "Same prediction accuracy",
+                            "Uniform data distribution"
+                        ],
+                        correct_index=1
+                    )
+                ]
+            ),
+            Task(
+                id="D",
+                title="Evaluating Model Fairness",
+                description="Apply fairness metrics to assess model performance",
+                questions=[
+                    Question(
+                        id="D1",
+                        text="What does equal opportunity mean?",
+                        options=[
+                            "Same accuracy for all groups",
+                            "Equal true positive rates across groups",
+                            "Equal false positive rates",
+                            "Same number of predictions"
+                        ],
+                        correct_index=1
+                    )
+                ]
+            ),
+            Task(
+                id="E",
+                title="Mitigation Strategies",
+                description="Explore techniques to reduce algorithmic bias",
+                questions=[
+                    Question(
+                        id="E1",
+                        text="Which is a bias mitigation technique?",
+                        options=[
+                            "Ignore protected attributes",
+                            "Reweighting training samples",
+                            "Use more servers",
+                            "Faster algorithms"
+                        ],
+                        correct_index=1
+                    )
+                ]
+            ),
+            Task(
+                id="F",
+                title="Ethical Deployment",
+                description="Best practices for deploying fair AI systems",
+                questions=[
+                    Question(
+                        id="F1",
+                        text="What is essential for ethical AI deployment?",
+                        options=[
+                            "Fastest inference time",
+                            "Continuous monitoring and auditing",
+                            "Most complex model",
+                            "Largest dataset"
+                        ],
+                        correct_index=1
+                    )
+                ]
+            )
+        ]
+    
+    @property
+    def total_tasks(self) -> int:
+        """Total number of tasks in the challenge"""
+        return len(self.tasks)
+    
+    @property
+    def total_questions(self) -> int:
+        """Total number of questions across all tasks"""
+        return sum(len(task.questions) for task in self.tasks)
+
+
+class ChallengeManager:
+    """
+    Manages local state for a user's challenge progress with multiple metrics.
+    
+    Features:
+    - Track arbitrary metrics (accuracy, fairness, robustness, etc.)
+    - Specify primary metric for scoring
+    - Track task and question progress
+    - Local preview of moral compass score
+    - Sync to server via API
+    """
+    
+    def __init__(self, table_id: str, username: str, api_client: Optional[MoralcompassApiClient] = None, 
+                 challenge: Optional[JusticeAndEquityChallenge] = None):
+        """
+        Initialize a challenge manager.
+        
+        Args:
+            table_id: The table identifier
+            username: The username
+            api_client: Optional API client instance (creates new one if None)
+            challenge: Optional challenge instance (creates JusticeAndEquityChallenge if None)
+        """
+        self.table_id = table_id
+        self.username = username
+        self.api_client = api_client or MoralcompassApiClient()
+        self.challenge = challenge or JusticeAndEquityChallenge()
+        
+        # Metrics state
+        self.metrics: Dict[str, float] = {}
+        self.primary_metric: Optional[str] = None
+        
+        # Progress state - initialize with challenge totals
+        self.tasks_completed: int = 0
+        self.total_tasks: int = self.challenge.total_tasks
+        self.questions_correct: int = 0
+        self.total_questions: int = self.challenge.total_questions
+        
+        # Track completed tasks and answers
+        self._completed_task_ids: set = set()
+        self._answered_questions: Dict[str, int] = {}  # question_id -> selected_index
+    
+    def set_metric(self, name: str, value: float, primary: bool = False) -> None:
+        """
+        Set a metric value.
+        
+        Args:
+            name: Metric name (e.g., 'accuracy', 'fairness', 'robustness')
+            value: Metric value (should be between 0 and 1 typically)
+            primary: If True, sets this as the primary metric for scoring
+        """
+        self.metrics[name] = value
+        
+        if primary:
+            self.primary_metric = name
+    
+    def set_progress(self, tasks_completed: int = 0, total_tasks: int = 0,
+                    questions_correct: int = 0, total_questions: int = 0) -> None:
+        """
+        Set progress counters.
+        
+        Args:
+            tasks_completed: Number of tasks completed
+            total_tasks: Total number of tasks
+            questions_correct: Number of questions answered correctly
+            total_questions: Total number of questions
+        """
+        self.tasks_completed = tasks_completed
+        self.total_tasks = total_tasks
+        self.questions_correct = questions_correct
+        self.total_questions = total_questions
+    
+    def complete_task(self, task_id: str) -> None:
+        """
+        Mark a task as completed.
+        
+        Args:
+            task_id: The task identifier (e.g., 'A', 'B', 'C')
+        """
+        if task_id not in self._completed_task_ids:
+            self._completed_task_ids.add(task_id)
+            self.tasks_completed = len(self._completed_task_ids)
+    
+    def answer_question(self, task_id: str, question_id: str, selected_index: int) -> bool:
+        """
+        Record an answer to a question.
+        
+        Args:
+            task_id: The task identifier
+            question_id: The question identifier
+            selected_index: The index of the selected answer
+            
+        Returns:
+            True if the answer is correct, False otherwise
+        """
+        # Find the question
+        question = None
+        for task in self.challenge.tasks:
+            if task.id == task_id:
+                for q in task.questions:
+                    if q.id == question_id:
+                        question = q
+                        break
+                break
+        
+        if question is None:
+            raise ValueError(f"Question {question_id} not found in task {task_id}")
+        
+        # Record the answer
+        self._answered_questions[question_id] = selected_index
+        
+        # Check if correct and update counter
+        is_correct = (selected_index == question.correct_index)
+        
+        # Recalculate questions_correct
+        self.questions_correct = sum(
+            1 for qid, idx in self._answered_questions.items()
+            if self._is_answer_correct(qid, idx)
+        )
+        
+        return is_correct
+    
+    def _is_answer_correct(self, question_id: str, selected_index: int) -> bool:
+        """Check if an answer is correct"""
+        for task in self.challenge.tasks:
+            for q in task.questions:
+                if q.id == question_id:
+                    return selected_index == q.correct_index
+        return False
+    
+    def get_progress_summary(self) -> Dict:
+        """
+        Get a summary of current progress.
+        
+        Returns:
+            Dictionary with progress information including local score preview
+        """
+        return {
+            'tasksCompleted': self.tasks_completed,
+            'totalTasks': self.total_tasks,
+            'questionsCorrect': self.questions_correct,
+            'totalQuestions': self.total_questions,
+            'metrics': self.metrics.copy(),
+            'primaryMetric': self.primary_metric,
+            'localScorePreview': self.get_local_score()
+        }
+    
+    def get_local_score(self) -> float:
+        """
+        Calculate moral compass score locally without syncing to server.
+        
+        Returns:
+            Moral compass score based on current state
+        """
+        if not self.metrics:
+            return 0.0
+        
+        # Determine primary metric
+        primary_metric = self.primary_metric
+        if primary_metric is None:
+            if 'accuracy' in self.metrics:
+                primary_metric = 'accuracy'
+            else:
+                primary_metric = sorted(self.metrics.keys())[0]
+        
+        primary_value = self.metrics.get(primary_metric, 0.0)
+        
+        # Calculate progress ratio
+        progress_denominator = self.total_tasks + self.total_questions
+        if progress_denominator == 0:
+            return 0.0
+        
+        progress_ratio = (self.tasks_completed + self.questions_correct) / progress_denominator
+        
+        return primary_value * progress_ratio
+    
+    def sync(self) -> Dict:
+        """
+        Sync current state to the Moral Compass API.
+        
+        Returns:
+            API response dict with moralCompassScore and other fields
+        """
+        if not self.metrics:
+            raise ValueError("No metrics set. Use set_metric() before syncing.")
+        
+        return self.api_client.update_moral_compass(
+            table_id=self.table_id,
+            username=self.username,
+            metrics=self.metrics,
+            tasks_completed=self.tasks_completed,
+            total_tasks=self.total_tasks,
+            questions_correct=self.questions_correct,
+            total_questions=self.total_questions,
+            primary_metric=self.primary_metric
+        )
+    
+    def __repr__(self) -> str:
+        return (
+            f"ChallengeManager(table_id={self.table_id!r}, username={self.username!r}, "
+            f"metrics={self.metrics}, primary_metric={self.primary_metric!r}, "
+            f"local_score={self.get_local_score():.4f})"
+        )