update

Author: iCGY96

README.md

@@ -1,151 +1,134 @@
-# EMSeek: Autonomous Agents for Electron Microscopy & Materials Analysis  
-
-**EMSeek** is a modular, provenance-tracked multi-agent platform that connects raw electron microscopy (EM) images to materials structures and property insights. It automates end-to-end workflows—segmentation, crystallographic reconstruction, property prediction, literature grounding, and audit reporting—powered by LLM/MLLM orchestration.  
-
----
-
-## ✨ Key Features  
-
-- **SegMentor** – Reference-guided, all-in-one segmentation  
-- **CrystalForge** – Mask-aware EM → CIF reconstruction  
-- **MatProphet** – Gated Mixture-of-Experts property predictor with uncertainty calibration  
-- **ScholarSeeker** – Literature retrieval with citation anchoring  
-- **Guardian + Scribe** – Physical consistency checks and audit-ready reporting  
-
----
-
-
-## ⚙️ Installation  
-
-**Requirements:** Python 3.10+, Linux/macOS preferred. GPU optional (PyTorch auto-detects CUDA).  
-
-1. Create environment:  
+<p align="center">
+  <img src="./samples/Logo.jpg" alt="EMSeek logo" width="420px" />
+</p>
+
+<p align="center">
+<a href="docs/architecture.md">
+<img src="https://img.shields.io/badge/Read-Architecture-1e3a8a?style=for-the-badge" alt="Architecture Doc" />
+</a>
+<a href="docs/agent-controllers.md">
+<img src="https://img.shields.io/badge/Study-Agent%20Manual-2563eb?style=for-the-badge" alt="Agent Manual" />
+</a>
+<a href="LICENSE">
+<img src="https://img.shields.io/badge/License-Apache%202.0-22c55e?style=for-the-badge" alt="License" />
+</a>
+<a href="https://github.com/PEESE/EMSeek/issues">
+<img src="https://img.shields.io/badge/Open-Issues-f97316?style=for-the-badge&logo=github" alt="Open Issues" />
+</a>
+</p>
+
+# Bridging Electron Microscopy and Materials Analysis with an Autonomous Agentic Platform
+
+## Overview
+EMSeek bridges raw electron microscopy (EM) data to actionable materials insights by pairing advanced reasoning with specialised actions. Rather than a monolithic model, EMSeek runs a provenance-tracked multi-agent system where a Maestro planner delegates work to targeted controllers, maintains shared memory, and streams NDJSON progress so every decision is auditable.
+
+### Why EMSeek Matters
+- Unifies perception, structure modelling, property inference, and literature reasoning into a reproducible, provenance-tracked workflow for EM.
+- Automates complex multi-stage analyses across diverse materials modalities with minimal human intervention.
+- Provides audit-ready artefacts, uncertainty calibration, and physical sanity checks to keep researchers in control.
+- Scales from exploratory analysis to production by exposing both browser and programmable interfaces, backed by configurable models and data stores.
+
+## Demo
+<p align="center">
+  <a href="https://youtu.be/GWGP8g39lV8" target="_blank" rel="noopener noreferrer">
+    <img src="https://img.youtube.com/vi/GWGP8g39lV8/hqdefault.jpg" alt="EMSeek demo video" width="720" />
+  </a>
+</p>
+
+## Quick Start
+
+### 1. Clone & Create an Environment
 ```bash
-conda create -n emseek python=3.10 -y && conda activate emseek
-# or
-python -m venv .venv && source .venv/bin/activate
+git clone https://github.com/PEESE/EMSeek.git
+cd EMSeek
+conda create -n emseek python=3.10 -y
+conda activate emseek
+# or: python -m venv .venv && source .venv/bin/activate
 ```
 
