Update README.md

README.md

@@ -7,214 +7,145 @@ colorFrom: green
 colorTo: gray
 sdk_version: 1.51.0
 ---
-#  Python → Streamlit Converter Pro
+# PyStreamlit Converter Pro
 
-A powerful, production-ready tool that converts Python scripts and Jupyter Notebooks into fully functional Streamlit applications. Handles large files, preserves comments and markdown, and provides multiple conversion strategies.
+> Transform **Jupyter Notebooks** and **Python scripts** into polished, interactive **Streamlit apps** — in seconds.
 
-## ✨ Features
-
-### Core Capabilities
-- **Multi-Format Support**: Convert `.py` files and `.ipynb` notebooks
-- **Large File Handling**: Efficiently processes files up to 5MB+ with optimized algorithms
-- **Comment Preservation**: All comments, docstrings, and inline documentation are preserved
-- **Markdown Support**: Notebook markdown cells are converted to commented Python code
-- **Batch Processing**: Upload ZIP archives to convert multiple files at once
-
-### Conversion Strategies
 
-1. **Hybrid Mode (Recommended)**: Combines AST parsing with regex patterns
-   - Best balance of accuracy and performance
-   - Handles complex code structures
-   - Preserves formatting and comments
+---
 
-2. **AST Mode (Precise)**: Pure abstract syntax tree transformation
-   - Deep understanding of code structure
-   - Best for complex transformations
-   - Preserves all code semantics
+## ✨ Features
 
-3. **Regex Mode (Fast)**: Pattern-based matching
-   - Fastest for very large files
-   - Good for simple conversions
-   - Efficient memory usage
+| Feature | Description |
+|---|---|
+| **Hybrid Conversion Engine** | Three-pass AST + regex pipeline for accurate, reliable conversion |
+| **Deep Code Analysis** | Complexity metrics, library detection, function/class inventory |
+| **Widget Suggester** | Scans hard-coded literals and proposes sidebar sliders, checkboxes, inputs |
+| **Diff Viewer** | Unified-diff comparison with configurable context lines |
+| **Auto `@st.cache_data`** | Automatically decorates data-loading functions |
+| **Auto Error Handling** | Wraps app body in `try/except` with `st.error()` + traceback expander |
+| **Batch ZIP Processing** | Convert an entire folder; download all results as one ZIP |
+| **Session History** | Timestamped timeline of all conversions this session |
+| **Light / Dark Theme** | Toggle from the sidebar |
+| **Two Built-in Samples** | Notebook and script for instant testing |
 
-4. **Auto Mode**: Automatically selects the best strategy based on file size
+---
 
-### What Gets Converted?
+## 🔄 Transformation Map
 
-| Original Code | Streamlit Equivalent |
-|--------------|---------------------|
+| Original Python | Streamlit Equivalent |
+|---|---|
 | `print(x)` | `st.write(x)` |
 | `display(df)` | `st.dataframe(df)` |
-| `df.head()` / `df.tail()` | `st.dataframe(df.head())` |
+| `df.head()` | `st.dataframe(df.head())` |
+| `df.describe()` | `st.dataframe(df.describe())` |
 | `plt.show()` | `st.pyplot(plt.gcf())` |
-| `fig.show()` (Plotly) | `st.plotly_chart(fig)` |
-| Markdown cells | Commented markdown |
-| All comments | Preserved |
+| `fig.show()` | `st.plotly_chart(fig)` |
+| `show(bokeh_fig)` | `st.bokeh_chart(fig)` |
+| Notebook markdown cells | `st.markdown(...)` |
+| `%magic` / `!shell` commands | *(removed)* |
+| `load_*()` / `fetch_*()` functions | `@st.cache_data` applied |
+
+---
 
-## 🚀 Installation
+## 🚀 Quick Start
 
-1. Clone or download this repository
-2. Install dependencies:
+### 1. Clone and install
 
 ```bash
-pip install -r Requirements.txt
+git clone https://github.com/your-username/pystreamlit-converter.git
+cd pystreamlit-converter
+pip install -r requirements.txt
 ```
 
-## 📖 Usage
-
-### Running the Application
+### 2. Run
 
 ```bash
 streamlit run app.py
 ```
 
-The application will open in your default web browser.
-
-### Basic Workflow
-
-1. **Upload Files**: Use the sidebar to upload Python files or Jupyter notebooks
-   - Individual files: Upload one or more files directly
-   - ZIP archive: Upload a ZIP containing multiple files
-
-2. **Configure Settings** (Optional):
-   - Choose conversion strategy (Hybrid recommended)
-   - Set large file threshold
-   - Enable/disable main guard
-   - Toggle comment preservation
-
-3. **Review & Download**: 
-   - View original and converted code side-by-side
-   - Check conversion report for details
-   - Download the converted Streamlit app
-
-### Advanced Settings
-
-- **Conversion Strategy**: Choose how the code is analyzed and converted
-- **Large File Threshold**: Files above this size (in KB) use optimized processing
-- **Main Guard**: Adds `if __name__ == '__main__':` wrapper for safer execution
-- **Preserve Comments**: Keep all comments and docstrings in the output
-
-## 🎯 Use Cases
-
-- **Data Science Projects**: Convert Jupyter notebooks with visualizations to interactive Streamlit dashboards
-- **Script Migration**: Transform existing Python scripts into web applications
-- **Batch Conversion**: Process entire project folders at once
-- **Prototyping**: Quickly create Streamlit apps from existing code
-
-## 🔧 Technical Details
+### 3. Convert your first file
 
-### Architecture
+1. Upload a `.py` or `.ipynb` file via the sidebar
+2. Adjust settings (or keep the defaults)
+3. Preview the output side-by-side
+4. Download the generated `*_streamlit.py`
 
