Initial commit: HF Spaces Fraud Detector scaffold

.env.example

@@ -0,0 +1,9 @@
+HF_TOKEN=hf_xxx
+SENDGRID_API_KEY=
+EMAIL_HOST=smtp.gmail.com
+EMAIL_PORT=587
+EMAIL_USER=
+EMAIL_PASS=
+SLACK_WEBHOOK=
+ADMIN_EMAIL=you@example.com
+QWEN_MODEL_ID=

.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+env/
+.env
+/data/*
+*.db
+*.sqlite
+*.pdf
+*.csv

README.md

@@ -0,0 +1,21 @@
+# Fraud Detector Agent — HF Spaces (Gradio) scaffold
+
+This repo is a deployable Hugging Face Space using Gradio + LangChain-style orchestration for transaction fraud detection.
+
+FEATURES
+- Multi-model inference (Hugging Face Inference API)
+- Velocity (burst) detection
+- Chroma vector store + sentence-transformers embeddings for RAG
+- Per-user SQLite storage (register/login)
+- CSV & PDF export of flagged results
+- Email & Slack alerts hooks
+
+Secrets needed in Space Settings:
+- HF_TOKEN
+- SENDGRID_API_KEY (or EMAIL_USER/EMAIL_PASS)
+- SLACK_WEBHOOK (optional)
+- ADMIN_EMAIL (optional)
+
+Deploy:
+- Create new Space on Hugging Face, choose `Gradio` Python.
+- Push repository files, set secrets, wait for build to complete.

alerts.py

@@ -0,0 +1,68 @@
+import os
+import smtplib
+from email.message import EmailMessage
+import requests
+
+SENDGRID_API_KEY = os.getenv("SENDGRID_API_KEY", "")
+EMAIL_USER = os.getenv("EMAIL_USER", "")
+EMAIL_PASS = os.getenv("EMAIL_PASS", "")
+EMAIL_HOST = os.getenv("EMAIL_HOST", "smtp.gmail.com")
+EMAIL_PORT = int(os.getenv("EMAIL_PORT", 587))
+SLACK_WEBHOOK = os.getenv("SLACK_WEBHOOK", "")
+ADMIN_EMAIL = os.getenv("ADMIN_EMAIL", "")
+
+class EmailNotifier:
+    def __init__(self):
+        pass
+
+    def send_alert(self, recipient: str, subject: str, body: str, attachment: str = None) -> bool:
+        if SENDGRID_API_KEY:
+            try:
+                import sendgrid
+                from sendgrid.helpers.mail import Mail, Attachment, FileContent, FileName, FileType, Disposition
+                sg = sendgrid.SendGridAPIClient(SENDGRID_API_KEY)
+                message = Mail(from_email=EMAIL_USER or "noreply@example.com", to_emails=recipient, subject=subject, plain_text_content=body)
+                if attachment and os.path.exists(attachment):
+                    with open(attachment, "rb") as f:
+                        data = f.read()
+                    import base64
+                    encoded = base64.b64encode(data).decode()
+                    attachedFile = Attachment(FileContent(encoded), FileName(os.path.basename(attachment)), FileType("application/pdf"), Disposition("attachment"))
+                    message.attachment = attachedFile
+                sg.send(message)
+                return True
+            except Exception as e:
+                print("SendGrid error:", e)
+        try:
+            msg = EmailMessage()
+            msg["Subject"] = subject
+            msg["From"] = EMAIL_USER or "noreply@example.com"
+            msg["To"] = recipient
+            msg.set_content(body)
+            if attachment and os.path.exists(attachment):
+                with open(attachment, "rb") as f:
+                    data = f.read()
+                msg.add_attachment(data, maintype="application", subtype="pdf", filename=os.path.basename(attachment))
+            with smtplib.SMTP(EMAIL_HOST, EMAIL_PORT) as server:
+                server.starttls()
+                if EMAIL_USER and EMAIL_PASS:
+                    server.login(EMAIL_USER, EMAIL_PASS)
+                server.send_message(msg)
+            return True
+        except Exception as e:
+            print("SMTP send error:", e)
+            return False
+
+class SlackNotifier:
+    def __init__(self, webhook_url: str):
+        self.webhook = webhook_url
+
+    def send(self, text: str):
+        if not self.webhook:
+            return False
+        try:
+            requests.post(self.webhook, json={"text": text}, timeout=10)
+            return True
+        except Exception as e:
+            print("Slack send error:", e)
+            return False

app.py

@@ -0,0 +1,166 @@
+import os
+import json
+import tempfile
+from datetime import datetime
+import pandas as pd
+import gradio as gr
+
+# local modules
+from database import DatabaseManager
+from models import ModelRouter
+from velocity import detect_burst
+from export_utils import generate_csv_report, generate_pdf_report
+from alerts import EmailNotifier, SlackNotifier
+from rag import RAGStore
+
+# config from env
+HF_TOKEN = os.getenv("HF_TOKEN", "")
+ADMIN_EMAIL = os.getenv("ADMIN_EMAIL", "")
+SLACK_WEBHOOK = os.getenv("SLACK_WEBHOOK", "")
+
+# initialize components (persistent storage under /data)
+DATA_DIR = "/data"
+os.makedirs(DATA_DIR, exist_ok=True)
+DB_PATH = os.path.join(DATA_DIR, "fraud_detector.db")
+VECTOR_DIR = os.path.join(DATA_DIR, "chroma_collection")
+
+db = DatabaseManager(DB_PATH)
+rag = RAGStore(collection_dir=VECTOR_DIR)
+model_router = ModelRouter(hf_token=HF_TOKEN)
+emailer = EmailNotifier()
+slacknot = SlackNotifier(SLACK_WEBHOOK) if SLACK_WEBHOOK else None
+
+# simple in-memory session (for demo only)
+SESSIONS = {}
+
+def register_user(username: str, password: str, email: str):
+    ok = db.create_user(username=username, password=password, email=email)
+    return "Registered" if ok else "Registration failed (username taken)."
+
+def login_user(username: str, password: str):
+    user_id = db.authenticate_user(username, password)
+    if user_id:
+        token = f"session-{user_id}-{int(datetime.utcnow().timestamp())}"
+        SESSIONS[token] = user_id
+        return token, f"Logged in as {username}"
+    else:
+        return "", "Invalid credentials"
+
+def process_file(session_token: str, file, rag_query: str = ""):
+    if session_token not in SESSIONS:
+        return "Please log in", {}, {}, ""
+    user_id = SESSIONS[session_token]
+    try:
+        df = pd.read_csv(file.name)
+    except Exception as e:
+        return f"Error reading CSV: {e}", {}, {}, ""
+
+    # Basic validation
+    required_cols = {"transaction_id", "timestamp", "amount", "description", "merchant"}
+    if not required_cols.issubset(set(df.columns)):
+        return f"CSV missing required columns: {required_cols}", {}, {}, ""
+
+    # store transactions
+    db.store_transactions(user_id, df)
+
+    # add to RAG (texts + metadata)
+    texts = df.apply(lambda x: f"txn_id:{x['transaction_id']} amount:{x['amount']} merchant:{x['merchant']} desc:{x.get('description','')}", axis=1).tolist()
+    metadatas = df.to_dict(orient="records")
+    rag.add(texts=texts, metadatas=metadatas)
+
+    # velocity detection
+    velocity_flags = detect_burst(df, window_minutes=10, threshold=5)
+
+    # run simple anomaly detection (z-score based) — small helper
+    amount_flags = []
+    if len(df) > 5:
+        mean = df['amount'].mean()
+        std = df['amount'].std()
+        for _, row in df.iterrows():
+            z = abs((row['amount'] - mean) / (std if std > 0 else 1))
+            if z > 2.5 or row['amount'] > 1000:
+                amount_flags.append({
+                    "transaction": row.to_dict(),
+                    "z_score": float(z),
+                    "risk_factor": "amount_anomaly",
+                    "risk_score": min(z/3.0, 1.0)
+                })
+
+    all_flagged = velocity_flags + amount_flags
+
+    # RAG lookup if requested
+    rag_results = []
+    if rag_query:
+        rag_results = rag.query(rag_query, k=5)
+
+    # Prepare prompt context
+    context = {
+        "num_transactions": len(df),
+        "velocity_flags": len(velocity_flags),
+        "amount_flags": len(amount_flags),
+        "rag_snippets": rag_results[:3]
+    }
+    prompt = f"""
+You are a financial fraud analyst. Analyze the transactions and provide a concise report and remediation steps.
+Context: {json.dumps(context, default=str)}
+"""
+
+    # pick model via router (Ministral -> default)
+    llm_output = model_router.run(prompt, task="analysis")
+
+    # generate reports if flagged
+    report_paths = {}
+    if all_flagged:
+        ts = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
+        csv_path = os.path.join(DATA_DIR, f"fraud_report_{user_id}_{ts}.csv")
+        pdf_path = os.path.join(DATA_DIR, f"fraud_report_{user_id}_{ts}.pdf")
+        generate_csv_report(all_flagged, csv_path)
+        generate_pdf_report(all_flagged, pdf_path)
+        report_paths = {"csv": csv_path, "pdf": pdf_path}
+
+        # send alerts
+        admin = ADMIN_EMAIL
+        if admin:
+            emailer.send_alert(recipient=admin,
+                               subject=f"Fraud Alert for user {user_id}",
+                               body=f"Detected {len(all_flagged)} suspicious txns. See attached.",
+                               attachment=pdf_path)
+        if slacknot:
+            slacknot.send(f"Fraud Alert: user {user_id} has {len(all_flagged)} flagged transactions.")
+
+    return llm_output, all_flagged, report_paths, f"Found {len(all_flagged)} suspicious transactions."
+
+# Gradio UI
+with gr.Blocks(css=".output_json {height:300px;}") as demo:
+    gr.Markdown("# 🔍 Fraud Detector Analyst — HF Spaces (Gradio)")
+
+    with gr.Tab("Auth"):
+        with gr.Row():
+            reg_user = gr.Textbox(label="Username")
+            reg_pass = gr.Textbox(label="Password", type="password")
+            reg_email = gr.Textbox(label="Email")
+            reg_btn = gr.Button("Register")
+            reg_msg = gr.Textbox(label="Message", interactive=False)
+
+        with gr.Row():
+            login_user_tb = gr.Textbox(label="Username")
+            login_pass_tb = gr.Textbox(label="Password", type="password")
+            login_btn = gr.Button("Login")
+            token_out = gr.Textbox(label="Session Token", interactive=False)
+            login_msg = gr.Textbox(label="Message", interactive=False)
+
+    with gr.Tab("Analyze"):
+        session_token_tb = gr.Textbox(label="Session Token (from login)")
+        csv_file = gr.File(label="Upload transactions CSV (.csv)")
+        rag_query_tb = gr.Textbox(label="RAG Query (optional)")
+        analyze_btn = gr.Button("Analyze")
+        analysis_out = gr.Textbox(label="LLM Analysis", lines=12, interactive=False)
+        flagged_out = gr.JSON(label="Flagged Transactions")
+        reports_out = gr.JSON(label="Reports (paths)")
+
+    reg_btn.click(fn=register_user, inputs=[reg_user, reg_pass, reg_email], outputs=[reg_msg])
+    login_btn.click(fn=login_user, inputs=[login_user_tb, login_pass_tb], outputs=[token_out, login_msg])
+    analyze_btn.click(fn=process_file, inputs=[session_token_tb, csv_file, rag_query_tb], outputs=[analysis_out, flagged_out, reports_out, gr.Textbox(label="status")])
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860)

database.py

@@ -0,0 +1,77 @@
+import sqlite3
+import hashlib
+import pandas as pd
+from typing import Optional
+
+class DatabaseManager:
+    def __init__(self, db_path=":memory:"):
+        self.db_path = db_path
+        self.init_db()
+
+    def init_db(self):
+        conn = sqlite3.connect(self.db_path, check_same_thread=False)
+        cur = conn.cursor()
+        cur.execute("""
+        CREATE TABLE IF NOT EXISTS users (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            username TEXT UNIQUE,
+            password_hash TEXT,
+            email TEXT,
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        )
+        """)
+        cur.execute("""
+        CREATE TABLE IF NOT EXISTS transactions (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id INTEGER,
+            transaction_id TEXT,
+            timestamp TEXT,
+            amount REAL,
+            description TEXT,
+            merchant TEXT,
+            category TEXT,
+            is_flagged INTEGER DEFAULT 0,
+            risk_score REAL DEFAULT 0.0,
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        )
+        """)
+        conn.commit()
+        conn.close()
+
+    def create_user(self, username: str, password: str, email: str = None) -> bool:
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cur = conn.cursor()
+            pwd_hash = hashlib.sha256(password.encode()).hexdigest()
+            cur.execute("INSERT INTO users (username, password_hash, email) VALUES (?, ?, ?)", (username, pwd_hash, email))
+            conn.commit()
+            conn.close()
+            return True
+        except sqlite3.IntegrityError:
+            return False
+
+    def authenticate_user(self, username: str, password: str) -> Optional[int]:
+        conn = sqlite3.connect(self.db_path)
+        cur = conn.cursor()
+        pwd_hash = hashlib.sha256(password.encode()).hexdigest()
+        cur.execute("SELECT id FROM users WHERE username = ? AND password_hash = ?", (username, pwd_hash))
+        row = cur.fetchone()
+        conn.close()
+        return row[0] if row else None
+
+    def store_transactions(self, user_id: int, df: pd.DataFrame):
+        conn = sqlite3.connect(self.db_path)
+        df = df.copy()
+        df['user_id'] = user_id
+        df.to_sql('transactions', conn, if_exists='append', index=False)
+        conn.close()
+
+    def get_transactions(self, user_id: int, days: int = 30):
+        conn = sqlite3.connect(self.db_path)
+        cur = conn.cursor()
+        cur.execute("SELECT * FROM transactions WHERE user_id = ? ORDER BY timestamp DESC", (user_id,))
+        rows = cur.fetchall()
+        cols = [desc[0] for desc in cur.description]
+        conn.close()
+        import pandas as pd
+        return pd.DataFrame(rows, columns=cols)

export_utils.py

@@ -0,0 +1,48 @@
+import pandas as pd
+from reportlab.lib.pagesizes import letter
+from reportlab.platypus import SimpleDocTemplate, Table, TableStyle, Paragraph, Spacer
+from reportlab.lib import colors
+from reportlab.lib.styles import getSampleStyleSheet
+
+def generate_csv_report(flagged_list: list, path: str):
+    rows = []
+    for item in flagged_list:
+        txn = item.get("transaction", {})
+        rows.append({
+            "transaction_id": txn.get("transaction_id"),
+            "timestamp": txn.get("timestamp"),
+            "amount": txn.get("amount"),
+            "description": txn.get("description"),
+            "risk_factor": item.get("risk_factor"),
+            "risk_score": item.get("risk_score")
+        })
+    df = pd.DataFrame(rows)
+    df.to_csv(path, index=False)
+    return path
+
+def generate_pdf_report(flagged_list: list, path: str):
+    doc = SimpleDocTemplate(path, pagesize=letter)
+    styles = getSampleStyleSheet()
+    elements = []
+    elements.append(Paragraph("Fraud Detection Report", styles["Title"]))
+    elements.append(Spacer(1, 12))
+    data = [["Transaction ID", "Timestamp", "Amount", "Risk Factor", "Risk Score"]]
+    for item in flagged_list:
+        txn = item.get("transaction", {})
+        data.append([
+            str(txn.get("transaction_id", "")),
+            str(txn.get("timestamp", "")),
+            f"{txn.get('amount', '')}",
+            item.get("risk_factor", ""),
+            f"{item.get('risk_score', 0):.2f}"
+        ])
+    table = Table(data, repeatRows=1)
+    table.setStyle(TableStyle([
+        ('BACKGROUND', (0,0), (-1,0), colors.grey),
+        ('TEXTCOLOR',(0,0),(-1,0),colors.whitesmoke),
+        ('GRID', (0,0), (-1,-1), 0.5, colors.black),
+        ('ALIGN',(2,1),(2,-1),'RIGHT')
+    ]))
+    elements.append(table)
+    doc.build(elements)
+    return path

requirements.txt

@@ -0,0 +1,14 @@
+gradio>=4.5
+langchain>=0.0.230
+huggingface-hub>=0.15.1
+sentence-transformers>=2.2.2
+chromadb>=0.3.24
+pandas
+reportlab
+fpdf
+sqlalchemy
+python-dotenv
+slack-sdk
+sendgrid
+requests
+tqdm