app.py

"""
AI-Assisted Decision-Making Study — Cloud Version
====================================================
One deployed app / one shared link. Each participant works through a fixed
set of questions (task instances from profiles.csv), each following the
3-step procedure:
  Step 1: initial prediction + confidence
  Step 2: see the AI's prediction + confidence
  Step 3: final prediction + confidence

Participants cannot advance without explicitly answering both questions in
each step (nothing is pre-selected). All answers are logged to a Google
Sheet, including the Question No., as each question is completed.

See README.md for full setup steps (Google Sheets credentials, GitHub,
Streamlit Community Cloud deployment).
"""

import os
from datetime import datetime
import hashlib

import pandas as pd
import streamlit as st

# ============================================================
# CONFIG — edit these for your study
# ============================================================
PROFILES_PATH = "profiles.csv"     # one row per question/task instance
LABEL_OPTIONS = ["<=50K", ">50K"]  # change to match your task's outcome labels
CONFIDENCE_MIN, CONFIDENCE_MAX = 50, 100

RESULTS_DIR = "results"  # only used as a local fallback if Google Sheets isn't configured
os.makedirs(RESULTS_DIR, exist_ok=True)

DATA_BACKEND = "gsheet" if "gcp_service_account" in st.secrets else "csv"

# Column order for every logged row
LOG_COLUMNS = [
    "participant_id", "question_no", "profile_id", "true_label",
    "initial_pred", "initial_conf",
    "ai_pred", "ai_conf",
    "final_pred", "final_conf",
    "timestamp_step1", "timestamp_step2", "timestamp_step3",
]


# ============================================================
# Google Sheets logging (falls back to local CSV if secrets aren't set)
# ============================================================
@st.cache_resource
def _get_gsheet():
    import gspread
    from google.oauth2.service_account import Credentials

    scopes = ["https://www.googleapis.com/auth/spreadsheets"]
    creds = Credentials.from_service_account_info(
        st.secrets["gcp_service_account"], scopes=scopes
    )
    client = gspread.authorize(creds)
    sheet = client.open_by_key(st.secrets["sheet_id"]).sheet1
    if sheet.row_count == 0 or not sheet.row_values(1):
        sheet.append_row(LOG_COLUMNS)
    return sheet


def append_row(trial: dict):
    row = [trial.get(col, "") for col in LOG_COLUMNS]
    if DATA_BACKEND == "gsheet":
        _get_gsheet().append_row(row, value_input_option="RAW")
    else:
        path = os.path.join(RESULTS_DIR, f"participant_{trial['participant_id']}.csv")
        df = pd.DataFrame([row], columns=LOG_COLUMNS)
        header = not os.path.exists(path)
        df.to_csv(path, mode="a", header=header, index=False)


def get_completed_count(pid: str) -> int:
    """How many questions this participant ID has already answered.
    0 for a brand-new participant. Used to block re-entry after finishing,
    and to resume correctly if their browser refreshes mid-study."""
    if DATA_BACKEND == "gsheet":
        records = _get_gsheet().get_all_records()
        return sum(1 for r in records if str(r.get("participant_id")) == str(pid))
    else:
        path = os.path.join(RESULTS_DIR, f"participant_{pid}.csv")
        return len(pd.read_csv(path)) if os.path.exists(path) else 0


def stable_seed(pid: str) -> int:
    """Deterministic per-participant seed (stable across app restarts,
    unlike Python's built-in hash()) used to fix each participant's question
    order so a resumed session sees the same order as before."""
    return int(hashlib.sha256(str(pid).encode()).hexdigest(), 16) % (2**32)


# ============================================================
# >>> PLUG YOUR MODEL IN HERE <<<
# ============================================================
def get_ai_prediction(profile_row: pd.Series):
    """
    Replace this with a call to your actual model.
    `profile_row` = one row of profiles.csv (the current question's features).
    Must return (prediction_label, confidence) where confidence is in [0.5, 1.0].
    """
    import random
    pred = random.choice(LABEL_OPTIONS)
    conf = random.uniform(0.55, 0.99)
    return pred, conf


# ============================================================
# App state
# ============================================================
def load_profiles():
    return pd.read_csv(PROFILES_PATH)


def init_session():
    defaults = {
        "participant_id": None,
        "profiles": None,
        "q_idx": 0,       # which question (0-based)
        "step": 1,        # which of the 3 steps
        "current": {},    # answers collected so far for the current question
    }
    for k, v in defaults.items():
        if k not in st.session_state:
            st.session_state[k] = v


st.set_page_config(page_title="AI-Assisted Decision Task", layout="centered")
init_session()

