README.md

---
title: Journal Authority Auditor
emoji: 🛡️
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
---

# Journal Authority Auditor Agent 🛡️

**🔗 Live App:** [https://huggingface.co/spaces/jscmp4/810proj](https://huggingface.co/spaces/jscmp4/810proj)

## 1. What the code does
This project implements an autonomous **AI Agent** designed to audit the academic authority of journals and research papers. It serves as a "Glass Box" tool for researchers to verify credibility instantly.

Key capabilities include:
* **Hybrid RAG Architecture:** Combines strict database lookups (MongoDB with 31,000+ Scimago records) with the semantic reasoning of Large Language Models (GPT-4o).
* **Intelligent Routing:** Automatically determines whether to search by **DOI** (using OpenAlex API) or by **Journal Name**.
* **Fail-Safe Reasoning:** If a journal is not found in the verified database, the agent falls back to its internal parametric knowledge to assess the publisher's reputation (e.g., IEEE, ACM) and provide a reasoned risk assessment.
* **Real-Time "Thinking" Logs:** A dual-pane interface displays the agent's **Chain-of-Thought (CoT)**, showing exactly which tools are being called and what data is retrieved, ensuring transparency.

## 2. Structure of the code
The project follows a containerized micro-framework structure powered by **Flask** and **Docker**.

### File Breakdown:
* **`app.py`**: The core application logic containing:
    * **Frontend**: A responsive HTML/JS/CSS interface rendered via Flask templates. It handles the dual-pane layout (Chat UI + Terminal Log) and Markdown rendering.
    * **Backend API (`/chat`)**: Handles POST requests and orchestrates the agent loop.
    * **Agent Logic (`run_agent_with_logs`)**: Implements a `while` loop that allows the LLM to autonomously call tools multiple times (Reasoning -> Acting -> Observation) before generating a final answer.
    * **Tools**:
        * `fetch_metadata`: Connects to **OpenAlex API** to resolve DOIs and identify publishers.
        * `check_ranking`: Connects to **MongoDB Atlas** to retrieve verified metrics (SJR Quartile, H-Index, Citation rates).
* **`GenAI.ipynb`**: **[Database Maintenance]** A Jupyter Notebook used for backend data engineering. It handles:
    * Fetching the latest SJR rankings CSV.
    * Cleaning data (handling Euro-style formats).
    * Upserting cleaned records into the MongoDB cloud database.
* **`Dockerfile`**: Defines the Python 3.9 environment, installs dependencies, creates a non-root user for security, and exposes port 7860.
* **`requirements.txt`**: Lists dependencies (`flask`, `openai`, `pymongo`, `requests`, `pyngrok`).

## 3. How to prepare to run
The application is containerized and requires specific API keys to function.

### Environment Variables (Secrets)
To run this code, the following environment variables must be set (in Hugging Face Settings or a local `.env` file):
* `OPENAI_API_KEY`: Required for the Agent's reasoning capabilities (GPT-4o).
* `MONGO_USER` & `MONGO_PASS`: Credentials for the MongoDB Atlas Cloud Database.
* `MONGO_CLUSTER`: The address of the MongoDB cluster.

### Dependencies
No local preparation is needed if accessing via the Hugging Face Web Interface. For local development, Python 3.9+ is required.

## 4. How to run

### Method A: Online (Recommended for Grading)
Simply click the **"App"** tab at the top of this Hugging Face Space or visit:
[https://huggingface.co/spaces/jscmp4/810proj](https://huggingface.co/spaces/jscmp4/810proj)

The application is pre-deployed and running 24/7.

### Method B: Local Execution (Docker)
1.  **Clone the repository:**
    ```bash
    git clone [https://huggingface.co/spaces/jscmp4/810proj](https://huggingface.co/spaces/jscmp4/810proj)
    cd 810proj
    ```
2.  **Build the Docker image:**
    ```bash
    docker build -t journal-auditor .
    ```
3.  **Run the container** (Injecting your API keys):
    ```bash
    docker run -p 7860:7860 -e OPENAI_API_KEY="sk-..." -e MONGO_PASS="..." journal-auditor
    ```
4.  **Access:** Open `http://localhost:7860` in your browser.

---
*Project submitted for CS810.*