-- **AST-Based Transformation**: Uses Python's `ast` module for structural analysis
-- **Regex Fallback**: Pattern matching for edge cases and large files
-- **Hybrid Approach**: Combines both methods for optimal results
-- **Error Recovery**: Graceful fallbacks when parsing fails
-
-### Performance
-
-- Handles files up to 5MB+ efficiently
-- Chunked processing for large files
-- Caching for repeated conversions
-- Memory-efficient algorithms
-
-### Limitations
+---
 
-- Does not execute code (safe conversion only)
-- Complex interactive widgets (e.g., `ipywidgets`) require manual conversion
-- Some edge cases in very complex code may need manual adjustment
-- Manual review recommended before production deployment
+## 🧠 Conversion Strategies
 
-## 📝 Example
+| Strategy | Best For |
+|---|---|
+| **Hybrid** *(default)* | Any file — AST + regex fallback |
+| **AST Precise** | Clean Python 3.9+ with valid syntax |
+| **Regex Fast** | Large files or syntax-heavy / magic-heavy code |
 
-### Input (Jupyter Notebook Cell):
-```python
-import pandas as pd
-import matplotlib.pyplot as plt
+---
 
-df = pd.read_csv('data.csv')
-print(f"Dataset has {len(df)} rows")
-display(df.head())
+## 📁 Project Structure
 
-plt.figure(figsize=(10, 6))
-plt.plot(df['x'], df['y'])
-plt.show()
+```
+pystreamlit-converter/
+├── app.py              # Single-file Streamlit application
+├── requirements.txt    # Python dependencies
+└── README.md           # Documentation
 ```
 
-### Output (Streamlit App):
-```python
-import streamlit as st
-import pandas as pd
-import matplotlib.pyplot as plt
-
-st.set_page_config(
-    page_title='Converted App',
-    layout='wide'
-)
+---
 
-st.title(' Converted Streamlit App')
+## ⚙️ Configuration Options
 
-df = pd.read_csv('data.csv')
-st.write(f"Dataset has {len(df)} rows")
-st.dataframe(df.head())
+All options are accessible from the sidebar:
 
-plt.figure(figsize=(10, 6))
-plt.plot(df['x'], df['y'])
-st.pyplot(plt.gcf())
-```
+| Option | Description | Default |
+|---|---|---|
+| Strategy | Conversion engine | Hybrid |
+| Chart Library | Preferred target chart lib | Auto-Detect |
+| App Layout | `wide` or `centered` | `wide` |
+| @st.cache_data | Auto-cache data-loading fns | On |
+| Error Handling | try/except wrapper | On |
+| Auto Sidebar Widgets | Expose literals as controls | On |
+| Download Button Stub | CSV export template | On |
+| Session State Init | Add session_state init block | Off |
+| if __name__ guard | Wrap in main guard | Off |
+| Preserve Comments | Keep docstrings / comments | On |
+| Large File Threshold | Strategy switch threshold | 200 KB |
 
-## 🛠️ Development
+---
 
-### Project Structure
-```
-python_to_full_streamlit/
-├── app.py              # Main Streamlit application
-├── Requirements.txt    # Python dependencies
-└── README.md          # This file
-```
+## 🔍 Analyze Tab
 
-### Key Components
+Gives a full breakdown before you convert:
 
-1. **HybridConverter**: Main conversion engine with multiple strategies
-2. **CommentPreservingTransformer**: AST transformer that preserves code structure
-3. **extract_code_from_notebook**: Enhanced notebook processing with markdown support
-4. **File Processing**: Cached, efficient file handling with error recovery
+- **Complexity** — total/code/comment/blank lines, cyclomatic complexity
+- **Library Detection** — chart, ML, and data libraries
+- **Function Inventory** — name, args, line count, async flag
+- **Widget Suggestions** — literals that could become interactive controls
 
-## 🤝 Contributing
+---
 
-This is a production-ready converter. Improvements welcome for:
-- Additional conversion patterns
-- Performance optimizations
-- Edge case handling
-- UI/UX enhancements
+## 📦 Batch ZIP Processing
 
-## 📄 License
+Upload a ZIP containing `.py` / `.ipynb` files. The app converts each one and packages all outputs into a downloadable ZIP.
 
-This project is provided as-is for converting Python code to Streamlit applications.
+---
 
 ## 💡 Tips
 
-- Use **Hybrid mode** for best results on most files
-- Enable **comment preservation** to maintain documentation
-- For very large files (>1MB), consider using **Regex mode**
-- Always review converted code before deployment
-- Test the generated Streamlit app with sample data
-
-## 🐛 Troubleshooting
+1. Run **Analyze** first to understand what will change
+2. Enable **Auto Sidebar Widgets** to make parameters interactive
+3. Use the **Diff Viewer** to review changes before deploying
+4. **Hybrid** mode handles 99% of files reliably
 
-**Issue**: Conversion fails on a file
-- **Solution**: Try a different conversion mode (AST vs Regex)
-- Check if the file has syntax errors
-- Verify the file is valid Python/Jupyter format
+---
 
-**Issue**: Comments are missing
-- **Solution**: Enable "Preserve Comments" in advanced settings
-- Use AST or Hybrid mode instead of Regex
+## 🗺️ images  of app
 
-**Issue**: Large file processing is slow
-- **Solution**: Increase the large file threshold
-- Use Regex mode for very large files
-- Process files individually instead of in ZIP
+![app image 1](img_1.png)
 
----
+#### 🗺️ image 2
+![app image 2](img_2.png)
 
-**Made with ❤️ for the Streamlit community**
+#### 🗺️ image 3
+![app image 3](img_3.png)