Update README.md

README.md

@@ -1,11 +1,78 @@
 ---
-title: 810proj
-emoji: 🌍
-colorFrom: red
-colorTo: blue
+title: Journal Authority Auditor
+emoji: 🛡️
+colorFrom: blue
+colorTo: indigo
 sdk: docker
-pinned: false
-short_description: this is for 810proj LLM agent
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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.*