Initial clean deployment

.gitignore

@@ -0,0 +1,8 @@
+
+*.png
+*.jpg
+*.jpeg
+
+*.png
+*.jpg
+*.jpeg

Researchmind-AI/.gitignore

@@ -0,0 +1,86 @@
+# ==================================================
+# Python
+# ==================================================
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+
+# ==================================================
+# Virtual Environments
+# ==================================================
+venv/
+.venv/
+env/
+ENV/
+
+# ==================================================
+# Environment Variables (API Keys)
+# ==================================================
+.env
+.env.*
+!.env.example
+
+# ==================================================
+# Gradio
+# ==================================================
+.gradio/
+
+# ==================================================
+# Snapshots
+# ==================================================
+.snapshots/
+
+# ==================================================
+# Generated Reports
+# ==================================================
+ResearchMind_Report.pdf
+research_report.pdf
+research_report.md
+
+# ==================================================
+# Output Files
+# ==================================================
+output/
+
+# ==================================================
+# Logs
+# ==================================================
+*.log
+
+# ==================================================
+# IDE
+# ==================================================
+.vscode/
+.idea/
+
+# ==================================================
+# Operating System
+# ==================================================
+.DS_Store
+Thumbs.db
+
+# ==================================================
+# Python Cache
+# ==================================================
+.pytest_cache/
+.mypy_cache/
+
+# ==================================================
+# Jupyter
+# ==================================================
+.ipynb_checkpoints/
+
+# ==================================================
+# Build Files
+# ==================================================
+build/
+dist/
+*.egg-info/
+
+# ==================================================
+# Temporary Files
+# ==================================================
+*.tmp
+*.temp

Researchmind-AI/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Azfar 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Researchmind-AI/README.md

