Changes to set up the host python app with uv

docs/PROJECT_STRUCTURE.md

@@ -33,7 +33,6 @@ MiniProfiler/
 │   │   └── sample_data_generator.py  # Generate mock profiling data
 │   │
 │   ├── requirements.txt          # Python dependencies
-│   ├── setup.py                  # Package setup
 │   └── run.py                    # Quick start script
 │
 ├── embedded/                     # Embedded module (Phase 2 - TODO)
@@ -306,11 +305,6 @@ User                Web UI              Web Server          Analyzer
 ### `requirements.txt`
 Python package dependencies with minimum versions
 
-### `setup.py`
-Package metadata and installation configuration
-- Entry point: `miniprofiler` CLI command
-- Package data includes web assets
-
 ### `.gitignore`
 Excludes:
 - Python bytecode and caches

docs/SETUP.md

@@ -0,0 +1,445 @@
+# MiniProfiler Setup Guide
+
+This guide covers setting up the MiniProfiler host application using `uv` for fast package management and virtual environment handling.
+
+## Prerequisites
+
+- Python 3.8 or higher
+- [uv](https://github.com/astral-sh/uv) - Fast Python package installer
+
+## Installing uv
+
+If you don't have `uv` installed:
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Or with pip
+pip install uv
+
+# Or with pipx
+pipx install uv
+```
+
+## Quick Start with uv
+
+### 1. Create and Activate Virtual Environment
+
+```bash
+# From the MiniProfiler root directory
+cd host
+
+# Create a virtual environment with uv
+uv venv
+
+# Activate the virtual environment
+# On Linux/macOS:
+source .venv/bin/activate
+
+# On Windows:
+.venv\Scripts\activate
+```
+
+### 2. Install the Package
+
+```bash
+# Install in editable mode with all dependencies
+uv pip install -e .
+
+# Or install with development dependencies
+uv pip install -e ".[dev]"
+```
+
+### 3. Run the Application
+
+```bash
+# Run directly
+miniprofiler
+
+# Or with Python
+python run.py
+
+# Or with custom options
+miniprofiler --host 0.0.0.0 --port 8080 --verbose
+```
+
+## Using the Makefile (Recommended)
+
+The project includes a Makefile for common tasks:
+
+```bash
+# From the project root directory
+
+# Show available commands
+make help
+
+# Install the package
+make install
+
+# Install with dev dependencies
+make dev
+
+# Run the web server
+make run
+
+# Generate sample data
+make sample
+
+# Run tests (after installing dev dependencies)
+make test
+
+# Format code
+make format
+
+# Lint code
+make lint
+
+# Clean build artifacts
+make clean
+```
+
+## Manual Setup (Without Makefile)
+
+### Step-by-Step
+
+```bash
+# 1. Navigate to host directory
+cd host
+
+# 2. Create virtual environment
+uv venv
+
+# 3. Activate virtual environment
+source .venv/bin/activate  # Linux/macOS
+# or
+.venv\Scripts\activate     # Windows
+
+# 4. Install package
+uv pip install -e .
+
+# 5. Verify installation
+miniprofiler --help
+
+# 6. Run the server
+miniprofiler
+```
+
+## Development Setup
+
+For development with testing and linting tools:
+
+```bash
+cd host
+
+# Create venv and install with dev dependencies
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black miniprofiler tests
+
+# Lint code
+ruff check miniprofiler tests
+```
+
+## Project Structure with uv
+
+```
+MiniProfiler/
+├── host/
+│   ├── .venv/              # Virtual environment (created by uv venv)
+│   ├── miniprofiler/       # Source code
+│   ├── tests/              # Tests
+│   ├── web/                # Web assets
+│   ├── pyproject.toml      # Project configuration (uv compatible)
+│   ├── .python-version     # Python version for uv
+│   └── run.py              # Quick start script
+└── Makefile                # Build automation
+```
+
+## Configuration Files
+
+### `pyproject.toml`
+
+Modern Python project configuration file supporting:
+- Project metadata
+- Dependencies
+- Build system configuration
+- Tool configurations (black, ruff, pytest)
+- Entry points for CLI commands
+
+### `.python-version`
+
+Specifies the Python version for `uv` to use. Currently set to `3.11`.
+
+## Virtual Environment Management
+
+### Create New Environment
+
+```bash
+cd host
+uv venv
+```
+
+### Activate Environment
+
+```bash
+# Linux/macOS
+source .venv/bin/activate
+
+# Windows
+.venv\Scripts\activate
+```
+
+### Deactivate Environment
+
+```bash
+deactivate
+```
+
+### Delete Environment
+
+```bash
+# Linux/macOS
+rm -rf .venv
+
+# Windows
+rmdir /s .venv
+```
+
+## Dependency Management
+
+### Install New Package
+
+```bash
+# With uv (fast)
+uv pip install package-name
+
+# Add to pyproject.toml dependencies manually, then:
+uv pip install -e .
+```
+
+### Update Dependencies
+
+```bash
+# Upgrade all packages
+uv pip install --upgrade -e .
+
+# Upgrade specific package
+uv pip install --upgrade package-name
+```
+
+### List Installed Packages
+
+```bash
+uv pip list
+```
+
+### Generate requirements.txt (if needed)
+
+```bash
+uv pip freeze > requirements.txt
+```
+
+## Testing
+
+### Run All Tests
+
+```bash
+pytest
+```
+
+### Run with Coverage
+
+```bash
+pytest --cov=miniprofiler --cov-report=html
+```
+
+### Run Specific Test
+
+```bash
+pytest tests/test_protocol.py
+```
+
+## Code Quality
+
+### Format Code (Black)
+
+```bash
+# Format all code
+black miniprofiler tests
+
+# Check without modifying
+black --check miniprofiler tests
+```
+
+### Lint Code (Ruff)
+
+```bash
+# Check for issues
+ruff check miniprofiler tests
+
+# Auto-fix issues
+ruff check --fix miniprofiler tests
+```
+
+## Common Tasks
+
+### Generate Sample Data
+
+```bash
+cd host/tests
+python sample_data_generator.py
+```
+
+This creates:
+- `sample_profile_data.bin`
+- `sample_flamegraph.json`
+- `sample_statistics.json`
+- `sample_timeline.json`
+
+### Run with Different Settings
+
+```bash
+# Bind to all interfaces
+miniprofiler --host 0.0.0.0
+
+# Use different port
+miniprofiler --port 8080
+
+# Enable debug mode
+miniprofiler --debug
+
+# Verbose logging
+miniprofiler --verbose
+
+# Combine options
+miniprofiler --host 0.0.0.0 --port 8080 --verbose
+```
+
+### Clean Build Artifacts
+
+```bash
+# Using Makefile
+make clean
+
+# Or manually
+find . -type d -name "__pycache__" -exec rm -rf {} +
+find . -type f -name "*.pyc" -delete
+rm -rf host/.venv host/build host/dist
+```
+
+## Troubleshooting
+
+### uv command not found
+
+```bash
+# Install uv
+pip install uv
+
+# Or use the installer
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Verify installation
+uv --version
+```
+
+### Virtual environment activation issues
+
+**Linux/macOS:**
+```bash
+# Make sure you're in the host directory
+cd host
+
+# Source the activate script
+source .venv/bin/activate
+
+# Verify activation (should show .venv path)
+which python
+```
+
+**Windows:**
+```cmd
+cd host
+.venv\Scripts\activate
+```
+
+### Import errors after installation
+
+```bash
+# Reinstall in editable mode
+cd host
+uv pip install -e .
+
+# Verify package is installed
+uv pip list | grep miniprofiler
+```
+
+### Port already in use
+
+```bash
+# Use a different port
+miniprofiler --port 8080
+
+# Or find and kill the process using port 5000
+# Linux/macOS:
+lsof -ti:5000 | xargs kill
+
+# Windows:
+netstat -ano | findstr :5000
+taskkill /PID <PID> /F
+```
+
+## Why uv?
+
+**Benefits over traditional pip:**
+- **10-100x faster** package installation
+- **Better dependency resolution**
+- **Drop-in replacement** for pip
+- **Virtual environment management** built-in
+- **Maintained by Astral** (creators of ruff)
+
+**Speed comparison:**
+```
+pip install:     ~30 seconds
+uv pip install:  ~3 seconds
+```
+
+## Alternative: Traditional pip + venv
+
+If you prefer not to use `uv`:
+
+```bash
+cd host
+
+# Create virtual environment
+python -m venv .venv
+
+# Activate
+source .venv/bin/activate  # Linux/macOS
+.venv\Scripts\activate     # Windows
+
+# Install
+pip install -e .
+
+# Run
+miniprofiler
+```
+
+## Next Steps
+
+After setup:
+1. Read [GETTING_STARTED.md](GETTING_STARTED.md) for usage guide
+2. Generate sample data: `make sample`
+3. Run the server: `make run`
+4. Open browser to `http://localhost:5000`
+
+For development:
+1. Install dev dependencies: `make dev`
+2. Read [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)
+3. Check out the code in `host/miniprofiler/`