(DOCS): finalize research-grade README with agnostic OCI instructions and scientific baseline

README.md

@@ -1,180 +1,119 @@
 ---
-title: Polymer Aging with ML
+title: "PolymerOS: Predictive Framework for Polymer Aging"
 emoji: 🔬
 colorFrom: blue
 colorTo: green
 sdk: docker
 app_port: 7860
 pinned: false
-license: mit
+license: apache-2.0
 ---
 
-# PolymerOS: AI-Driven Polymer Aging Prediction and Classification
+# PolymerOS: A Computational Framework for Degradation-Aware Plastic Classification
 
 ![React](https://img.shields.io/badge/React-18.2-brightgreen)
 ![FastAPI](https://img.shields.io/badge/FastAPI-0.116%2B-blue)
-![PyTorch](https://img.shields.io/badge/PyTorch-ML--Core-red)
-![Docker](https://img.shields.io/badge/docker-ready-blue)
+![PyTorch](https://img.shields.io/badge/PyTorch-2.6-red)
+![OCI](https://img.shields.io/badge/container-ready-blue)
 ![License](https://img.shields.io/badge/License-Apache%202.0-blue)
 
+[**Live Interactive Dashboard**](https://huggingface.co/spaces/dev-jas/polymer-aging-with-ml) | [**Official Repository**](https://github.com/KLab-AI3/ml-polymer-recycling)
+
 ---
 
 ## Overview
 
-**PolymerOS** is a full-stack AI application that classifies the degradation state of polymers using **Raman** and **FTIR spectroscopy**.
-It enables scientists, engineers, and researchers to upload spectroscopic data and receive predictions on whether materials are **stable (unweathered)** or **weathered (degraded)**.
+**PolymerOS** is the official computational framework for the predictive aging of plastics as described in the manuscript *"Predictive Framework to Indicate the Age of Plastics for Proper Recycling."*
 
-This platform was designed for both research reproducibility and production-grade deployment. Every prediction includes **scientific provenance tracking**, ensuring transparency in preprocessing, QC checks, and model metadata.
+Conventional mechanical recycling often overlooks the degradation history of materials, leading to inconsistent product quality. This framework utilizes **deep learning applied to Raman and FTIR spectroscopy** to identify early-stage chemical and physical aging signatures. It provides a standardized, secure, and reproducible environment for the scientific classification of aged versus unaged polymers.
 
 ---
 
-## Features
+## Core Research Artifacts
 
-- **Multi-Modal Input**: Supports Raman and FTIR data
-- **Flexible File Formats**: Accepts `.txt`, `.csv`, `.json` (auto-detected)
-- **Model Zoo**: Figure2CNN, ResNet1D, ResNet18Vision, and custom CNNs
-- **Batch & Single-Spectrum Analysis**
-- **Multi-Model Comparison**
-- **Provenance Tracking**: QC checks + preprocessing metadata
-- **Performance Dashboard**
-- **RESTful API** for programmatic access
-- **Modern UI**: React + TypeScript, charting with Recharts
+### 1. Model Zoo
+Verified architectures and weights for the following models are provided:
+- **Figure2CNN**: High-performance binary classifier (Aged vs. Unaged) optimized for spectral data.
+- **ResNet1D**: Benchmarked 1D-convolutional architecture for spectral feature extraction.
+- **Preprocessing Pipeline**: A standardized 4-step sequence including asymmetric least-squares baseline correction, Savitzky–Golay smoothing, min-max normalization, and resampling to 4000 spectral points.
 
----
+### 2. Standalone Scientific Appliance
+To facilitate reproducibility and practical use by researchers, the entire pipeline—including the interactive dashboard, inference engine, and preprocessing logic—is delivered as a **portable OCI container**.
 
-## Architecture
+---
 
-PolymerOS is a **monorepo** with a React frontend and FastAPI backend, packaged for **single-container deployment**.
+## Technical Architecture
 
 ```text
-polymeros/
+ml-polymer-recycling/
 ├── backend/
-│   ├── main.py               # FastAPI entrypoint: routes, middleware, startup
-│   ├── service.py            # Core MLInferenceService logic
-│   ├── pydantic_models.py    # API contracts for request/response validation
-│   ├── utils/                # Preprocessing, performance, orchestration
-│   └── models/
-│       ├── registry.py       # Model registry for AI models
-│       └── figure2_cnn.py    # Example CNN implementation
+│   ├── main.py               # API entrypoint and static asset server
+│   ├── models/
+│   │   └── weights/          # Model binaries (.pth managed via Git LFS)
+│   ├── utils/
+│   │   ├── model_manager.py  # Hardened PyTorch 2.6 safe-loading logic
+│   │   └── preprocessing.py  # Standardized 4-step spectral preprocessing
+│   └── service.py            # Core inference orchestration
 ├── frontend/
-│   ├── src/
-│   │   ├── App.tsx           # Main React app shell
-│   │   ├── apiClient.ts      # Centralized API calls
-│   │   ├── components/       # Reusable UI components
-│   │   └── types/api.ts      # Auto-generated TypeScript types
-│   └── package.json
-├── models/weights/           # Directory for trained model weights (.pth)
-├── Dockerfile                # Multi-stage build for backend+frontend
-└── main.py                   # Root entrypoint: serves frontend + backend
-```
-
----
-
-## Data Flow
-
-Example: Standard Spectrum Analysis
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant UI as React UI
-    participant API as FastAPI Backend
-    participant ML as ML Service
-    User->>UI: Upload spectrum file
-    UI->>API: POST /api/v1/upload
-    API->>ML: Parse + preprocess spectrum
-    ML->>ML: Run model inference
-    ML-->>API: PredictionResult (class + confidence + provenance)
-    API-->>UI: JSON response
-    UI-->>User: Display prediction & visualization
+│   ├── src/                  # React/TypeScript source code
+│   │   └── apiClient.ts      # Location-agnostic API Client
+│   └── dist/                 # Compiled production assets
+├── Dockerfile                # Multi-stage hardened OCI build configuration
+├── requirements.txt          # Python environment specifications
+└── .gitattributes            # Git LFS tracking for model weights
 ```
 
 ---
 
-## Getting Started
-
-### Prerequisites
-
-- Python 3.10+
-- Node.js 16+
-- npm
-- Git
-
-### Setup
-
-```bash
-# Clone repo
-git clone https://github.com/devjas1/polymeros.git
-cd polymeros
-
-# Backend setup
-pip install -r backend/requirements.txt
-
-# Frontend setup
-cd frontend
-npm install
-cd ..
-```
+## Reproducibility & Local Operation
 
-### Run (Dev Mode)
+### 1. Prerequisites
+- **Git LFS** (Required to download model weight binaries).
+- **Docker** or **Podman**.
 
+### 2. Setup
 ```bash
-# Backend (FastAPI with live reload)
-uvicorn backend.main:app --reload --port 8000
+# Clone the official repository
+git clone https://github.com/KLab-AI3/ml-polymer-recycling.git
+cd ml-polymer-recycling
 
-# Frontend (React)
-cd frontend
-npm start
+# Initialize LFS and pull model weights
+git lfs install
+git lfs pull
 ```
 
-### Run (Single-Container)
+### 3. Running the Dashboard
+To ensure bit-perfect scientific parity with the benchmarks reported in the manuscript, we recommend running the framework as a standalone appliance. The container is internally hardened to run in a restricted, read-only state.
 
 ```bash
-python main.py
-```
+# Build the appliance
+docker build -t polymer-os .
 
-Access the app at: **http://localhost:8000**
-
----
-
-## Tests
-
-```bash
-# From repo root
-export PYTHONPATH=$PWD
-pytest backend/tests
+# Launch the dashboard
+docker run -p 7860:7860 polymer-os
 ```
+The interactive interface will be available at: **http://localhost:7860**
 
 ---
 
-## Deployment
+## Security & Agnosticism
 
-### Docker
-
-```bash
-docker build -t polymeros .
-docker run -p 8000:8000 polymeros
-```
-
-### Hugging Face Spaces
-
-PolymerOS is optimized for deployment on Hugging Face Spaces with unified API + UI on a single port.
+- **PyTorch 2.6 Enforcement**: Models are loaded using the hardened `weights_only=True` standard to ensure safe execution in public environments.
+- **Environment Aware**: The "Agnostic" API client automatically detects host and port settings, ensuring seamless transitions between local workstations and cloud providers like Hugging Face Spaces.
 
 ---
 
 ## Contributors
 
-- **Dhoopshikha Lakshmi Devi Basgeet**
-- **Jaser Hasan** — Developer
+- **Dhoopshikha Lakshmi Devi Basgeet** — Lead Author
+- **Jaser Hasan** — Lead Developer / Technical Audit
 - **Konpal Raheja**
 - **Divita Mathur**
-- **Dr. Sanmukh Kuppannagari** — Mentor
-- **Dr. Metin Karailyan** — Mentor
+- **Dr. Sanmukh Kuppannagari** — Corresponding Author
+- **Dr. Metin Karayilan** — Corresponding Author
 
 ---
 
 ## License
 
-Apache 2.0 — see [LICENSE](LICENSE)
-
----
+Licensed under the Apache License, Version 2.0 (the "License"); see [LICENSE](LICENSE) for details.