Add Google Colab quick start notebook and package version

README.md

@@ -4,6 +4,7 @@ title: LayerLens - Adaptive Low-Rank Adaptation Selector
 
 # LayerLens
 
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ErenAta16/LayerLens/blob/main/notebooks/colab_quick_start.ipynb)
 [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
 [![Tests](https://img.shields.io/badge/tests-15%2F15-brightgreen)](tests/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

layerlens/__init__.py

@@ -6,6 +6,8 @@
 Python interfaces for core algorithms that will be accelerated with Cython.
 """
 
+__version__ = "0.1.0"
+
 from .config import ProfilingConfig, OptimizationConfig, LatencyProfile
 
 # Import submodules to make them available for type checking
@@ -40,5 +42,6 @@
     "ManifestError",
     "ModelSpecError",
     "ActivationCacheError",
+    "__version__",
 ]
 

notebooks/README.md

@@ -1,30 +1,53 @@
-# LayerLens Colab Notebooks
+# LayerLens Notebooks
 
-This directory contains Jupyter notebooks for running LayerLens on Google Colab.
+This directory contains Jupyter notebooks for interactive demos and tutorials.
 
 ## Quick Start
 
+### Google Colab
+Click the badge below to open the quick start notebook directly in Google Colab:
+
 [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ErenAta16/LayerLens/blob/main/notebooks/colab_quick_start.ipynb)
 
-Click the badge above to open the quick start notebook in Colab.
+### Available Notebooks
+
+#### `colab_quick_start.ipynb`
+**Recommended for first-time users**
+
+A beginner-friendly introduction to LayerLens on Google Colab:
+- ✅ One-click installation
+- ✅ GPU verification
+- ✅ Simple BERT example
+- ✅ Results visualization
+- ⏱️ ~5 minutes to complete
+
+**Topics covered:**
+- Installing LayerLens on Colab
+- Defining model specifications
+- Configuring profiling and optimization
+- Running the pipeline
+- Interpreting results
+
+## Local Usage
+
+To run these notebooks locally:
 
-## Available Notebooks
+```bash
+# Install Jupyter
+pip install jupyter
 
-- **colab_quick_start.ipynb** - Quick start guide with BERT demo
-- **colab_bert_demo.ipynb** - Full BERT-base optimization example
-- **colab_yolo_demo.ipynb** - YOLO model optimization example
+# Install LayerLens with demo dependencies
+pip install -e ".[demo]"
 
-## Requirements
+# Start Jupyter
+jupyter notebook notebooks/
+```
 
-- Google Colab account
-- GPU runtime (recommended, but CPU works too)
-- ~5 minutes setup time
+## Troubleshooting
 
-## Usage
+If you encounter issues on Colab, see [COLAB_TROUBLESHOOT.md](../COLAB_TROUBLESHOOT.md) for solutions.
 
-1. Open a notebook in Colab using the badge links
-2. Run cells sequentially
-3. Check output in `./output/` directory
+## Contributing
 
-For troubleshooting, see `docs/TROUBLESHOOTING.md`.
+Want to add more notebooks? See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
 

notebooks/colab_quick_start.ipynb

@@ -0,0 +1,210 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# LayerLens Quick Start on Google Colab\n",
+    "\n",
+    "This notebook demonstrates how to use LayerLens on Google Colab with GPU acceleration.\n",
+    "\n",
+    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ErenAta16/LayerLens/blob/main/notebooks/colab_quick_start.ipynb)\n",
+    "\n",
+    "## What You'll Learn\n",
+    "- Install LayerLens on Colab\n",
+    "- Verify GPU availability\n",
+    "- Run a simple BERT profiling example\n",
+    "- Generate optimization manifest"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Install LayerLens\n",
+    "!git clone https://github.com/ErenAta16/LayerLens.git\n",
+    "%cd LayerLens\n",
+    "!pip install -e \".[demo]\" -q\n",
+    "\n",
+    "print(\"✅ LayerLens installed successfully!\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Verify installation and GPU\n",
+    "import torch\n",
+    "import layerlens\n",
+    "\n",
+    "print(f\"LayerLens version: {layerlens.__version__ if hasattr(layerlens, '__version__') else '0.1.0'}\")\n",
+    "print(f\"CUDA available: {torch.cuda.is_available()}\")\n",
+    "if torch.cuda.is_available():\n",
+    "    print(f\"GPU: {torch.cuda.get_device_name(0)}\")\n",
+    "    print(f\"GPU Memory: {torch.cuda.get_device_properties(0).total_memory / 1e9:.2f} GB\")\n",
+    "else:\n",
+    "    print(\"⚠️ No GPU detected. Using CPU (slower performance).\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "from layerlens.pipeline import run_pipeline\n",
+    "from layerlens.config import ProfilingConfig, OptimizationConfig, LatencyProfile\n",
+    "from layerlens.models import ModelSpec, LayerSpec\n",
+    "\n",
+    "# Define a simple model (BERT-base structure)\n",
+    "model_spec = ModelSpec(\n",
+    "    model_name=\"bert-base-example\",\n",
+    "    total_params=110_000_000,\n",
+    "    layers=[\n",
+    "        LayerSpec(\n",
+    "            name=f\"encoder.layer.{i}\",\n",
+    "            hidden_size=768,\n",
+    "            layer_type=\"transformer\",\n",
+    "            supports_attention=True\n",
+    "        )\n",
+    "        for i in range(12)\n",
+    "    ]\n",
+    ")\n",
+    "\n",
+    "# Configure profiling\n",
+    "profiling_cfg = ProfilingConfig(\n",
+    "    metric_weights={\n",
+    "        \"gradient_energy\": 0.4,\n",
+    "        \"fisher\": 0.4,\n",
+    "        \"proxy_eval\": 0.2\n",
+    "    }\n",
+    ")\n",
+    "\n",
+    "# Configure optimization with GPU latency profile\n",
+    "latency_profile = LatencyProfile(\n",
+    "    device_type=\"gpu\",\n",
+    "    model_family=\"llm\",\n",
+    "    batch_size=4,\n",
+    "    sequence_length=512\n",
+    ")\n",
+    "\n",
+    "optimization_cfg = OptimizationConfig(\n",
+    "    max_trainable_params=50_000,\n",
+    "    max_flops=1e9,\n",
+    "    max_vram_gb=15.0,  # Colab GPU limit\n",
+    "    latency_target_ms=100.0,\n",
+    "    latency_profile=latency_profile\n",
+    ")\n",
+    "\n",
+    "# Create synthetic activation cache (in real use, compute from model)\n",
+    "activation_cache = {\n",
+    "    f\"encoder.layer.{i}\": {\n",
+    "        \"grad_norm\": 0.5 + i * 0.1,\n",
+    "        \"fisher_trace\": 0.3 + i * 0.05,\n",
+    "        \"proxy_gain\": 0.1 + i * 0.02\n",
+    "    }\n",
+    "    for i in range(12)\n",
+    "}\n",
+    "\n",
+    "# Run pipeline\n",
+    "output_dir = Path(\"./output\")\n",
+    "print(\"Running LayerLens pipeline...\")\n",
+    "manifest_path = run_pipeline(\n",
+    "    model_spec=model_spec,\n",
+    "    profiling_cfg=profiling_cfg,\n",
+    "    optimization_cfg=optimization_cfg,\n",
+    "    activation_cache=activation_cache,\n",
+    "    output_dir=output_dir\n",
+    ")\n",
+    "\n",
+    "print(f\"\\n✅ Optimization complete!\")\n",
+    "print(f\"📄 Manifest saved to: {manifest_path}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json\n",
+    "\n",
+    "# Load and display the manifest\n",
+    "with open(manifest_path, 'r') as f:\n",
+    "    manifest = json.load(f)\n",
+    "\n",
+    "print(\"=\" * 60)\n",
+    "print(\"LAYERLENS OPTIMIZATION RESULTS\")\n",
+    "print(\"=\" * 60)\n",
+    "\n",
+    "allocations = manifest['allocations']\n",
+    "print(f\"\\nTotal layers: {len(allocations)}\")\n",
+    "\n",
+    "# Summary statistics\n",
+    "lora_layers = sum(1 for a in allocations if a['method'] == 'lora')\n",
+    "adapter_layers = sum(1 for a in allocations if a['method'] == 'adapter')\n",
+    "prefix_layers = sum(1 for a in allocations if a['method'] == 'prefix')\n",
+    "none_layers = sum(1 for a in allocations if a['method'] == 'none')\n",
+    "\n",
+    "print(f\"\\nMethod Distribution:\")\n",
+    "print(f\"  LoRA: {lora_layers} layers\")\n",
+    "print(f\"  Adapter: {adapter_layers} layers\")\n",
+    "print(f\"  Prefix: {prefix_layers} layers\")\n",
+    "print(f\"  None: {none_layers} layers\")\n",
+    "\n",
+    "# Show top 5 layers by utility\n",
+    "print(f\"\\nTop 5 Layers by Utility:\")\n",
+    "sorted_allocs = sorted(allocations, key=lambda x: x['utility'], reverse=True)\n",
+    "for i, alloc in enumerate(sorted_allocs[:5], 1):\n",
+    "    print(f\"  {i}. {alloc['layer']}: {alloc['method']} (rank={alloc['rank']}, utility={alloc['utility']:.4f})\")\n",
+    "\n",
+    "print(\"\\n\" + \"=\" * 60)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 🎉 Success!\n",
+    "\n",
+    "You've successfully run LayerLens on Google Colab!\n",
+    "\n",
+    "### Next Steps\n",
+    "1. **Try with a real model**: See `demos/demo_bert.py` for loading actual BERT models\n",
+    "2. **Experiment with configurations**: Adjust `max_trainable_params`, `latency_target_ms`, etc.\n",
+    "3. **Explore YOLO demo**: Check `demos/demo_yolo.py` for vision model optimization\n",
+    "\n",
+    "### Resources\n",
+    "- 📖 [Documentation](https://github.com/ErenAta16/LayerLens/tree/main/docs)\n",
+    "- 🐛 [Troubleshooting](https://github.com/ErenAta16/LayerLens/blob/main/COLAB_TROUBLESHOOT.md)\n",
+    "- 💬 [Issues](https://github.com/ErenAta16/LayerLens/issues)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

requirements.txt

@@ -1,59 +1,39 @@
-# LayerLens Dependencies
-# ========================
-# For Google Colab Quick Setup:
-#   pip install -r requirements.txt
+# LayerLens Requirements
+# ======================
+# For Google Colab, install with: pip install -r requirements.txt
 
-# CORE DEPENDENCIES (Always Required)
-# ------------------------------------
+# CORE DEPENDENCIES (Required)
+# -----------------------------
 numpy>=1.24
 scipy>=1.10.0
 
-# OPTIONAL DEPENDENCIES (For Demos & Experiments)
-# -----------------------------------------------
-# Uncomment the sections you need, or install with:
-#   pip install -e ".[demo,yolo,pipeline,dev]"
+# OPTIONAL: For demos and examples
+# ---------------------------------
+# Uncomment the dependencies you need, or install with:
+# pip install -e ".[demo,yolo,pipeline]"
 
-# For BERT/Transformer demos:
+# For BERT/LLM demos:
 # transformers>=4.20.0
 # torch>=2.0.0
 
-# For YOLO demos:
+# For YOLO integration:
 # ultralytics>=8.0.0
 # torchvision>=0.15.0
-
-# For LLM-YOLO pipeline:
 # pillow>=9.0.0
 
-# BUILD DEPENDENCIES (For Development)
-# -------------------------------------
-# Only needed if you want to compile Cython modules
-# (Colab users can use Python fallback, no compilation needed)
+# DEVELOPMENT DEPENDENCIES
+# ------------------------
+# For building from source (Cython compilation)
+# Note: Colab users don't need these - Python fallback is automatic
 # setuptools>=65
 # wheel
 # Cython>=3.0
 
-# DEVELOPMENT DEPENDENCIES
-# ------------------------
+# For testing:
 # pytest>=7.0.0
 # pytest-cov>=4.0.0
-# pytest-mock>=3.10.0
 
-# QUICK INSTALL OPTIONS:
+# RECOMMENDED FOR COLAB
 # ----------------------
-# Minimal (core only):
-#   pip install -e .
-#
-# With demos:
-#   pip install -e ".[demo]"
-#
-# With YOLO support:
-#   pip install -e ".[yolo]"
-#
-# With full pipeline:
-#   pip install -e ".[pipeline]"
-#
-# For development:
-#   pip install -e ".[dev]"
-#
-# Everything:
-#   pip install -e ".[demo,yolo,pipeline,dev]"
+# Install with: pip install -e ".[demo]"
+# This includes transformers and torch for running examples