Pin Python 3.10

README.md

@@ -5,17 +5,222 @@ colorFrom: blue
 colorTo: purple
 sdk: gradio
 sdk_version: "4.44.0"
+python_version: "3.10"
 app_file: app.py
 pinned: false
 ---
 
-<h1 align="center">
-  StegNet : Deep Learning-Based Image Steganography with Encryption and Super Resolution
-</h1>
+# StegNet — AI-Based Secure Image Steganography Platform
 
-<p align="center">
-  <img src="app/ui/logo.png" alt="Project Logo" width="100">
-</p>
+> **Context document for LLMs and AI agents working on this codebase.**
+> Read this fully before making any changes.
+
+---
+
+## 1. What This Project Does
+
+StegNet is a Python-based web application that lets users:
+
+1. **Hide** a secret image inside a cover image using a deep learning CNN model (steganography)
+2. **Reveal** the hidden image from a steg image using a second CNN model
+3. **Encrypt / Decrypt** the steg image using AES or Blowfish (CBC mode, SHA-256 key hashing)
+4. **Upscale** any image 4× using ESRGAN (Enhanced Super Resolution GAN)
+5. **Generate** images from text prompts via the HuggingFace Stable Diffusion 2.1 API
+
+The web interface is built with **Gradio** and deployed on **HuggingFace Spaces**.
+
+---
+
+## 2. Repository Structure
+
+```
+StegNet/
+├── app.py                          # ENTRY POINT — Gradio web UI (6 tabs)
+├── requirements.txt                # Python dependencies
+├── README.md                       # This file
+└── app/
+    ├── __init__.py
+    ├── main_CLI_v1.py              # Legacy CLI script (not used in web)
+    ├── models/
+    │   ├── DEEP_STEGO/
+    │   │   ├── hide_image.py       # hide_image(cover_path, secret_path) → steg_path
+    │   │   ├── reveal_image.py     # reveal_image(steg_path) → secret_path
+    │   │   ├── train.py            # Model training script (not used at runtime)
+    │   │   ├── models/
+    │   │   │   ├── hide.h5         # Trained hide network weights (TensorFlow/Keras)
+    │   │   │   └── reveal.h5       # Trained reveal network weights
+    │   │   ├── checkpoints/
+    │   │   │   └── steg_model-06-0.03.hdf5
+    │   │   └── Utils/
+    │   │       ├── preprocessing.py        # normalize_batch / denormalize_batch
+    │   │       ├── customLossWeight.py     # custom_loss_1, custom_loss_2 (MSE)
+    │   │       ├── enhance.py
+    │   │       ├── eval.py
+    │   │       └── progressbarCL_animation.py
+    │   ├── ESRGAN/
+    │   │   ├── upscale_image.py    # upscale_image(image_path) → output_path
+    │   │   ├── RRDBNet_arch.py     # RRDB network architecture (PyTorch)
+    │   │   ├── model.py
+    │   │   ├── net_intrep.py
+    │   │   ├── test.py
+    │   │   └── models/
+    │   │       └── RRDB_ESRGAN_x4.pth   # Pretrained ESRGAN weights (PyTorch)
+    │   ├── encryption/
+    │   │   ├── aes.py              # encrypt(path, key) / decrypt(path, key)
+    │   │   └── blowfish.py         # encrypt(path, key) / decrypt(path, key)
+    │   ├── StableDiffusionAPI/
+    │   │   └── StableDiffusionV2.py  # generate(text_prompt) → PIL Image
+    │   └── StackGAN/               # Empty placeholder
+    └── ui/
+        └── main.py                 # Legacy PyQt5 desktop GUI (NOT used in web)
+```
+
+---
+
+## 3. Key Function Signatures
+
+### Steganography
+```python
+# app/models/DEEP_STEGO/hide_image.py
+def hide_image(cover_image_filepath: str, secret_image_filepath: str) -> str:
+    """Hides secret inside cover. Returns path to steg image (tempfile .png)."""
+
+# app/models/DEEP_STEGO/reveal_image.py
+def reveal_image(stego_image_filepath: str) -> str:
+    """Extracts hidden image from steg. Returns path to revealed image (tempfile .png)."""
+```
+
+### Encryption
+```python
+# app/models/encryption/aes.py and blowfish.py
+def encrypt(image_path: str, key: str) -> None:
+    """Encrypts image file. Saves to image_path + '.enc'."""
+
+def decrypt(encrypted_image_path: str, key: str) -> tuple[int, str | None]:
+    """Decrypts. Returns (0, output_path) on success, (-1, None) on wrong key."""
+```
+
+### Super Resolution
+```python
+# app/models/ESRGAN/upscale_image.py
+def upscale_image(image_filepath: str) -> str:
+    """4× upscale using ESRGAN. Returns output path (tempfile .png)."""
+```
+
+### Image Generation
+```python
+# app/models/StableDiffusionAPI/StableDiffusionV2.py
+def generate(text_prompt: str) -> PIL.Image:
+    """Calls HuggingFace Stable Diffusion 2.1 API. Requires HF_API_KEY env var."""
+```
+
+---
+
+## 4. Model Architecture
+
+### Deep Steganography (TensorFlow/Keras)
+- Input: 224×224 RGB images (cover + secret), normalized with ImageNet stats
+- **Prepare Network**: 3 parallel Conv2D branches (3×3, 4×4, 5×5 kernels, 50 filters each) → concatenated → final branch
+- **Hide Network**: Concatenates cover + prepared secret features → same multi-scale conv structure → outputs 3-channel steg image
+- **Reveal Network**: Takes steg image (with Gaussian noise during training) → recovers secret
+- Loss: Custom MSE — hide weight 1.0, reveal weight 0.75
+- Preprocessing: channel-wise z-score with ImageNet mean/std
+
+### ESRGAN (PyTorch)
+- `RRDBNet(3, 3, 64, 23, gc=32)` — 23 RRDB blocks, 64 features, 32 growth channels
+- 4× spatial upscaling
+- Runs on CUDA if available, falls back to CPU automatically
+- Model loaded lazily (once, on first call)
+
+---
+
+## 5. Environment & Dependencies
+
+```
+tensorflow          # hide/reveal CNN models
+torch               # ESRGAN
+torchvision
+opencv-python-headless   # image I/O (headless = no GUI deps)
+Pillow              # image processing
+pycryptodome        # AES + Blowfish encryption
+gradio              # web UI
+numpy
+imageio             # saving numpy arrays as images
+requests            # Stable Diffusion API calls
+```
+
+**Python version:** 3.10+ recommended  
+**GPU:** Optional. ESRGAN auto-detects CUDA; steganography runs on CPU fine.
+
+---
+
+## 6. Environment Variables
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `HF_API_KEY` | Optional | HuggingFace API token for Stable Diffusion image generation tab |
+
+Set as a HuggingFace Space secret or local env variable.
+
+---
+
+## 7. Deployment
+
+**Live URL:** https://huggingface.co/spaces/savetrees/StegNet  
+**GitHub:** https://github.com/savetree-1/stego-net  
+**Platform:** HuggingFace Spaces (Gradio SDK, CPU Basic, free tier)  
+**Git LFS:** All binary files (`*.h5`, `*.pth`, `*.hdf5`, `*.npy`, `*.png`, `*.jpg`) are tracked with Git LFS.
+
+### Run locally
+```bash
+git clone https://github.com/savetree-1/stego-net.git
+cd stego-net
+pip install -r requirements.txt
+python app.py
+```
+
+### Push updates
+```bash
+git add .
+git commit -m "your message"
+# HuggingFace
+git push https://savetrees:HF_TOKEN@huggingface.co/spaces/savetrees/StegNet main
+# GitHub
+git push https://savetree-1:GH_TOKEN@github.com/savetree-1/stego-net.git main
+```
+
+---
+
+## 8. Important Implementation Notes
+
+- **Model paths** are resolved relative to each file using `os.path.dirname(os.path.abspath(__file__))` — never hardcoded absolute paths
+- **Models are lazy-loaded** (loaded once on first inference call, cached in module-level `_model` variable)
+- **Output files** use `tempfile.mkstemp(suffix='.png')` — caller receives the path
+- **Encryption output** saves to `original_path + '.enc'`; decryption saves to `original_path.dec.png`
+- The `app/ui/main.py` PyQt5 desktop GUI is **not used** in the web deployment — ignore it
+- The `app/main_CLI_v1.py` CLI script is **not used** in the web deployment — ignore it
+- `imageio.imsave` is used instead of PIL/cv2 for saving numpy uint8 arrays from model output
+
+---
+
+## 9. Known Issues & Limitations
+
+- ESRGAN is slow on CPU (HuggingFace free tier) — expect 30–60s for upscaling
+- Steganography models resize all input to 224×224 — output is always 224×224
+- HuggingFace free tier sleeps after inactivity — first request may be slow
+- Image generation requires `HF_API_KEY` env var — disabled if not set
+
+---
+
+## 10. Original Project
+
+This project was originally called **InvisiCipher** (by Asirwad). It has been:
+- Rebranded to **StegNet**
+- Converted from a PyQt5 desktop app to a Gradio web app
+- Fixed hardcoded Windows paths replaced with portable relative paths
+- Added CPU fallback for ESRGAN
+- Added model lazy-loading
+- Removed hardcoded API key file dependency (now uses env var)
 
 <p align="center">
   <strong>Hide secrets, enhance images!</strong>