-2. Install PyTorch (CPU/CUDA): [official guide](https://pytorch.org/get-started/locally/)  
-
-3. Install dependencies:  
+### 2. Install Core Dependencies
+Follow PyTorch's [official instructions](https://pytorch.org/get-started/locally/) for your platform (CPU-only is fine). Then install the EMSeek stack:
 ```bash
 pip install flask gunicorn litellm requests numpy pillow opencv-python scikit-image scipy matplotlib tqdm joblib ase pymatgen torchvision
 ```
 
-**Optional packages:**  
-- Literature Q&A: `pip install paper-qa`  
-- Segmentation models: `pip install segmentation-models-pytorch`  
-- Property backends (UMA/MACE/MatterSim): `pip install fairchem mace-torch mattersim`  
+**Optional extras**
+- Literature Q&A: `pip install paper-qa`
+- Segmentation family: `pip install segmentation-models-pytorch`
+- Property backends (UMA, MACE, MatterSim): `pip install fairchem mace-torch mattersim`
 
-4. Set API keys:  
+### 3. Provide API Keys
+EMSeek speaks to LLM/MLLM providers via LiteLLM. Export the keys you need (OpenAI-compatible shown below) before launching:
 ```bash
-export OPENAI_API_KEY=your_key_here
-# optional
-export CORE_API_KEY=your_key_here
+export OPENAI_API_KEY="your_openai_key"
+# Optional providers
+export CORE_API_KEY="your_core_key"
+export LLM_MODEL="gpt-5-nano"           # overrides cfg.py defaults
+export MLLM_MODEL="gpt-4o-mini"         # vision-capable model for captions
 ```
 
----
+### 4. Fetch Models & Reference Data
+- Place segmentation and property checkpoints under `pretrained/` according to `cfg.py:TASK2MODEL`.
+- Add crystal structure libraries to `database/cif_lib/` (CIF files).
+- Drop supporting PDFs into `database/papers_lib/` for offline literature review.
+- Runtime logs and artefacts land in `history/<user>/<session>/` automatically.
 
-## 📦 Data & Models  
-
-- Download pretrained weights from [Google Drive](https://drive.google.com/drive/folders/1ltlPT8bclLc9QXfSOEWyKm64ZdtSPxQM?usp=sharing) and place them in `pretrained/` (see `cfg.py:TASK2MODEL`).  
-- Place `.cif` files in `database/cif_lib/`.  
-- Place PDFs in `database/papers_lib/`.  
-
-Artifacts & logs are written to:  
-```
-history/<user_id>/
- ├── logs/       # JSONL traces
- └── artifacts/  # masks, overlays, CIFs, patches, etc.
-```
-
----
-
-## 🚀 Usage  
-
-### Web UI (dev mode)  
+### 5. Launch & Smoke-Test
+**Browser UI (development):**
 ```bash
 python app.py
 # visit http://localhost:8000
 ```
 
-### Production (gunicorn)  
+**Production-ready gunicorn:**
 ```bash
-sh run.sh
-# binds to 0.0.0.0:8000
+gunicorn -w 2 -k gevent -b 0.0.0.0:8000 "app:app"
 ```
 
-### Avoiding 413 (Upload Too Large)  
-If you see “Upload too large (413)” when sending image-only requests, your reverse proxy is likely rejecting the request body. Increase the proxy limit and (optionally) Flask’s content length:
-
-- Nginx: set a larger limit in http/server/location blocks and reload Nginx:
-  - `client_max_body_size 50M;`
-  - `proxy_read_timeout 600s;`
-  - See `deploy/nginx.conf.example` for a complete example.
-- Flask: the app honors `MAX_UPLOAD_MB` (default 100). Example: `export MAX_UPLOAD_MB=200` before starting.
-
-Alternatively, downscale or compress images before uploading to reduce payload size.
-
-### REST API (NDJSON streaming)  
+**REST NDJSON request:**
 ```bash
-curl -N -H 'Content-Type: application/json'   -d '{
-        "text": "Segment image and explain",
-        "files": ["/abs/path/to/em.png"],
-        "model": "general_model"
-      }'   http://localhost:8000/api
+curl -N -H 'Content-Type: application/json' \
+  -d '{"text": "Segment and describe the uploaded EM image.", "files": ["/abs/path/to/image.png"], "model": "general_model"}' \
+  http://localhost:8000/api
 ```
 
-### Python API  
+**Python API:**
 ```python
 from emseek.platform import Platform
 import cfg
 
-plat = Platform(cfg)
-plat.init_agent()
+platform = Platform(cfg)
+platform.init_agent()
 
-payload = {"text": "Segment EM image", "files": ["em.png"]}
-for line in plat.query_unified(payload):
-    print(line.strip())  # JSON objects (step/final)
+payload = {"text": "Segment EM image", "files": ["samples/oblique_AgBiSb2S6-1cbf0237027e_supercell_24x20x1_dose30000_sampling0.1_iDPC_V3.png"]}
+for frame in platform.query_unified(payload):
+    print(frame.strip())  # JSON objects per step/final
 ```
 
----
-
-## 🔧 LLM/MLLM Generation Settings
-
-Configure token and temperature limits centrally in `cfg.py` (overridable via environment variables):
-
-- LLM_MAX_TOKENS (env: `LLM_MAX_TOKENS`, default: 10240)
-- LLM_TEMPERATURE (env: `LLM_TEMPERATURE`, default: 1.0)
-- MLLM_MAX_TOKENS (env: `MLLM_MAX_TOKENS`, default: 10240)
-- MLLM_TEMPERATURE (env: `MLLM_TEMPERATURE`, default: 1.0)
-
-All internal `llm`/`mllm` calls respect these settings unless explicitly overridden at the call site.
-
----
+If uploads are rejected with HTTP 413, raise the proxy limit (`client_max_body_size` in Nginx) and optionally export `MAX_UPLOAD_MB` before starting Flask.
 
-## 🧩 Core Agents  
 
-- **MaestroAgent** – Orchestration & planning  
-- **SegMentorAgent** – Segmentation + visual LLM explanation  
-- **CrystalForgeAgent** – EM→CIF retrieval with similarity scoring  
-- **MatProphetAgent** – MoE property prediction with uncertainty signals  
-- **ScholarSeekerAgent** – PaperQA with CORE/local fallback  
-- **AnalyzerHubAgent** – Unified tool routing (HyperSpy, py4DSTEM, pymatgen, etc.)  
-- **GuardianAgent** – Physical consistency & audit checks  
-- **ScribeAgent** – Structured final report  
+## Configuration Surface
+All runtime knobs live in `cfg.py`:
+- Model identifiers (`LLM_MODEL`, `MLLM_MODEL`, `EMBEDDING_MODEL`).
+- Generation limits (`LLM_MAX_TOKENS`, `MLLM_TEMPERATURE`, etc.).
+- Data roots (`HISTORY_ROOT`, `CIF_LIB_DIR`, `PDF_FOLDER`).
+- Concurrency and streaming heartbeats.
 
----
+Environment variables override module defaults, so ops teams can configure deployments without editing code.
 
-## 📜 License  
 
-This project is licensed under the terms in the [LICENSE](./LICENSE) file.  
+## Observability & Provenance
+- Every agent step logs JSONL traces and writes artefacts under `history/<user>/<session>/` for audit trails.
+- Guardian and Scribe attach provenance metadata, curated context, and uncertainty summaries to outputs.
+- Session JSON records persist the latest conversations per user, powering history recall in the web UI.
 
----
 
-## 📖 Citation  
+## Contributing
+We welcome pull requests for new agents, analysis tools, retrieval pipelines, and documentation. Open an issue to discuss ideas or share reproducible bug reports. Please ensure new features include tests or runnable notebooks when applicable and respect existing logging and provenance patterns.
 
-If EMSeek is useful for your work, please cite:  
+## License & Citation
+This project is released under the [Apache License 2.0](LICENSE).
 
 ```bibtex
 @misc{chen2025emseek,