@@ -0,0 +1,198 @@
+# 🔬 ResearchMind AI
+
+<div align="center">
+
+![Python](https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white)
+![Gradio](https://img.shields.io/badge/Gradio-UI-FF6F00?style=for-the-badge)
+![Groq](https://img.shields.io/badge/Groq-LLM-000000?style=for-the-badge)
+![RAG](https://img.shields.io/badge/RAG-Retrieval--Augmented--Generation-6A5ACD?style=for-the-badge)
+![Agentic](https://img.shields.io/badge/Agentic-Plan%20%E2%86%92%20Write%20%E2%86%92%20Verify-E91E63?style=for-the-badge)
+![FAISS](https://img.shields.io/badge/FAISS-Vector%20Search-009688?style=for-the-badge)
+![Tests](https://img.shields.io/badge/Tests-26%20passing-2E7D32?style=for-the-badge)
+![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)
+
+### A multi-agent research assistant that plans, researches, writes, and **fact-checks its own reports**
+
+</div>
+
+---
+
+## 📖 Overview
+
+Most AI research tools return fluent text you have to trust blindly. ResearchMind AI is built around a different idea: **every claim in the report is cited, and a second agent checks each claim against the exact passages it cites** before you see the result.
+
+Give it a topic and a team of cooperating agents does the work:
+
+| Agent | Job |
+|---|---|
+| 🧭 **Planner** | Breaks the topic into focused research sub-questions |
+| 🔍 **Researcher** | Searches the web for every sub-question in parallel (Tavily) |
+| 🧩 **Retriever** | Chunks and embeds all sources, then ranks the best passages with FAISS cosine search |
+| ✍️ **Writer** | Drafts a report that may only use the retrieved sources, citing them as `[1]`, `[2]` |
+| 🔎 **Checker** | Verifies each cited claim against the passages it cites: *supported / partial / unsupported* |
+| 🛠️ **Reviser** | Rewrites or removes flagged claims, then the Checker re-verifies (the feedback loop) |
+| 🌍 **Translator** | Optionally renders the *verified* English report in Urdu |
+
+The UI shows this activity live: the plan, sources found, passages retrieved, and the fact-check verdicts.
+
+---
+
+## ✨ Features
+
+- **Agentic pipeline** with a self-correcting verify → revise loop
+- **Real RAG**: per-request in-memory FAISS index (normalized embeddings, cosine similarity), per-source caps so one page cannot dominate, relevance floor to drop weak passages
+- **Inline citations** `[n]` with a sources list built by code (URLs are never invented by the model); invented citation numbers are stripped automatically
+- **Claim-level verification** with an honest score shown on every report
+- **Bring your own documents**: upload PDF / TXT / MD, mix them with web results, or run on your documents only
+- **Research depth** presets: Quick, Standard, Deep
+- **Report styles**: Standard, Summary, Academic
+- **English and Urdu** output (Urdu is translated *after* verification, so the checking happens on the original English text)
+- **Export** to Markdown (all languages) and PDF (English) with clickable source links
+- **Model fallback and rate-limit retry** across several Groq models
+- **Offline test suite** (26 tests) and a **batch evaluation script**
+
+---
+
+## 🏗️ Architecture
+
+```text
+                    Topic + options (style, depth, language, documents)
+                                      │
+                                      ▼
+                         ┌────────────────────────┐
+                         │  Planner (fast LLM)    │──► 2–5 sub-questions
+                         └───────────┬────────────┘
+                                     ▼
+                  ┌─────────────────────────────────────┐
+                  │ Researcher: parallel Tavily search  │  + uploaded PDF/TXT/MD
+                  └───────────────────┬─────────────────┘
+                                      ▼
+                  ┌─────────────────────────────────────┐
+                  │ Retriever: chunk → embed (MiniLM)   │
+                  │ → FAISS cosine index → top passages │
+                  │   per sub-question                  │
+                  └───────────────────┬─────────────────┘
+                                      ▼
+                         ┌────────────────────────┐
+                         │ Writer (70B, streaming)│──► cited draft
+                         └───────────┬────────────┘
+                                     ▼
+              ┌─────────────────────────────────────���───────┐
+              │ Checker: each claim vs. the passages it cites│
+              └───────────┬─────────────────────────────────┘
+                          │ flagged claims?
+                  yes ┌───┴───┐ no
+                      ▼       │
+              ┌──────────────┐│
+              │   Reviser    ││   (re-check; keep the revision only if it scores better)
+              └──────┬───────┘│
+                     └────────┤
+                              ▼
+                  Translator (optional) → Report + Sources + Verification
+```
+
+---
+
+## 🧰 Tech Stack
+
+Python · Gradio · Groq (Llama 3.3 70B for writing, Llama 3.1 8B for planning and checking, with fallbacks) · Tavily · Sentence-Transformers (`all-MiniLM-L6-v2`) · FAISS · LangChain text splitters · pypdf · ReportLab
+
+---
+
+## 🚀 Getting Started
+
+```bash
+git clone https://github.com/muhammadazfar-ai/ResearchMind-AI.git
+cd ResearchMind-AI
+python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+cp .env.example .env                                    # then add your keys
+python app.py
+```
+
+You need a free [Groq](https://console.groq.com) key and a [Tavily](https://tavily.com) key. Never commit `.env`.
+
+### Run on Hugging Face Spaces
+1. Create a new **Gradio** Space and push this repository.
+2. In *Settings → Variables and secrets*, add `GROQ_API_KEY` and `TAVILY_API_KEY` as **secrets**.
+3. The Space installs `requirements.txt` and runs `app.py` automatically.
+
+---
+
+## 📊 Evaluation
+
+Run the pipeline over a topic list and measure how well-grounded the reports are:
+
+```bash
+python evaluate.py --limit 5            # first 5 topics in evaluation/topics.txt
+python evaluate.py --depth Quick --pause 15
+```
+
+It writes `evaluation/results.json` and `evaluation/RESULTS.md` with, per topic and on average:
+- **Claim support rate**: share of cited claims fully supported by their sources, for the first draft and after the Checker/Reviser loop
+- **Citation coverage**: share of factual sentences that carry a citation
+- Sources per report, claims checked, and time per report
+
+> Paste your own `RESULTS.md` summary here after running it, so the numbers in this README are yours.
+
+---
+
+## 🧪 Tests
+
+```bash
+pip install -r requirements-dev.txt
+python -m pytest
+```
+
+The suite runs fully offline with scripted fake search, embedding and LLM components. It covers retrieval ranking, citation cleaning, claim extraction, the full verify → revise loop (including a planted false claim that must be caught and removed), document loading, Urdu translation flow, error paths, and the UI handler.
+
+---
+
+## ⚙️ Configuration
+
+All tuning lives in [`src/config.py`](src/config.py): chunk size, depth presets, how many passages go to the Writer, relevance thresholds, fact-check batch size. Model order per role is in [`src/llm.py`](src/llm.py) and can be overridden with `GROQ_WRITER_MODEL` / `GROQ_FAST_MODEL`.
+
+---
+
+## ⚠️ Limitations
+
+- **The fact-check measures grounding, not absolute truth.** An LLM judges whether a claim matches the passages it cites. If a source is wrong, the report can still be "supported". Verify critical facts yourself.
+- **Free-tier rate limits.** Deep research makes many API calls; the app retries and falls back to other models, but it can still be slow or fail under tight limits.
+- **Urdu PDF export is not supported** (standard PDF fonts cannot shape Urdu). Urdu reports download as Markdown.
+- **Scanned PDFs** have no text layer and need OCR before upload.
+- The Urdu translation is machine-generated and was not reviewed by a native speaker.
+
+---
+
+## 📂 Project Structure
+
+```text
+ResearchMind-AI/
+├── app.py                 # Gradio UI: controls, live agent log, exports
+├── evaluate.py            # Batch evaluation (support rate, coverage, timing)
+├── requirements.txt
+├── requirements-dev.txt
+├── pytest.ini
+├── .env.example
+├── evaluation/
+│   └── topics.txt         # Topics used by evaluate.py
+├── src/
+│   ├── agents.py          # Planner, Researcher, Writer, Checker, Reviser, Translator
+│   ├── pipeline.py        # Orchestration + live activity trace
+│   ├── evidence.py        # Chunking, FAISS index, passage selection per question
+│   ├── embeddings.py      # Sentence-Transformers + cosine index
+│   ├── search.py          # Tavily web search
+│   ├── documents.py       # PDF / TXT / MD loading
+│   ├── llm.py             # Groq client, model fallback, streaming
+│   ├── prompts.py         # All agent prompts
+│   ├── chunking.py        # Recursive text splitter
+│   └── config.py          # Tunable settings
+├── tests/                 # Offline test suite
+└── screenshot/
+```
+
+---
+
+## 📄 License
+
+MIT. See [LICENSE](LICENSE).

Researchmind-AI/app.py

@@ -0,0 +1,292 @@
+import html
+import os
+import re
+import tempfile
+import threading
+import uuid
+
+from dotenv import find_dotenv, load_dotenv
+
+# Search up the directory tree to find .env and load environment variables
+load_dotenv(find_dotenv(), override=True)
+
+# Startup verification logs for keys
+if not os.getenv("GROQ_API_KEY"):
+    print("[WARNING] GROQ_API_KEY was not found in .env or environment variables.")
+if not os.getenv("TAVILY_API_KEY"):
+    print("[WARNING] TAVILY_API_KEY was not found in .env or environment variables.")
+
+import gradio as gr
+from reportlab.lib.pagesizes import LETTER
+from reportlab.lib.styles import getSampleStyleSheet
+from reportlab.platypus import Paragraph, SimpleDocTemplate, Spacer
+
+from src.config import DEFAULT_DEPTH, DEPTH_PRESETS, LANGUAGES, MAX_UPLOAD_FILES, MODES
+from src.embeddings import get_embedding_model
+from src.pipeline import run_research
+
+REPORTS_DIR = os.path.join(tempfile.gettempdir(), "researchmind_reports")
+
+
+# ======================================================
+# EXPORT (Markdown + PDF)
+# ======================================================
+def _pdf_safe(text: str) -> str:
+    """Standard PDF fonts only cover Windows-1252, so drop emoji and other unsupported symbols."""
+    return text.encode("cp1252", "ignore").decode("cp1252")
+
+
+def create_markdown(text: str):
+    """Saves the report as a .md file (works for every language)."""
+    if not text or len(text.strip()) < 10:
+        return None
+    os.makedirs(REPORTS_DIR, exist_ok=True)
+    path = os.path.join(REPORTS_DIR, f"ResearchMind_Report_{uuid.uuid4().hex[:8]}.md")
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(text)
+    return path
+
+
+def create_pdf(text: str):
+    """Builds a PDF from the markdown report. English/Latin text only (see README for Urdu)."""
+    if not text or len(text.strip()) < 10:
+        return None
+    try:
+        os.makedirs(REPORTS_DIR, exist_ok=True)
+        path = os.path.join(REPORTS_DIR, f"ResearchMind_Report_{uuid.uuid4().hex[:8]}.pdf")
+        styles = getSampleStyleSheet()
+        story = []
+        for raw in text.split("\n"):
+            line = _pdf_safe(raw).strip()
+            if not line:
+                story.append(Spacer(1, 8))
+                continue
+            if set(line) <= {"-", " "}:  # horizontal rule
+                story.append(Spacer(1, 6))
+                continue
+
+            style, bullet = styles["BodyText"], None
+            heading = re.match(r"^(#+)\s*(.*)", line)
+            if heading:
+                style = styles["Heading1"] if len(heading.group(1)) == 1 else styles["Heading2"]
+                line = heading.group(2)
+            elif line.startswith(">"):
+                style, line = styles["Italic"], line.lstrip("> ").strip()
+            elif re.match(r"^[-*]\s+", line):
+                bullet, line = "\u2022", re.sub(r"^[-*]\s+", "", line)
+
+            line = html.escape(line)
+            line = re.sub(r"\*\*(.*?)\*\*", r"<b>\1</b>", line)
+            line = re.sub(r"\[([^\]]+)\]\((https?://[^)\s]+)\)", r'<a href="\2" color="blue">\1</a>', line)
+            story.append(Paragraph(line, style, bulletText=bullet))
+
+        SimpleDocTemplate(path, pagesize=LETTER).build(story)
+        return path
+    except Exception as e:
+        print(f"PDF Generation Error: {e}")
+        return None
+
+
+def export_files(report: str, language: str) -> list:
+    files = [create_markdown(report)]
+    if language == "English":
+        files.append(create_pdf(report))
+    return [f for f in files if f]
+
+
+# ======================================================
+# CORE HANDLER
+# ======================================================
+def run_agent(topic, mode, language, depth, use_web, doc_files):
+    """Streams the agent pipeline into the UI: live activity log, report, then downloadable files."""
+    if not topic or len(topic.strip()) < 2:
+        yield (
+            gr.update(visible=True),
+            gr.update(value="", visible=False),
+            gr.update(value="", visible=False),
+            gr.update(value=None, visible=False),
+        )
+        return
+
+    rtl = language == "Urdu"
+    try:
+        for event in run_research(
+            topic.strip(), mode, language, depth, use_web, [getattr(f, "name", f) for f in (doc_files or [])]
+        ):
+            report_update = gr.update() if event["report"] is None else gr.update(value=event["report"], visible=True, rtl=rtl)
+            files_update = gr.update(value=None, visible=False)
+            if event["done"]:
+                files = export_files(event["result"]["report"], language)
+                files_update = gr.update(value=files, visible=bool(files))
+            yield gr.update(visible=False), gr.update(value=event["trace"], visible=True), report_update, files_update
+            if event["error"]:
+                return
+    except Exception as e:
+        yield (
+            gr.update(visible=False),
+            gr.update(),
+            gr.update(value=f"### ❌ An Error Occurred:\n`{str(e)}`", visible=True),
+            gr.update(value=None, visible=False),
+        )
+
+
+def reset_ui():
+    """Resets the UI state for starting a new research session."""
+    return (
+        "",                                    # clear search input
+        gr.update(visible=True),               # show welcome text
+        gr.update(value="", visible=False),    # clear activity log
+        gr.update(value="", visible=False),    # clear report
+        gr.update(value=None, visible=False),  # clear downloads
+    )
+
+
+# ======================================================
+# STYLES
+# ======================================================
+custom_css = """
+body, .gradio-container { 
+    background-color: #0b0e14 !important; 
+    color: #adbac7 !important; 
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif !important;
+}
+footer { display: none !important; }
+
+.sidebar-gpt { 
+    background-color: #0d1117 !important; 
+    border-right: 1px solid #2d333b !important; 
+    padding: 16px !important; 
+}
+.sidebar-btn { 
+    background: transparent !important;
+    border: 1px solid #2d333b !important;
+    color: #adbac7 !important;
+    text-align: left !important;
+    justify-content: flex-start !important;
+    padding: 10px 14px !important; 
+    border-radius: 10px !important; 
+    cursor: pointer !important; 
+    font-size: 14px !important;
+    margin-bottom: 8px !important;
+    width: 100% !important;
+}
+.sidebar-btn:hover { 
+    background: #1c2128 !important; 
+    color: #ffffff !important; 
+}
+
+.chat-container { 
+    max-width: 850px !important; 
+    margin: 0 auto !important; 
+    padding-bottom: 40px !important; 
+}
+.welcome-text { 
+    font-size: 32px; 
+    font-weight: 700; 
+    text-align: center; 
+    margin-top: 40px; 
+    color: #ffffff; 
+}
+
+.report-gpt { 
+    color: #adbac7 !important; 
+    font-size: 16px !important; 
+    line-height: 1.7 !important; 
+}
+.report-gpt h1, .report-gpt h2, .report-gpt h3 { 
+    color: #ffffff !important; 
+}
+
+.input-bar-gpt { 
+    background: #1c2128 !important; 
+    border: 1px solid #2d333b !important; 
+    border-radius: 16px !important; 
+    padding: 8px 16px !important; 
+    align-items: center !important;
+}
+
+.trace-box {
+    background: #0d1117 !important;
+    border: 1px solid #2d333b !important;
+    border-radius: 12px !important;
+    padding: 12px 16px !important;
+    font-size: 14px !important;
+    margin-bottom: 12px !important;
+}
+
+.send-btn { 
+    background: #10a37f !important; 
+    color: white !important; 
+    border-radius: 50% !important; 
+    min-width: 40px !important;
+    height: 40px !important;
+    border: none !important;
+}
+"""
+
+# ======================================================
+# UI STRUCTURE
+# ======================================================
+with gr.Blocks(title="ResearchMind AI") as app:
+    with gr.Row():
+        # LEFT SIDEBAR
+        with gr.Column(scale=1, elem_classes="sidebar-gpt", min_width=240):
+            gr.HTML("""<div style="font-size:20px; font-weight:800; margin-bottom:20px; color:#ffffff;">ResearchMind</div>""")
+            new_research_btn = gr.Button("➕  New Research", elem_classes="sidebar-btn")
+            gr.Markdown(
+                "**How it works**\n\n"
+                "1. 🧭 **Planner** splits your topic\n"
+                "2. 🔍 **Researcher** searches the web\n"
+                "3. 🧩 **Retriever** indexes & ranks passages\n"
+                "4. ✍️ **Writer** drafts with citations\n"
+                "5. 🔎 **Checker** verifies every claim\n"
+                "6. 🛠️ **Reviser** fixes weak claims\n"
+            )
+
+        # MAIN AREA
+        with gr.Column(scale=4):
+            with gr.Row():
+                mode = gr.Dropdown(choices=MODES, value="Standard", label="Style", scale=2)
+                depth = gr.Dropdown(choices=list(DEPTH_PRESETS), value=DEFAULT_DEPTH, label="Depth", scale=2)
+                language = gr.Dropdown(choices=LANGUAGES, value="English", label="Language", scale=2)
+
+            with gr.Column(elem_classes="chat-container"):
+                welcome = gr.HTML('<div class="welcome-text">What would you like to research?</div>')
+                trace_out = gr.Markdown(visible=False, elem_classes="trace-box")
+                report_out = gr.Markdown(visible=False, elem_classes="report-gpt")
+                files_out = gr.File(label="Download report", file_count="multiple", visible=False)
+
+            with gr.Row(elem_classes="input-bar-gpt"):
+                query = gr.Textbox(placeholder="Ask anything...", lines=1, container=False, scale=10)
+                submit_btn = gr.Button("↑", variant="primary", elem_classes="send-btn", scale=1)
+
+            with gr.Row():
+                use_web = gr.Checkbox(label="🌐 Include web search", value=True)
+            with gr.Accordion(f"📎 Add your own documents (PDF, TXT, MD — up to {MAX_UPLOAD_FILES})", open=False):
+                doc_files = gr.File(file_count="multiple", file_types=[".pdf", ".txt", ".md"], label="Your documents")
+
+    # Event handlers
+    run_inputs = [query, mode, language, depth, use_web, doc_files]
+    run_outputs = [welcome, trace_out, report_out, files_out]
+
+    submit_event = submit_btn.click(fn=run_agent, inputs=run_inputs, outputs=run_outputs)
+    submit_event.then(fn=lambda: "", outputs=[query])
+
+    query_event = query.submit(fn=run_agent, inputs=run_inputs, outputs=run_outputs)
+    query_event.then(fn=lambda: "", outputs=[query])
+
+    new_research_btn.click(fn=reset_ui, outputs=[query, welcome, trace_out, report_out, files_out])
+
+
+def _warm_up():
+    """Loads the embedding model in the background so the first search is not slow."""
+    try:
+        get_embedding_model()
+    except Exception as e:
+        print(f"[DEBUG WARNING] Embedding model warm-up failed: {e}")
+
+
+if __name__ == "__main__":
+    threading.Thread(target=_warm_up, daemon=True).start()
+    app.queue(default_concurrency_limit=3)
+    app.launch(inbrowser=not os.getenv("SPACE_ID"), css=custom_css)

Researchmind-AI/evaluate.py

@@ -0,0 +1,156 @@
+"""Batch evaluation of ResearchMind on a list of topics.
+
+Usage:
+    python evaluate.py                       # all topics in evaluation/topics.txt
+    python evaluate.py --limit 3 --depth Quick
+    python evaluate.py --topics my_topics.txt --pause 15
+
+For every topic it runs the full agent pipeline and records the fact-checker's verdicts:
+  * support rate     - share of cited claims fully supported by the passages they cite
+  * first draft vs final - how much the Checker/Reviser loop improved the report
+  * citation coverage - share of factual sentences that carry a citation
+Results are written to evaluation/results.json and evaluation/RESULTS.md.
+"""
+import argparse
+import json
+import os
+import statistics
+import time
+
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+
+def evaluate_topic(topic: str, depth: str, runner) -> dict:
+    row = {"topic": topic, "ok": False}
+    try:
+        final = None
+        for event in runner(topic, "Standard", "English", depth, True, None):
+            if event["error"]:
+                row["error"] = event["report"]
+                return row
+            if event["done"]:
+                final = event["result"]
+        if not final:
+            row["error"] = "pipeline produced no result"
+            return row
+    except Exception as e:
+        row["error"] = str(e)
+        return row
+
+    m = final["metrics"]
+    first, last = m["first_pass"] or {}, m["final"] or {}
+    row.update({
+        "ok": True,
+        "sources": m["sources"],
+        "passages": m["passages_indexed"],
+        "claims": last.get("claims"),
+        "checked": last.get("checked"),
+        "support_first": first.get("support_rate"),
+        "support_final": last.get("support_rate"),
+        "citation_coverage": last.get("citation_coverage"),
+        "revised": m["revised"],
+        "seconds": m["seconds"],
+    })
+    return row
+
+
+def _mean(rows, key):
+    values = [r[key] for r in rows if r.get(key) is not None]
+    return statistics.mean(values) if values else None
+
+
+def aggregate(rows: list) -> dict:
+    ok = [r for r in rows if r["ok"]]
+    return {
+        "topics": len(rows),
+        "completed": len(ok),
+        "avg_sources": _mean(ok, "sources"),
+        "avg_claims": _mean(ok, "claims"),
+        "avg_support_first": _mean(ok, "support_first"),
+        "avg_support_final": _mean(ok, "support_final"),
+        "avg_citation_coverage": _mean(ok, "citation_coverage"),
+        "avg_seconds": _mean(ok, "seconds"),
+        "revised_count": sum(1 for r in ok if r.get("revised")),
+    }
+
+
+def _pct(x):
+    return "n/a" if x is None else f"{x * 100:.0f}%"
+
+
+def _num(x, digits=1):
+    return "n/a" if x is None else f"{x:.{digits}f}"
+
+
+def write_outputs(rows: list, summary: dict, out_dir: str, depth: str):
+    os.makedirs(out_dir, exist_ok=True)
+    with open(os.path.join(out_dir, "results.json"), "w", encoding="utf-8") as f:
+        json.dump({"depth": depth, "summary": summary, "rows": rows}, f, indent=2)
+
+    lines = [
+        "# Evaluation results",
+        "",
+        f"Depth preset: **{depth}** · Topics completed: **{summary['completed']}/{summary['topics']}**",
+        "",
+        "| Topic | Sources | Claims | Support (1st draft) | Support (final) | Cited sentences | Revised | Time (s) |",
+        "|---|---|---|---|---|---|---|---|",
+    ]
+    for r in rows:
+        if r["ok"]:
+            lines.append(
+                f"| {r['topic']} | {r['sources']} | {r['claims']} | {_pct(r['support_first'])} | "
+                f"{_pct(r['support_final'])} | {_pct(r['citation_coverage'])} | {'yes' if r['revised'] else 'no'} | {_num(r['seconds'])} |"
+            )
+        else:
+            lines.append(f"| {r['topic']} | failed: {r.get('error', 'unknown')[:60]} | | | | | | |")
+    lines += [
+        "",
+        "## Summary",
+        "",
+        f"- Average claim support: **{_pct(summary['avg_support_first'])}** in the first draft → **{_pct(summary['avg_support_final'])}** after the Checker/Reviser loop",
+        f"- Average share of factual sentences with a citation: **{_pct(summary['avg_citation_coverage'])}**",
+        f"- Average sources per report: **{_num(summary['avg_sources'])}**, claims checked per report: **{_num(summary['avg_claims'])}**",
+        f"- Reports improved by the Reviser: **{summary['revised_count']}/{summary['completed']}**",
+        f"- Average time per report: **{_num(summary['avg_seconds'])} s**",
+        "",
+        "_Support is judged by an automated LLM fact-checker against the passages each claim cites; "
+        "it measures grounding in the retrieved sources, not absolute truth._",
+    ]
+    with open(os.path.join(out_dir, "RESULTS.md"), "w", encoding="utf-8") as f:
+        f.write("\n".join(lines) + "\n")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Evaluate ResearchMind on a list of topics.")
+    parser.add_argument("--topics", default="evaluation/topics.txt")
+    parser.add_argument("--depth", default="Standard", choices=["Quick", "Standard", "Deep"])
+    parser.add_argument("--limit", type=int, default=None, help="only run the first N topics")
+    parser.add_argument("--pause", type=float, default=8.0, help="seconds to wait between topics (API rate limits)")
+    parser.add_argument("--out", default="evaluation")
+    args = parser.parse_args()
+
+    from src.pipeline import run_research
+
+    with open(args.topics, encoding="utf-8") as f:
+        topics = [line.strip() for line in f if line.strip()]
+    if args.limit:
+        topics = topics[: args.limit]
+
+    rows = []
+    for i, topic in enumerate(topics, 1):
+        print(f"[{i}/{len(topics)}] {topic}")
+        row = evaluate_topic(topic, args.depth, run_research)
+        print("   ->", f"support {_pct(row['support_first'])} -> {_pct(row['support_final'])}, {row['seconds']}s" if row["ok"] else f"FAILED: {row.get('error')}")
+        rows.append(row)
+        if i < len(topics):
+            time.sleep(args.pause)
+
+    summary = aggregate(rows)
+    write_outputs(rows, summary, args.out, args.depth)
+    print(f"\nWrote {args.out}/results.json and {args.out}/RESULTS.md")
+
+
+if __name__ == "__main__":
+    main()

Researchmind-AI/evaluation/topics.txt

@@ -0,0 +1,10 @@
+How is generative AI being used in agriculture
+Impact of large language models on software engineering jobs
+Retrieval-augmented generation techniques to reduce LLM hallucinations
+Solar energy adoption in Pakistan
+Current state of AI regulation in the European Union
+Benefits and risks of AI in healthcare diagnostics
+How do AI agents use tools and planning
+Electric vehicle adoption trends worldwide
+Cybersecurity risks of generative AI
+Future of remote work after 2025

Researchmind-AI/pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+pythonpath = .
+testpaths = tests

Researchmind-AI/requirements-dev.txt

@@ -0,0 +1,2 @@
+-r requirements.txt
+pytest>=8.0

Researchmind-AI/requirements.txt

@@ -0,0 +1,10 @@
+gradio>=6.0.0,<7
+groq>=0.4.0,<2
+python-dotenv>=1.0.0,<2
+tavily-python>=0.3.0,<1
+sentence-transformers>=2.2.2,<7
+faiss-cpu>=1.7.4,<2
+langchain-text-splitters>=0.0.1,<2
+reportlab>=4.0.0,<6
+pypdf>=4.0.0,<7
+numpy>=1.24.0,<3

Researchmind-AI/src/agents.py

@@ -0,0 +1,232 @@
+"""The agents of ResearchMind. Each one is a small, testable function.
+
+Planner    -> splits the topic into sub-questions
+Researcher -> searches the web for every sub-question (in parallel)
+Writer     -> drafts a cited report from retrieved evidence
+Checker    -> verifies every cited claim against the passages it cites
+Reviser    -> rewrites flagged claims so they match the evidence
+Translator -> renders the verified report in another language
+"""
+import json
+import re
+from collections import Counter
+from concurrent.futures import ThreadPoolExecutor
+
+from src import config
+from src.llm import LLMError
+from src.prompts import (
+    SYSTEM_CHECKER,
+    SYSTEM_PLANNER,
+    SYSTEM_REVISER,
+    SYSTEM_TRANSLATOR,
+    SYSTEM_WRITER,
+    build_check_prompt,
+    build_planner_prompt,
+    build_revise_prompt,
+    build_translate_prompt,
+    build_writer_prompt,
+)
+from src.search import SearchError
+
+_CITATION = re.compile(r"\[(\d{1,2}(?:\s*,\s*\d{1,2})*)\]")
+VERDICTS = ("supported", "partial", "unsupported")
+
+
+# ------------------------------------------------------------------ helpers
+def parse_json(text: str):
+    """Parses JSON even if the model wrapped it in prose or code fences."""
+    if not text:
+        return None
+    try:
+        return json.loads(text)
+    except Exception:
+        pass
+    match = re.search(r"\{.*\}", text, re.S)
+    if match:
+        try:
+            return json.loads(match.group(0))
+        except Exception:
+            return None
+    return None
+
+
+def clean_citations(text: str, max_n: int) -> str:
+    """Normalises [1, 2] to [1][2] and drops citation numbers the model invented (outside 1..max_n)."""
+    def _replace(match):
+        numbers = [int(n) for n in re.split(r"\s*,\s*", match.group(1))]
+        return "".join(f"[{n}]" for n in numbers if 1 <= n <= max_n)
+
+    return _CITATION.sub(_replace, text)
+
+
+# ------------------------------------------------------------------ Planner
+def plan(topic: str, n: int, complete) -> list:
+    """Returns up to n search-friendly sub-questions; falls back to the topic itself."""
+    messages = [
+        {"role": "system", "content": SYSTEM_PLANNER},
+        {"role": "user", "content": build_planner_prompt(topic, n)},
+    ]
+    data = parse_json(complete(messages, role="fast", temperature=0.2, json_mode=True))
+    questions = []
+    for q in (data or {}).get("sub_questions", []):
+        if isinstance(q, str) and q.strip() and q.strip() not in questions:
+            questions.append(q.strip())
+    return questions[:n] or [topic]
+
+
+# --------------------------------------------------------------- Researcher
+def research_web(questions: list, cfg: dict, searcher) -> tuple:
+    """Searches every sub-question in parallel. Returns (unique_sources, error_messages)."""
+    def one(question):
+        try:
+            return searcher(
+                question,
+                max_results=cfg["results_per_question"],
+                search_depth=cfg["search_depth"],
+            ), None
+        except SearchError as e:
+            return [], str(e)
+
+    sources, errors, seen = [], [], set()
+    with ThreadPoolExecutor(max_workers=min(len(questions), 5) or 1) as pool:
+        for results, error in pool.map(one, questions):
+            if error and error not in errors:
+                errors.append(error)
+            for item in results:
+                key = item.get("url") or item["title"]
+                if key in seen:
+                    continue
+                seen.add(key)
+                sources.append({**item, "kind": "web"})
+    return sources, errors
+
+
+# ------------------------------------------------------------------- Writer
+def format_context(selected: list, sources: list) -> str:
+    """Renders retrieved passages grouped under their numbered source."""
+    blocks = []
+    for source in sources:
+        texts = [c["text"] for c in selected if c["cite"] == source["n"]]
+        body = "\n".join(f"- {t}" for t in texts)
+        where = source["url"] if source.get("url") else "uploaded document"
+        blocks.append(f"[{source['n']}] {source['title']} ({where})\n{body}")
+    return "\n\n".join(blocks)
+
+
+def write_stream(topic, mode, questions, selected, sources, stream):
+    """Yields text deltas of the first draft."""
+    messages = [
+        {"role": "system", "content": SYSTEM_WRITER},
+        {
+            "role": "user",
+            "content": build_writer_prompt(topic, mode, questions, format_context(selected, sources), len(sources)),
+        },
+    ]
+    yield from stream(messages, role="writer", temperature=0.3)
+
+
+# ------------------------------------------------------------------ Checker
+def extract_claims(report: str) -> tuple:
+    """Splits a report into cited sentences (claims to verify) and counts uncited factual sentences."""
+    claims, uncited = [], 0
+    for raw in report.split("\n"):
+        line = raw.strip()
+        if not line or line.startswith(("#", ">", "---")):
+            continue
+        line = re.sub(r"^([-*\u2022]|\d+[.)])\s+", "", line)
+        line = re.sub(r"\*\*|__", "", line)
+        # "claim. [1]" -> "claim[1]." so the citation stays attached to its sentence
+        line = re.sub(r"([.!?])\s*((?:\[\d{1,2}\])+)", r"\2\1", line)
+        for sentence in re.split(r"(?<=[.!?])\s+", line):
+            sentence = sentence.strip()
+            cites = sorted({int(n) for n in re.findall(r"\[(\d{1,2})\]", sentence)})
+            if cites:
+                claims.append({"id": len(claims) + 1, "text": sentence, "cites": cites})
+            elif len(sentence.split()) >= 8:
+                uncited += 1
+    return claims, uncited
+
+
+def check_claims(claims: list, store, complete) -> dict:
+    """Verifies claims in small batches against the passages they cite. Returns {claim_id: {verdict, reason}}."""
+    results = {}
+    to_check = claims[: config.MAX_CLAIMS_CHECKED]
+
+    for start in range(0, len(to_check), config.CHECK_BATCH_SIZE):
+        batch = to_check[start : start + config.CHECK_BATCH_SIZE]
+        items = [
+            {"id": c["id"], "text": c["text"], "evidence": store.support_for(c["text"], c["cites"], k=2)}
+            for c in batch
+        ]
+        messages = [
+            {"role": "system", "content": SYSTEM_CHECKER},
+            {"role": "user", "content": build_check_prompt(items)},
+        ]
+        try:
+            data = parse_json(complete(messages, role="fast", temperature=0.0, json_mode=True))
+        except LLMError as e:
+            print(f"[DEBUG WARNING] Checker batch skipped: {e}")
+            continue
+        for entry in (data or {}).get("results", []):
+            try:
+                claim_id = int(entry["id"])
+            except (KeyError, TypeError, ValueError):
+                continue
+            verdict = str(entry.get("verdict", "")).lower().strip()
+            if verdict in VERDICTS and any(c["id"] == claim_id for c in batch):
+                results[claim_id] = {"verdict": verdict, "reason": str(entry.get("reason", ""))[:200]}
+    return results
+
+
+def summarize_check(claims: list, results: dict, uncited: int) -> dict:
+    counts = Counter(results[c["id"]]["verdict"] for c in claims if c["id"] in results)
+    checked = sum(counts.values())
+    total_sentences = len(claims) + uncited
+    return {
+        "claims": len(claims),
+        "checked": checked,
+        "supported": counts["supported"],
+        "partial": counts["partial"],
+        "unsupported": counts["unsupported"],
+        "support_rate": (counts["supported"] / checked) if checked else None,
+        "citation_coverage": (len(claims) / total_sentences) if total_sentences else None,
+    }
+
+
+# ------------------------------------------------------------------ Reviser
+def revise(report: str, claims: list, results: dict, store, complete) -> str:
+    """Rewrites the report so flagged claims match their evidence. Returns the original if the rewrite looks broken."""
+    issues = []
+    for claim in claims:
+        verdict = results.get(claim["id"])
+        if verdict and verdict["verdict"] in ("unsupported", "partial"):
+            issues.append({
+                "text": claim["text"],
+                "verdict": verdict["verdict"],
+                "reason": verdict["reason"] or "not backed by the cited source",
+                "evidence": store.support_for(claim["text"], claim["cites"], k=2),
+            })
+    if not issues:
+        return report
+
+    messages = [
+        {"role": "system", "content": SYSTEM_REVISER},
+        {"role": "user", "content": build_revise_prompt(report, issues)},
+    ]
+    revised = complete(messages, role="writer", temperature=0.1).strip()
+    # Guard against a stub or truncated answer replacing the whole report
+    if len(revised) < 0.5 * len(report):
+        return report
+    return revised
+
+
+# --------------------------------------------------------------- Translator
+def translate(report: str, language: str, complete) -> str:
+    messages = [
+        {"role": "system", "content": SYSTEM_TRANSLATOR},
+        {"role": "user", "content": build_translate_prompt(report, language)},
+    ]
+    translated = complete(messages, role="writer", temperature=0.1).strip()
+    if len(translated) < 0.3 * len(report):
+        raise LLMError("The translation came back too short.")
+    return translated

Researchmind-AI/src/chunking.py

@@ -0,0 +1,22 @@
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+
+def split_text(text: str, chunk_size: int = 500, chunk_overlap: int = 100) -> list:
+    """Splits raw input text into overlapping chunks using LangChain's RecursiveCharacterTextSplitter."""
+    if not text or not isinstance(text, str) or not text.strip():
+        print("[DEBUG WARNING] Empty or non-string input passed to split_text.")
+        return []
+
+    try:
+        splitter = RecursiveCharacterTextSplitter(
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+            separators=["\n\n", "\n", " ", ""]
+        )
+
+        chunks = splitter.split_text(text)
+        return chunks
+
+    except Exception as e:
+        print(f"[DEBUG ERROR] Failed to split text: {e}")
+        return []

Researchmind-AI/src/config.py

@@ -0,0 +1,33 @@
+"""Central settings for ResearchMind. Tune the pipeline here."""
+
+# --- chunking -------------------------------------------------------------
+CHUNK_SIZE = 800
+CHUNK_OVERLAP = 120
+
+# --- research depth presets (shown in the UI) -----------------------------
+DEPTH_PRESETS = {
+    "Quick":    {"sub_questions": 2, "results_per_question": 3, "search_depth": "basic",    "chunks_per_question": 4},
+    "Standard": {"sub_questions": 3, "results_per_question": 4, "search_depth": "advanced", "chunks_per_question": 5},
+    "Deep":     {"sub_questions": 5, "results_per_question": 4, "search_depth": "advanced", "chunks_per_question": 5},
+}
+DEFAULT_DEPTH = "Standard"
+
+# --- evidence selection ---------------------------------------------------
+MAX_EVIDENCE_CHUNKS = 20          # total passages given to the Writer
+MAX_CHUNKS_PER_SOURCE = 4         # across the whole report, so no single page dominates
+MAX_PER_SOURCE_PER_QUESTION = 2   # per sub-question
+MIN_SCORE = 0.2                   # cosine floor for a passage to count as relevant
+MIN_KEEP_PER_QUESTION = 2         # always keep this many passages per sub-question
+
+# --- fact-checking --------------------------------------------------------
+CHECK_BATCH_SIZE = 5
+MAX_CLAIMS_CHECKED = 40
+MAX_REVISION_ROUNDS = 1
+
+# --- UI options -----------------------------------------------------------
+MODES = ["Standard", "Summary", "Academic"]
+LANGUAGES = ["English", "Urdu"]
+
+# --- uploaded documents ---------------------------------------------------
+MAX_UPLOAD_FILES = 5
+MAX_CHARS_PER_DOCUMENT = 150_000

Researchmind-AI/src/documents.py

@@ -0,0 +1,57 @@
+import os
+import re
+
+from src.config import MAX_CHARS_PER_DOCUMENT, MAX_UPLOAD_FILES
+
+SUPPORTED = (".pdf", ".txt", ".md")
+
+
+def _read_pdf(path: str) -> str:
+    from pypdf import PdfReader
+
+    reader = PdfReader(path)
+    return "\n\n".join((page.extract_text() or "") for page in reader.pages)
+
+
+def _read_text(path: str) -> str:
+    with open(path, "r", encoding="utf-8", errors="ignore") as f:
+        return f.read()
+
+
+def load_documents(paths) -> tuple:
+    """Reads uploaded PDF/TXT/MD files into source dicts.
+
+    Returns (documents, warnings). Each document is {title, url, content, kind}.
+    Problems with one file never stop the others.
+    """
+    documents, warnings = [], []
+    paths = [getattr(p, "name", p) for p in (paths or [])]
+
+    if len(paths) > MAX_UPLOAD_FILES:
+        warnings.append(f"Only the first {MAX_UPLOAD_FILES} files are used.")
+        paths = paths[:MAX_UPLOAD_FILES]
+
+    for path in paths:
+        name = os.path.basename(path)
+        ext = os.path.splitext(name)[1].lower()
+        if ext not in SUPPORTED:
+            warnings.append(f"`{name}` skipped: unsupported file type.")
+            continue
+        try:
+            text = _read_pdf(path) if ext == ".pdf" else _read_text(path)
+        except Exception as e:
+            warnings.append(f"`{name}` could not be read: {e}")
+            continue
+
+        text = re.sub(r"[ \t]+", " ", text)
+        text = re.sub(r"\n{3,}", "\n\n", text).strip()
+        if len(text) < 50:
+            warnings.append(f"`{name}` has no readable text (a scanned PDF needs OCR first).")
+            continue
+        if len(text) > MAX_CHARS_PER_DOCUMENT:
+            text = text[:MAX_CHARS_PER_DOCUMENT]
+            warnings.append(f"`{name}` is long; only the first {MAX_CHARS_PER_DOCUMENT:,} characters are used.")
+
+        documents.append({"title": name, "url": "", "content": text, "kind": "document"})
+
+    return documents, warnings

Researchmind-AI/src/embeddings.py

@@ -0,0 +1,35 @@
+import numpy as np
+import faiss
+
+# Cache model in memory globally so it only loads once
+_MODEL_CACHE = None
+
+
+def get_embedding_model(model_name: str = "all-MiniLM-L6-v2"):
+    """Loads and caches the SentenceTransformer model (imported lazily to keep startup fast)."""
+    global _MODEL_CACHE
+    if _MODEL_CACHE is None:
+        from sentence_transformers import SentenceTransformer
+
+        print(f"Loading embedding model '{model_name}'...")
+        _MODEL_CACHE = SentenceTransformer(model_name)
+    return _MODEL_CACHE
+
+
+def embed_texts(texts: list, model=None) -> np.ndarray:
+    """Encodes texts into L2-normalized float32 vectors (so inner product == cosine similarity)."""
+    model = model or get_embedding_model()
+    vectors = model.encode(
+        texts,
+        convert_to_numpy=True,
+        normalize_embeddings=True,
+        show_progress_bar=False,
+    )
+    return np.asarray(vectors, dtype="float32")
+
+
+def build_cosine_index(vectors: np.ndarray) -> faiss.IndexFlatIP:
+    """Builds an in-memory FAISS inner-product index over normalized vectors."""
+    index = faiss.IndexFlatIP(vectors.shape[1])
+    index.add(vectors)
+    return index

Researchmind-AI/src/evidence.py

@@ -0,0 +1,99 @@
+import numpy as np
+
+from src import config
+from src.chunking import split_text
+from src.embeddings import build_cosine_index, embed_texts
+
+
+class EvidenceError(Exception):
+    """Raised when there is no readable text to build evidence from."""
+
+
+class EvidenceStore:
+    """All source text, chunked and indexed in an in-memory FAISS cosine index.
+
+    Used three ways: retrieve passages per sub-question for the Writer (`gather`),
+    and pull the passages that back a specific claim for the Checker (`support_for`).
+    """
+
+    def __init__(self, sources: list, embedder=None):
+        self.sources = sources
+        self.embedder = embedder
+        self.records = []
+        for source_idx, source in enumerate(sources):
+            for piece in split_text(source["content"], config.CHUNK_SIZE, config.CHUNK_OVERLAP):
+                self.records.append({"id": len(self.records), "text": piece, "source_idx": source_idx})
+        if not self.records:
+            raise EvidenceError("The sources contained no readable text.")
+
+        self.vectors = embed_texts([r["text"] for r in self.records], embedder)
+        self.index = build_cosine_index(self.vectors)
+        self.numbering = {}   # source_idx -> citation number, assigned by gather()
+        self.selected = []
+
+    def _search(self, query: str, k: int):
+        query_vector = embed_texts([query], self.embedder)
+        scores, ids = self.index.search(query_vector, min(len(self.records), k))
+        return [(self.records[i], float(s)) for s, i in zip(scores[0], ids[0]) if i >= 0]
+
+    def gather(self, questions: list, chunks_per_question: int) -> tuple:
+        """Selects the best passages for each sub-question; returns (selected_chunks, numbered_sources)."""
+        chosen, chosen_ids, per_source_total = [], set(), {}
+
+        for q_idx, question in enumerate(questions):
+            kept, per_source_q = 0, {}
+            for record, score in self._search(question, chunks_per_question * 6):
+                if kept >= chunks_per_question or len(chosen) >= config.MAX_EVIDENCE_CHUNKS:
+                    break
+                sid = record["source_idx"]
+                if per_source_q.get(sid, 0) >= config.MAX_PER_SOURCE_PER_QUESTION:
+                    continue
+                if record["id"] in chosen_ids:
+                    # Already picked for an earlier question: it still covers this one, so count it
+                    # instead of padding this question with weaker passages.
+                    if score >= config.MIN_SCORE:
+                        per_source_q[sid] = per_source_q.get(sid, 0) + 1
+                        kept += 1
+                    continue
+                if per_source_total.get(sid, 0) >= config.MAX_CHUNKS_PER_SOURCE:
+                    continue
+                if score < config.MIN_SCORE and kept >= config.MIN_KEEP_PER_QUESTION:
+                    continue
+                chosen_ids.add(record["id"])
+                chosen.append({**record, "score": score, "question_idx": q_idx})
+                per_source_q[sid] = per_source_q.get(sid, 0) + 1
+                per_source_total[sid] = per_source_total.get(sid, 0) + 1
+                kept += 1
+
+        if not chosen:
+            raise EvidenceError("No relevant passages were found in the sources.")
+
+        # Number sources by first appearance so citations read [1], [2], [3]... in order
+        self.numbering = {}
+        for chunk in chosen:
+            self.numbering.setdefault(chunk["source_idx"], len(self.numbering) + 1)
+        for chunk in chosen:
+            chunk["cite"] = self.numbering[chunk["source_idx"]]
+        self.selected = chosen
+
+        numbered = [
+            {
+                "n": n,
+                "title": self.sources[sid]["title"],
+                "url": self.sources[sid].get("url", ""),
+                "kind": self.sources[sid].get("kind", "web"),
+            }
+            for sid, n in sorted(self.numbering.items(), key=lambda kv: kv[1])
+        ]
+        return chosen, numbered
+
+    def support_for(self, claim: str, cites: list, k: int = 2) -> list:
+        """The k passages from the cited sources that are closest to a claim (what the Checker reads)."""
+        wanted = {sid for sid, n in self.numbering.items() if n in set(cites)}
+        candidates = [r["id"] for r in self.records if r["source_idx"] in wanted]
+        if not candidates:
+            return []
+        claim_vector = embed_texts([claim], self.embedder)[0]
+        sims = self.vectors[candidates] @ claim_vector
+        best = np.argsort(-sims)[:k]
+        return [self.records[candidates[i]]["text"] for i in best]

Researchmind-AI/src/llm.py

@@ -0,0 +1,102 @@
+import os
+import time
+
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+# Each agent role has its own model preference list. Later entries are used if a model is
+# unavailable or rate-limited. Override the first choice with GROQ_WRITER_MODEL / GROQ_FAST_MODEL.
+DEFAULT_MODELS = {
+    "writer": ["llama-3.3-70b-versatile", "openai/gpt-oss-120b", "llama-3.1-8b-instant"],
+    "fast":   ["llama-3.1-8b-instant", "openai/gpt-oss-20b", "llama-3.3-70b-versatile"],
+}
+
+
+class LLMError(Exception):
+    """Raised when no Groq model could produce an answer."""
+
+
+def model_candidates(role: str) -> list:
+    models = list(DEFAULT_MODELS[role])
+    override = os.getenv(f"GROQ_{role.upper()}_MODEL", "").strip()
+    if override:
+        models = [override] + [m for m in models if m != override]
+    return models
+
+
+def get_client():
+    """Creates the Groq client lazily so a missing key is a clear runtime message, not an import crash."""
+    key = os.getenv("GROQ_API_KEY", "").strip().strip('"').strip("'")
+    if not key:
+        raise LLMError("`GROQ_API_KEY` is missing in your `.env` file (or Space secrets).")
+    from groq import Groq
+
+    return Groq(api_key=key)
+
+
+def _is_rate_limit(error) -> bool:
+    text = str(error).lower()
+    return "429" in text or "rate limit" in text or "rate_limit" in text
+
+
+def complete(messages: list, role: str = "fast", temperature: float = 0.0, json_mode: bool = False) -> str:
+    """Single (non-streaming) completion with model fallback and one patient retry on rate limits."""
+    client = get_client()
+    last_error = None
+
+    for attempt in range(2):
+        for model_id in model_candidates(role):
+            kwargs = {"model": model_id, "messages": messages, "temperature": temperature}
+            try:
+                if json_mode:
+                    try:
+                        response = client.chat.completions.create(**kwargs, response_format={"type": "json_object"})
+                    except Exception as json_error:
+                        if _is_rate_limit(json_error):
+                            raise
+                        response = client.chat.completions.create(**kwargs)
+                else:
+                    response = client.chat.completions.create(**kwargs)
+                return response.choices[0].message.content or ""
+            except Exception as e:
+                print(f"[DEBUG NOTICE] Groq model '{model_id}' failed: {e}")
+                last_error = e
+        if attempt == 0 and last_error is not None and _is_rate_limit(last_error):
+            time.sleep(8)
+            continue
+        break
+
+    raise LLMError(f"All Groq models failed. Last error: `{last_error}`")
+
+
+def stream_completion(messages: list, role: str = "writer", temperature: float = 0.3):
+    """Yields text deltas, falling back to the next model if one fails before producing output."""
+    client = get_client()
+    last_error = None
+
+    for attempt in range(2):
+        for model_id in model_candidates(role):
+            started = False
+            try:
+                stream = client.chat.completions.create(
+                    model=model_id, messages=messages, temperature=temperature, stream=True
+                )
+                for chunk in stream:
+                    delta = chunk.choices[0].delta.content if chunk.choices else None
+                    if delta:
+                        started = True
+                        yield delta
+                return
+            except Exception as e:
+                if started:
+                    # Failed midway: switching models would restart the report, so surface the error.
+                    raise LLMError(f"Generation was interrupted: `{e}`")
+                print(f"[DEBUG NOTICE] Groq model '{model_id}' failed: {e}")
+                last_error = e
+        if attempt == 0 and last_error is not None and _is_rate_limit(last_error):
+            time.sleep(8)
+            continue
+        break
+
+    raise LLMError(f"All Groq models failed. Last error: `{last_error}`")

Researchmind-AI/src/pipeline.py

@@ -0,0 +1,260 @@
+"""Orchestrates the agents: Planner -> Researcher -> Retriever -> Writer -> Checker -> Reviser -> Translator."""
+import re
+import time
+import types
+
+from src import agents, config, llm
+from src.documents import load_documents
+from src.evidence import EvidenceError, EvidenceStore
+from src.search import search_topic
+
+DEFAULT_LLM = types.SimpleNamespace(complete=llm.complete, stream=llm.stream_completion)
+
+_ICONS = {"run": "⏳", "ok": "✅", "warn": "⚠️", "fail": "❌"}
+
+
+class Trace:
+    """The live 'agent activity' log shown in the UI."""
+
+    def __init__(self):
+        self.steps = []
+
+    def start(self, name: str, detail: str = "") -> int:
+        self.steps.append({"name": name, "status": "run", "detail": detail, "items": []})
+        return len(self.steps) - 1
+
+    def finish(self, idx: int, detail: str = None, status: str = "ok", items: list = None):
+        step = self.steps[idx]
+        step["status"] = status
+        if detail is not None:
+            step["detail"] = detail
+        if items:
+            step["items"] = items
+
+    def render(self) -> str:
+        lines = ["### 🤖 Agent activity", ""]
+        for s in self.steps:
+            lines.append(f"{_ICONS[s['status']]} **{s['name']}** — {s['detail']}".rstrip(" —"))
+            for item in s["items"]:
+                lines.append(f"   - {item}")
+        return "\n".join(lines)
+
+
+def _event(trace, report=None, done=False, error=False, result=None):
+    return {"trace": trace.render(), "report": report, "done": done, "error": error, "result": result}
+
+
+def sources_markdown(sources: list) -> str:
+    lines = []
+    for s in sources:
+        if s.get("kind") == "document":
+            lines.append(f"{s['n']}. 📄 **{s['title']}** (uploaded document)")
+        else:
+            title = re.sub(r"[\[\]]", "", s["title"]) or s["url"]
+            lines.append(f"{s['n']}. [{title}]({s['url']})")
+    return "\n\n---\n\n## Sources\n\n" + "\n".join(lines)
+
+
+def verification_markdown(final: dict, first: dict, revised: bool) -> str:
+    if not final or not final["checked"]:
+        return "\n\n> 🔎 **Verification:** the automatic fact-check was unavailable for this report. Please verify key facts yourself."
+    text = f"{final['supported']} of {final['checked']} cited claims are fully supported by their sources"
+    extras = []
+    if final["partial"]:
+        extras.append(f"{final['partial']} partially supported")
+    if final["unsupported"]:
+        extras.append(f"{final['unsupported']} unsupported")
+    if extras:
+        text += " (" + ", ".join(extras) + ")"
+    if revised and first and first["checked"]:
+        text += f". The first draft scored {first['supported']}/{first['checked']}; the Reviser agent corrected the rest"
+    return f"\n\n> 🔎 **Verification:** {text}. This is an automated check — verify critical facts yourself."
+
+
+def _check(report, store, complete):
+    claims, uncited = agents.extract_claims(report)
+    results = agents.check_claims(claims, store, complete) if claims else {}
+    return claims, results, agents.summarize_check(claims, results, uncited)
+
+
+def run_research(
+    topic: str,
+    mode: str = "Standard",
+    language: str = "English",
+    depth: str = config.DEFAULT_DEPTH,
+    use_web: bool = True,
+    document_paths=None,
+    *,
+    searcher=None,
+    embedder=None,
+    llm_api=None,
+):
+    """Generator. Yields {"trace", "report", "done", "error", "result"} events as the agents work.
+
+    The final event has done=True and a `result` dict with the report, sources and fact-check metrics.
+    `searcher`, `embedder` and `llm_api` can be replaced for testing.
+    """
+    started = time.time()
+    searcher = searcher or search_topic
+    llm_api = llm_api or DEFAULT_LLM
+    cfg = config.DEPTH_PRESETS.get(depth, config.DEPTH_PRESETS[config.DEFAULT_DEPTH])
+    trace = Trace()
+
+    topic = (topic or "").strip()
+    if len(topic) < 2:
+        yield _event(trace, report="### ⚠️ Please enter a research topic.", error=True)
+        return
+
+    # ---- 0. uploaded documents ---------------------------------------------------------
+    documents = []
+    if document_paths:
+        step = trace.start("Documents", "reading uploaded files...")
+        yield _event(trace)
+        documents, warnings = load_documents(document_paths)
+        trace.finish(
+            step,
+            f"{len(documents)} file(s) loaded" if documents else "no readable documents",
+            "ok" if documents else "warn",
+            items=warnings,
+        )
+
+    if not use_web and not documents:
+        yield _event(trace, report="### ⚠️ Web search is off and no readable documents were uploaded, so there is nothing to research.", error=True)
+        return
+
+    # ---- 1. Planner --------------------------------------------------------------------
+    step = trace.start("Planner", "splitting the topic into research questions...")
+    yield _event(trace)
+    try:
+        questions = agents.plan(topic, cfg["sub_questions"], llm_api.complete)
+        trace.finish(step, f"{len(questions)} research question(s)", items=[f"{i}. {q}" for i, q in enumerate(questions, 1)])
+    except llm.LLMError as e:
+        questions = [topic]
+        trace.finish(step, f"planner unavailable ({e}); using the topic as a single question", "warn")
+    yield _event(trace)
+
+    # ---- 2. Researcher -----------------------------------------------------------------
+    sources, errors = list(documents), []
+    if use_web:
+        step = trace.start("Researcher", f"searching the web ({len(questions)} parallel searches)...")
+        yield _event(trace)
+        web_sources, errors = agents.research_web(questions, cfg, searcher)
+        sources = web_sources + sources
+        if web_sources:
+            trace.finish(step, f"{len(web_sources)} web source(s) found", items=[f"note: {e}" for e in errors])
+        else:
+            trace.finish(step, "no web results", "warn", items=errors)
+        yield _event(trace)
+
+    if not sources:
+        message = "### ⚠️ " + (errors[0] if use_web and errors else "No sources were found for this topic.")
+        yield _event(trace, report=message, error=True)
+        return
+
+    # ---- 3. Index + retrieve -----------------------------------------------------------
+    step = trace.start("Retriever", "chunking, embedding and indexing sources...")
+    yield _event(trace)
+    try:
+        store = EvidenceStore(sources, embedder)
+        selected, numbered = store.gather(questions, cfg["chunks_per_question"])
+    except EvidenceError as e:
+        trace.finish(step, str(e), "fail")
+        yield _event(trace, report=f"### ⚠️ {e}", error=True)
+        return
+    except Exception as e:
+        print(f"[DEBUG ERROR] Retrieval failed: {e}")
+        trace.finish(step, f"retrieval failed: {e}", "fail")
+        yield _event(trace, report=f"### ❌ Retrieval failed: `{e}`", error=True)
+        return
+    trace.finish(step, f"{len(store.records)} passages indexed, {len(selected)} selected from {len(numbered)} source(s)")
+    yield _event(trace)
+
+    # ---- 4. Writer ---------------------------------------------------------------------
+    step = trace.start("Writer", "drafting the cited report...")
+    draft = ""
+    try:
+        for delta in agents.write_stream(topic, mode, questions, selected, numbered, llm_api.stream):
+            draft += delta
+            shown = agents.clean_citations(draft, len(numbered))
+            yield _event(trace, report="*Draft — fact-checking will follow...*\n\n" + shown)
+    except llm.LLMError as e:
+        trace.finish(step, str(e), "fail")
+        yield _event(trace, report=f"### ❌ {e}", error=True)
+        return
+    report = agents.clean_citations(draft, len(numbered)).strip()
+    if not report:
+        trace.finish(step, "empty answer", "fail")
+        yield _event(trace, report="### ⚠️ The model returned an empty answer. Please try again.", error=True)
+        return
+    trace.finish(step, f"draft written ({len(report.split())} words)")
+    yield _event(trace, report="*Draft — fact-checking in progress...*\n\n" + report)
+
+    # ---- 5. Checker (+ Reviser loop) ---------------------------------------------------
+    first_metrics = final_metrics = None
+    revised_flag = False
+    step = trace.start("Checker", "verifying every cited claim against its sources...")
+    yield _event(trace, report="*Draft — fact-checking in progress...*\n\n" + report)
+    try:
+        claims, results, first_metrics = _check(report, store, llm_api.complete)
+        final_metrics = first_metrics
+        if first_metrics["checked"]:
+            m = first_metrics
+            trace.finish(step, f"{m['supported']}/{m['checked']} claims supported, {m['partial']} partial, {m['unsupported']} unsupported")
+        else:
+            trace.finish(step, "no claims could be verified", "warn")
+        yield _event(trace, report="*Draft — fact-checking in progress...*\n\n" + report)
+
+        for _ in range(config.MAX_REVISION_ROUNDS):
+            flagged = final_metrics["partial"] + final_metrics["unsupported"]
+            if not flagged:
+                break
+            step = trace.start("Reviser", f"rewriting {flagged} flagged claim(s)...")
+            yield _event(trace, report="*Draft — revising flagged claims...*\n\n" + report)
+            candidate = agents.revise(report, claims, results, store, llm_api.complete)
+            if candidate == report:
+                trace.finish(step, "no usable revision", "warn")
+                break
+            claims2, results2, metrics2 = _check(candidate, store, llm_api.complete)
+            old_rate = final_metrics["support_rate"] or 0
+            new_rate = metrics2["support_rate"] or 0
+            if metrics2["checked"] and new_rate >= old_rate:
+                report, claims, results, final_metrics, revised_flag = candidate, claims2, results2, metrics2, True
+                trace.finish(step, f"revised; now {metrics2['supported']}/{metrics2['checked']} claims supported")
+            else:
+                trace.finish(step, "revision did not improve the report; kept the original draft", "warn")
+            yield _event(trace, report=report)
+    except llm.LLMError as e:
+        trace.finish(step, f"unavailable ({e}); report delivered unverified", "warn")
+        yield _event(trace, report=report)
+
+    # ---- 6. Translator -----------------------------------------------------------------
+    english_report = report
+    if language != "English":
+        step = trace.start("Translator", f"translating the verified report to {language}...")
+        yield _event(trace, report=report)
+        try:
+            report = agents.translate(report, language, llm_api.complete)
+            trace.finish(step, f"translated to {language}")
+        except llm.LLMError as e:
+            trace.finish(step, f"translation failed ({e}); showing English", "warn")
+
+    # ---- 7. Assemble -------------------------------------------------------------------
+    final_md = report + sources_markdown(numbered) + verification_markdown(final_metrics, first_metrics, revised_flag)
+    elapsed = round(time.time() - started, 1)
+    result = {
+        "topic": topic,
+        "report": final_md,
+        "report_english": english_report,
+        "language": language,
+        "questions": questions,
+        "sources": numbered,
+        "metrics": {
+            "first_pass": first_metrics,
+            "final": final_metrics,
+            "revised": revised_flag,
+            "sources": len(numbered),
+            "passages_indexed": len(store.records),
+            "seconds": elapsed,
+        },
+    }
+    yield _event(trace, report=final_md, done=True, result=result)

Researchmind-AI/src/prompts.py

@@ -0,0 +1,112 @@
+# ---------------------------------------------------------------- Planner
+SYSTEM_PLANNER = (
+    "You are the Planner of a research agent. You break a topic into focused research sub-questions "
+    "and reply with JSON only."
+)
+
+
+def build_planner_prompt(topic: str, n: int) -> str:
+    return (
+        f"Topic: {topic}\n\n"
+        f"Break this topic into exactly {n} specific, non-overlapping research sub-questions that together cover it "
+        "(for example: background, current state, evidence or data, challenges or risks, outlook). "
+        "Each sub-question must be a self-contained web-search query written in English, at most 15 words.\n\n"
+        'Return ONLY JSON in this form: {"sub_questions": ["...", "..."]}'
+    )
+
+
+# ----------------------------------------------------------------- Writer
+SYSTEM_WRITER = (
+    "You are ResearchMind, a careful research writer. "
+    "You write reports using ONLY the numbered sources provided by the user. "
+    "Every factual claim must end with a citation such as [1] or [2][3]. "
+    "If the sources do not cover something, say so explicitly instead of filling the gap from memory. "
+    "Never invent sources, URLs, statistics or quotes. "
+    "Do not write a references list; it is added automatically."
+)
+
+MODE_INSTRUCTIONS = {
+    "Standard": (
+        "Write a clear, structured report with markdown sections such as Introduction, Key Findings, "
+        "Current Developments, Challenges, Outlook and Conclusion. Use short paragraphs and bullet points where helpful."
+    ),
+    "Summary": (
+        "Write a concise summary: a 2-3 sentence overview followed by 5-7 bullet points "
+        "covering the most important findings."
+    ),
+    "Academic": (
+        "Write in a formal academic tone with sections such as Abstract, Introduction, Background, Analysis, "
+        "Discussion, Limitations and Conclusion. Be precise, avoid hype, and note where sources disagree or are limited."
+    ),
+}
+
+
+def build_writer_prompt(topic: str, mode: str, questions: list, context: str, num_sources: int) -> str:
+    outline = "\n".join(f"{i}. {q}" for i, q in enumerate(questions, 1))
+    return (
+        f"Topic: {topic}\n\n"
+        f"Research questions to cover:\n{outline}\n\n"
+        f"Sources:\n{context}\n\n"
+        f"Task: {MODE_INSTRUCTIONS.get(mode, MODE_INSTRUCTIONS['Standard'])} "
+        "Make sure the report addresses each research question.\n\n"
+        f"Rules: cite only with the numbers 1 to {num_sources}, placed right after the claim they support. "
+        "Use only information found in the sources above."
+    )
+
+
+# ---------------------------------------------------------------- Checker
+SYSTEM_CHECKER = (
+    "You are a strict fact-checker. You judge whether a claim is supported by the evidence quoted from "
+    "its cited sources. Use only the evidence given; never use outside knowledge. Reply with JSON only."
+)
+
+
+def build_check_prompt(items: list) -> str:
+    blocks = []
+    for item in items:
+        evidence = "\n".join(f"- {e}" for e in item["evidence"]) or "- (no evidence available)"
+        blocks.append(f"CLAIM {item['id']}: {item['text']}\nEVIDENCE {item['id']}:\n{evidence}")
+    return (
+        "Judge each claim against its evidence.\n"
+        'Verdicts: "supported" (the evidence clearly states or directly implies the claim), '
+        '"partial" (the evidence supports only part of the claim, or is vaguer than the claim), '
+        '"unsupported" (the evidence does not contain the claim or contradicts it).\n\n'
+        'Return ONLY JSON: {"results": [{"id": 1, "verdict": "supported", "reason": "max 15 words"}]}\n\n'
+        + "\n\n".join(blocks)
+    )
+
+
+# ---------------------------------------------------------------- Reviser
+SYSTEM_REVISER = (
+    "You are the Reviser of a research agent. You fix a report so that every claim is strictly backed "
+    "by the evidence provided."
+)
+
+
+def build_revise_prompt(report: str, issues: list) -> str:
+    blocks = []
+    for i, issue in enumerate(issues, 1):
+        evidence = "\n".join(f"  - {e}" for e in issue["evidence"]) or "  - (none)"
+        blocks.append(
+            f"{i}. Claim: {issue['text']}\n   Fact-check verdict: {issue['verdict']} ({issue['reason']})\n"
+            f"   Evidence from the cited source:\n{evidence}"
+        )
+    return (
+        f"REPORT:\n{report}\n\n"
+        "A fact-checker flagged these claims:\n\n" + "\n\n".join(blocks) + "\n\n"
+        "For each flagged claim either (a) delete it, or (b) rewrite it so it states ONLY what the evidence supports. "
+        "Do not add new facts or new sources. Keep the headings, structure and [n] citation markers of everything else. "
+        "Return the complete corrected report and nothing else."
+    )
+
+
+# ------------------------------------------------------------- Translator
+SYSTEM_TRANSLATOR = "You are a professional translator who preserves formatting exactly."
+
+
+def build_translate_prompt(report: str, language: str) -> str:
+    return (
+        f"Translate the following research report into {language}. "
+        "Keep the markdown structure (headings, bullets). Keep citation markers such as [1] exactly as they are. "
+        "Do not translate URLs. Return only the translation.\n\n" + report
+    )

Researchmind-AI/src/search.py

@@ -0,0 +1,54 @@
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class SearchError(Exception):
+    """Raised when web search cannot run or returns nothing usable."""
+
+
+def _get_key() -> str:
+    return os.getenv("TAVILY_API_KEY", "").strip().strip('"').strip("'")
+
+
+def search_topic(topic: str, max_results: int = 6, search_depth: str = "advanced") -> list:
+    """Searches the web with Tavily and returns [{title, content, url}, ...].
+
+    Raises SearchError with a user-friendly message if the key is missing,
+    the request fails, or no usable results come back.
+    """
+    key = _get_key()
+    if not key:
+        raise SearchError("`TAVILY_API_KEY` is missing in your `.env` file (or Space secrets).")
+
+    try:
+        from tavily import TavilyClient
+
+        client = TavilyClient(api_key=key)
+        response = client.search(
+            query=topic,
+            search_depth=search_depth,
+            max_results=max_results,
+        )
+    except Exception as e:
+        print(f"[DEBUG ERROR] Tavily search failed for '{topic}': {e}")
+        raise SearchError(f"Web search failed: `{e}`")
+
+    results, seen_urls = [], set()
+    for item in response.get("results", []):
+        url = item.get("url", "")
+        content = (item.get("content") or "").strip()
+        if not content or url in seen_urls:
+            continue
+        seen_urls.add(url)
+        results.append({
+            "title": (item.get("title") or url or "Untitled source").strip(),
+            "content": content,
+            "url": url,
+        })
+
+    if not results:
+        raise SearchError("The web search returned no usable results for this topic.")
+    return results

Researchmind-AI/tests/conftest.py

@@ -0,0 +1,93 @@
+import hashlib
+import json
+import re
+import types
+
+import numpy as np
+import pytest
+
+
+class FakeEmbedder:
+    """Deterministic bag-of-words hashing embedder, so similarity reflects shared words (no model download)."""
+
+    def encode(self, texts, convert_to_numpy=True, normalize_embeddings=True, show_progress_bar=False):
+        out = np.zeros((len(texts), 256), dtype="float32")
+        for i, text in enumerate(texts):
+            for word in re.findall(r"[a-z]+", text.lower()):
+                word = re.sub(r"(ing|s)$", "", word)  # crude stemming: drone/drones, monitor/monitoring
+                out[i, int(hashlib.md5(word.encode()).hexdigest(), 16) % 256] += 1
+        if normalize_embeddings:
+            out /= np.maximum(np.linalg.norm(out, axis=1, keepdims=True), 1e-9)
+        return out
+
+
+WEB = {
+    "solar": [
+        {"title": "Agrivoltaics explained", "url": "https://a.example/agri",
+         "content": "Agrivoltaics combines solar panels with crops on the same farmland. It improves land use and farm income. " * 10},
+    ],
+    "drone": [
+        {"title": "Farm drones", "url": "https://b.example/drones",
+         "content": "Drones monitor crops on farmland and help farmers detect plant disease early using imaging. " * 10},
+        {"title": "Cooking pasta", "url": "https://c.example/pasta",
+         "content": "Boil water, add salt, cook pasta for ten minutes and serve with sauce. " * 8},
+    ],
+}
+
+
+def fake_searcher(question, max_results=4, search_depth="basic"):
+    results = []
+    for key, items in WEB.items():
+        if key in question.lower():
+            results += items
+    return results or WEB["solar"]
+
+
+class FakeLLM:
+    """Scripted stand-in for Groq. Role is detected from the system prompt."""
+
+    def __init__(self, bad_claim="The moon is made of cheese"):
+        self.bad_claim = bad_claim
+        self.calls = []
+
+    def complete(self, messages, role="fast", temperature=0.0, json_mode=False):
+        system, user = messages[0]["content"], messages[-1]["content"]
+        self.calls.append(system.split(".")[0])
+        if "Planner" in system:
+            return json.dumps({"sub_questions": ["solar panels on farmland", "drone crop monitoring"]})
+        if "fact-checker" in system:
+            results = []
+            for match in re.finditer(r"CLAIM (\d+): (.*)", user):
+                verdict = "unsupported" if self.bad_claim.lower() in match.group(2).lower() else "supported"
+                results.append({"id": int(match.group(1)), "verdict": verdict, "reason": "scripted"})
+            return json.dumps({"results": results})
+        if "Reviser" in system:
+            report = user.split("A fact-checker flagged")[0].replace("REPORT:\n", "")
+            return "\n".join(l for l in report.split("\n") if self.bad_claim.lower() not in l.lower())
+        if "translator" in system:
+            return "[UR] " + user.split("\n\n", 1)[1]
+        raise AssertionError("unexpected prompt: " + system)
+
+    def stream(self, messages, role="writer", temperature=0.3):
+        self.calls.append("writer")
+        text = (
+            "## Key Findings\n"
+            "Solar panels and crops can share the same farmland [1]. "
+            "Drones help farmers detect plant disease early [2][9].\n"
+            f"{self.bad_claim} [1].\n"
+            "## Conclusion\n"
+            "Both technologies improve how farmland is used [1, 2].\n"
+        )
+        for i in range(0, len(text), 25):
+            yield text[i : i + 25]
+
+
+@pytest.fixture
+def embedder():
+    return FakeEmbedder()
+
+
+@pytest.fixture
+def fake_llm():
+    llm = FakeLLM()
+    return types.SimpleNamespace(complete=llm.complete, stream=llm.stream, raw=llm)

Researchmind-AI/tests/test_app.py

@@ -0,0 +1,61 @@
+import functools
+import os
+
+import pytest
+
+pytest.importorskip("gradio")
+
+import app
+from src import pipeline
+from tests.conftest import fake_searcher
+
+
+@pytest.fixture
+def patched_app(monkeypatch, fake_llm, embedder):
+    """Runs the real UI handler with fake search/LLM/embeddings injected."""
+    monkeypatch.setattr(
+        app,
+        "run_research",
+        functools.partial(pipeline.run_research, searcher=fake_searcher, embedder=embedder, llm_api=fake_llm),
+    )
+    return app
+
+
+def collect(gen):
+    return list(gen)
+
+
+def test_ui_builds_with_expected_controls():
+    assert app.app is not None
+
+
+def test_run_agent_streams_then_offers_md_and_pdf(patched_app):
+    outputs = collect(patched_app.run_agent("AI in agriculture", "Standard", "English", "Standard", True, None))
+    welcome, trace, report, files = outputs[-1]
+    assert "Agent activity" in trace["value"] and "Verification" in report["value"]
+    paths = files["value"]
+    assert files["visible"] and {os.path.splitext(p)[1] for p in paths} == {".md", ".pdf"}
+    assert all(os.path.getsize(p) > 100 for p in paths)
+
+
+def test_urdu_gets_markdown_only_and_rtl(patched_app):
+    outputs = collect(patched_app.run_agent("AI in agriculture", "Standard", "Urdu", "Standard", True, None))
+    _, _, report, files = outputs[-1]
+    assert report.get("rtl") is True
+    assert [os.path.splitext(p)[1] for p in files["value"]] == [".md"]
+
+
+def test_empty_query_keeps_welcome_screen(patched_app):
+    welcome, trace, report, files = collect(patched_app.run_agent("", "Standard", "English", "Standard", True, None))[0]
+    assert welcome["visible"] is True and report["visible"] is False
+
+
+def test_error_event_shows_message_and_no_files(patched_app):
+    outputs = collect(patched_app.run_agent("topic here", "Standard", "English", "Standard", False, None))
+    _, _, report, files = outputs[-1]
+    assert "nothing to research" in report["value"] and files["visible"] is False
+
+
+def test_pdf_handles_emoji_links_and_headings(tmp_path):
+    path = app.create_pdf("# Title\n\n## Sources\n\n1. [Solar & crops](https://x.example/a?b=1&c=2)\n2. 📄 **notes.pdf** (uploaded)\n\n> 🔎 **Verification:** ok")
+    assert path and os.path.getsize(path) > 500

Researchmind-AI/tests/test_pipeline.py

@@ -0,0 +1,230 @@
+import os
+
+import pytest
+
+from src import agents, config, pipeline
+from src.documents import load_documents
+from src.evidence import EvidenceStore
+from tests.conftest import WEB, fake_searcher
+
+
+def run(fake_llm, embedder, **kwargs):
+    events = list(pipeline.run_research(
+        "AI in agriculture", searcher=fake_searcher, embedder=embedder, llm_api=fake_llm, **kwargs
+    ))
+    return events, events[-1]
+
+
+# ------------------------------------------------------------ agents
+def test_parse_json_handles_fences_and_prose():
+    assert agents.parse_json('```json\n{"a": 1}\n```') == {"a": 1}
+    assert agents.parse_json('Sure! {"a": 1} hope that helps') == {"a": 1}
+    assert agents.parse_json("not json") is None
+
+
+def test_planner_falls_back_to_topic_on_garbage(fake_llm):
+    assert agents.plan("my topic", 3, lambda *a, **k: "garbage") == ["my topic"]
+
+
+def test_planner_limits_and_dedupes():
+    reply = '{"sub_questions": ["a", "a", "b", "c", "d"]}'
+    assert agents.plan("t", 3, lambda *a, **k: reply) == ["a", "b", "c"]
+
+
+def test_clean_citations():
+    assert agents.clean_citations("A [1] B [9] C [2, 7] D [2026]", 3) == "A [1] B  C [2] D [2026]"
+    assert agents.clean_citations("x [1, 2]", 5) == "x [1][2]"
+
+
+def test_extract_claims_keeps_citation_with_its_sentence():
+    report = (
+        "## Heading\n"
+        "- Solar panels share land with crops. [1] Drones detect disease early [2].\n"
+        "This sentence has plenty of words but no citation at all in it.\n"
+        "> quoted verification note [1]\n"
+    )
+    claims, uncited = agents.extract_claims(report)
+    assert [c["cites"] for c in claims] == [[1], [2]]
+    assert claims[0]["text"].startswith("Solar panels share land with crops")
+    assert uncited == 1
+
+
+def test_research_web_dedupes_urls_and_collects_errors():
+    from src.search import SearchError
+
+    def searcher(q, max_results, search_depth):
+        if q == "bad":
+            raise SearchError("boom")
+        return [{"title": "T", "url": "https://x", "content": "text"}]
+
+    sources, errors = agents.research_web(["a", "b", "bad"], {"results_per_question": 2, "search_depth": "basic"}, searcher)
+    assert len(sources) == 1 and errors == ["boom"]
+
+
+# ---------------------------------------------------------- evidence
+def test_evidence_ranks_relevant_sources_first_and_drops_irrelevant(embedder):
+    sources = [dict(s, kind="web") for s in WEB["solar"] + WEB["drone"]]
+    store = EvidenceStore(sources, embedder)
+    selected, numbered = store.gather(["solar panels on farmland", "drone crop monitoring"], 5)
+    titles = [s["title"] for s in numbered]
+    assert titles[0] == "Agrivoltaics explained"
+    assert "Cooking pasta" not in titles
+    assert len(selected) <= config.MAX_EVIDENCE_CHUNKS
+    assert all(sum(1 for c in selected if c["source_idx"] == i) <= config.MAX_CHUNKS_PER_SOURCE for i in range(3))
+
+
+def test_support_for_returns_passages_from_cited_source_only(embedder):
+    sources = [dict(s, kind="web") for s in WEB["solar"] + WEB["drone"]]
+    store = EvidenceStore(sources, embedder)
+    store.gather(["solar panels on farmland", "drone crop monitoring"], 5)
+    passages = store.support_for("drones detect plant disease", [2], k=2)
+    assert passages and all("Drones" in p for p in passages)
+    assert store.support_for("anything", [99]) == []
+
+
+# ----------------------------------------------------------- pipeline
+def test_full_agent_loop_catches_and_fixes_unsupported_claim(fake_llm, embedder):
+    events, last = run(fake_llm, embedder)
+    assert last["done"] and not last["error"]
+    result = last["result"]
+
+    # Checker flagged the planted claim, Reviser removed it, re-check is clean
+    m = result["metrics"]
+    assert m["first_pass"]["unsupported"] == 1
+    assert m["final"]["unsupported"] == 0 and m["final"]["support_rate"] == 1.0
+    assert m["revised"] is True
+    assert "cheese" not in result["report"]
+
+    # Invented citation [9] removed, sources + verification note appended
+    assert "[9]" not in result["report"]
+    assert "## Sources" in result["report"] and "https://a.example/agri" in result["report"]
+    assert "Verification" in result["report"]
+
+    # Trace shows every agent
+    trace = last["trace"]
+    for agent in ("Planner", "Researcher", "Retriever", "Writer", "Checker", "Reviser"):
+        assert agent in trace
+    assert "Translator" not in trace
+
+
+def test_draft_streams_progressively(fake_llm, embedder):
+    events, _ = run(fake_llm, embedder)
+    drafts = [e["report"] for e in events if e["report"] and e["report"].startswith("*Draft")]
+    assert len(drafts) >= 3
+
+
+def test_urdu_runs_translator_after_verification(fake_llm, embedder):
+    _, last = run(fake_llm, embedder, language="Urdu")
+    result = last["result"]
+    assert result["report"].startswith("[UR]")
+    assert "cheese" not in result["report_english"]
+    assert "Translator" in last["trace"]
+
+
+def test_documents_only_mode(fake_llm, embedder, tmp_path):
+    doc = tmp_path / "notes.txt"
+    doc.write_text("Greenhouse farming with solar panels on farmland increases crop yield per hectare. " * 10)
+    _, last = run(fake_llm, embedder, use_web=False, document_paths=[str(doc)])
+    assert last["done"]
+    sources = last["result"]["sources"]
+    assert sources and all(s["kind"] == "document" for s in sources)
+    assert "📄" in last["result"]["report"]
+
+
+def test_no_web_and_no_documents_is_a_clear_error(fake_llm, embedder):
+    _, last = run(fake_llm, embedder, use_web=False)
+    assert last["error"] and "nothing to research" in last["report"]
+
+
+def test_empty_topic_is_rejected(fake_llm, embedder):
+    events = list(pipeline.run_research("  ", searcher=fake_searcher, embedder=embedder, llm_api=fake_llm))
+    assert events[-1]["error"]
+
+
+def test_search_failure_without_documents_surfaces_message(fake_llm, embedder):
+    from src.search import SearchError
+
+    def broken(q, max_results=4, search_depth="basic"):
+        raise SearchError("`TAVILY_API_KEY` is missing")
+
+    events = list(pipeline.run_research("topic here", searcher=broken, embedder=embedder, llm_api=fake_llm))
+    assert events[-1]["error"] and "TAVILY_API_KEY" in events[-1]["report"]
+
+
+def test_writer_failure_is_reported_not_raised(embedder, fake_llm):
+    import types
+    from src.llm import LLMError
+
+    def bad_stream(*a, **k):
+        raise LLMError("All Groq models failed.")
+        yield
+
+    broken = types.SimpleNamespace(complete=fake_llm.complete, stream=bad_stream)
+    events = list(pipeline.run_research("topic here", searcher=fake_searcher, embedder=embedder, llm_api=broken))
+    assert events[-1]["error"] and "All Groq models failed" in events[-1]["report"]
+
+
+def test_checker_outage_still_delivers_report(embedder, fake_llm):
+    import types
+    from src.llm import LLMError
+
+    def complete(messages, role="fast", temperature=0.0, json_mode=False):
+        if "Planner" in messages[0]["content"]:
+            return fake_llm.complete(messages, role, temperature, json_mode)
+        raise LLMError("rate limited")
+
+    llm_api = types.SimpleNamespace(complete=complete, stream=fake_llm.stream)
+    _, last = None, list(pipeline.run_research("topic here", searcher=fake_searcher, embedder=embedder, llm_api=llm_api))[-1]
+    assert last["done"] and "unavailable" in last["result"]["report"]
+
+
+def test_reviser_guard_rejects_stub_rewrites(embedder):
+    report = "word " * 200
+    claims = [{"id": 1, "text": "x [1]", "cites": [1]}]
+    results = {1: {"verdict": "unsupported", "reason": "r"}}
+
+    class Store:
+        def support_for(self, *a, **k):
+            return ["evidence"]
+
+    assert agents.revise(report, claims, results, Store(), lambda *a, **k: "ok") == report
+
+
+# ---------------------------------------------------------- documents
+def test_load_documents_pdf_txt_and_warnings(tmp_path):
+    from reportlab.lib.pagesizes import LETTER
+    from reportlab.platypus import Paragraph, SimpleDocTemplate
+    from reportlab.lib.styles import getSampleStyleSheet
+
+    pdf = tmp_path / "paper.pdf"
+    SimpleDocTemplate(str(pdf), pagesize=LETTER).build(
+        [Paragraph("Agrivoltaics lets farmers grow crops under solar panels and earn extra income. " * 5, getSampleStyleSheet()["BodyText"])]
+    )
+    txt = tmp_path / "empty.txt"
+    txt.write_text("hi")
+    odd = tmp_path / "data.xyz"
+    odd.write_text("whatever " * 30)
+
+    docs, warnings = load_documents([str(pdf), str(txt), str(odd)])
+    assert [d["title"] for d in docs] == ["paper.pdf"]
+    assert "Agrivoltaics" in docs[0]["content"] and docs[0]["kind"] == "document"
+    assert len(warnings) == 2
+
+
+# ---------------------------------------------------------- evaluation
+def test_evaluate_aggregates_and_writes_reports(fake_llm, embedder, tmp_path):
+    import functools
+
+    import evaluate
+
+    runner = functools.partial(pipeline.run_research, searcher=fake_searcher, embedder=embedder, llm_api=fake_llm)
+    rows = [evaluate.evaluate_topic("AI in agriculture", "Quick", runner)]
+    rows.append(evaluate.evaluate_topic("x", "Quick", runner))          # too short -> failure row
+    assert rows[0]["ok"] and rows[0]["support_first"] < rows[0]["support_final"] == 1.0
+    assert not rows[1]["ok"]
+
+    summary = evaluate.aggregate(rows)
+    assert summary["completed"] == 1 and summary["revised_count"] == 1
+    evaluate.write_outputs(rows, summary, str(tmp_path), "Quick")
+    text = (tmp_path / "RESULTS.md").read_text(encoding="utf-8")
+    assert "first draft" in text and "100%" in text and (tmp_path / "results.json").exists()