# ---------------- Landing screen ----------------
if st.session_state.participant_id is None:
    st.title("AI-Assisted Decision-Making Study")

    url_pid = st.query_params.get("pid")
    if url_pid:
        pid = url_pid
        st.write(f"Participant ID: **{pid}**")
        confirmed = st.button("Start", type="primary")
    else:
        st.write("Please enter your participant ID to begin.")
        pid = st.text_input("Participant ID")
        confirmed = st.button("Start", type="primary") and bool(pid)

    if confirmed:
        all_profiles = load_profiles()
        completed = get_completed_count(pid)

        if completed >= len(all_profiles):
            st.error("This participant ID has already completed the study.")
            st.stop()

        st.session_state.participant_id = pid
        st.session_state.profiles = all_profiles.sample(
            frac=1, random_state=stable_seed(pid)
        ).reset_index(drop=True)
        if completed > 0:
            st.session_state.q_idx = completed
            st.toast(f"Resuming from question {completed + 1}.")
        st.rerun()
    st.stop()

profiles = st.session_state.profiles
q_idx = st.session_state.q_idx
question_no = q_idx + 1  # 1-based, shown to participant and logged

# ---------------- End of study ----------------
if q_idx >= len(profiles):
    st.title("Task complete — thank you!")
    st.success("Your responses have been recorded. You may close this window.")
    st.stop()

row = profiles.iloc[q_idx]
feature_cols = [c for c in profiles.columns if c not in ("id", "true_label")]

col_profile, col_task = st.columns([1, 2])

with col_profile:
    st.caption(f"Question {question_no} of {len(profiles)}")
    st.subheader("The Profile")
    st.table(row[feature_cols].rename("value"))

with col_task:
    # ---------------- STEP 1 ----------------
    if st.session_state.step == 1:
        st.header("Step 1: Make your prediction")

        pred = st.radio(
            "Q1. What is your prediction?",
            LABEL_OPTIONS,
            index=None,  # nothing pre-selected — participant must actively choose
            key=f"pred1_{q_idx}",
        )
        conf = st.slider(
            "Q2. What is your confidence in your prediction?",
            CONFIDENCE_MIN, CONFIDENCE_MAX, CONFIDENCE_MIN,
            key=f"conf1_{q_idx}",
            help="50 = Not sure, 100 = Very sure. Drag the slider to answer.",
        )

        ready = pred is not None
        if not ready:
            st.caption("Please select a prediction above to continue.")
        if st.button("Next", type="primary", disabled=not ready):
            st.session_state.current = {
                "participant_id": st.session_state.participant_id,
                "question_no": question_no,
                "profile_id": row.get("id", question_no),
                "true_label": row.get("true_label", ""),
                "initial_pred": pred,
                "initial_conf": conf,
                "timestamp_step1": datetime.now().isoformat(timespec="seconds"),
            }
            st.session_state.step = 2
            st.rerun()

    # ---------------- STEP 2 ----------------
    elif st.session_state.step == 2:
        st.header("Step 2: See AI's suggestion")
        trial = st.session_state.current

        st.markdown(
            f"**Your prediction:** {trial['initial_pred']}  \n"
            f"**Your confidence:** {trial['initial_conf']}%"
        )

        if "ai_pred" not in trial:
            ai_pred, ai_conf = get_ai_prediction(row)
            trial["ai_pred"] = ai_pred
            trial["ai_conf"] = ai_conf

        st.markdown(
            f"**AI's prediction:** {trial['ai_pred']}  \n"
            f"**AI's confidence:** {trial['ai_conf'] * 100:.0f}%"
        )

        if st.button("Continue to final decision", type="primary"):
            trial["timestamp_step2"] = datetime.now().isoformat(timespec="seconds")
            st.session_state.step = 3
            st.rerun()

    # ---------------- STEP 3 ----------------
    elif st.session_state.step == 3:
        st.header("Step 3: Make the final decision")
        trial = st.session_state.current

        final_pred = st.radio(
            "What is your final prediction?",
            LABEL_OPTIONS,
            index=None,
            key=f"pred3_{q_idx}",
        )
        final_conf = st.slider(
            "Your confidence in your final prediction",
            CONFIDENCE_MIN, CONFIDENCE_MAX, CONFIDENCE_MIN,
            key=f"conf3_{q_idx}",
        )

        ready = final_pred is not None
        if not ready:
            st.caption("Please select a final prediction above to finish this item.")
        if st.button("Finish and next", type="primary", disabled=not ready):
            trial["final_pred"] = final_pred
            trial["final_conf"] = final_conf
            trial["timestamp_step3"] = datetime.now().isoformat(timespec="seconds")

            append_row(trial)

            st.session_state.q_idx += 1
            st.session_state.step = 1
            st.session_state.current = {}
            st.rerun()