fix(web): verbose logging, experiment loading fixes, and --doctor command

.gitignore

@@ -148,3 +148,8 @@ CLAUDE.md
 # Temporary files
 tmp_*.html
 tmp_*.json
+
+# Personal/temporary artifacts
+*.pdf
+*.zip
+pdf_parts/

docs/architecture.md

@@ -26,9 +26,24 @@ spkmc/
 ├── utils/              # Utilities
 │   ├── __init__.py
 │   └── numba_utils.py  # Numba-optimized functions
-└── visualization/      # Visualization module
+├── visualization/      # Visualization module
+│   ├── __init__.py
+│   └── plots.py        # Visualization functions
+└── web/                # Web interface module (Streamlit)
     ├── __init__.py
-    └── plots.py        # Visualization functions
+    ├── app.py           # Entry point, routing, sidebar navigation
+    ├── config.py        # JSON preferences and Streamlit secrets
+    ├── state.py         # Typed session state accessors with URL persistence
+    ├── styles.py        # CSS design system (teal palette, Plus Jakarta Sans)
+    ├── components.py    # Reusable form components
+    ├── plotting.py      # Plotly interactive figure builders
+    ├── runner.py        # Subprocess simulation runner
+    ├── analysis_runner.py  # AI analysis subprocess runner
+    ├── logging.py       # Structured debug logging
+    └── pages/           # Page modules
+        ├── dashboard.py         # Experiments list with live polling
+        ├── experiment_detail.py # Scenario cards, charts, comparison
+        └── settings.py          # Preferences and AI configuration
 ```
 
 ## Main Components
@@ -117,15 +132,80 @@ This file contains CLI parameter validators:
 - `validate_network_type`: Validate the network type.
 - `validate_distribution_type`: Validate the distribution type.
 
+### `web` Module
+
+The `web` module provides an interactive browser-based interface built with Streamlit, serving as an alternative to the CLI for running simulations and managing experiments.
+
+#### `app.py`
+
+Entry point for the web interface. Handles page routing and renders the sidebar navigation with experiment discovery from the `experiments/` folder.
+
+#### `config.py`
+
+Manages user preferences persisted as a JSON file and integrates with Streamlit secrets for sensitive configuration such as AI API keys.
+
+#### `state.py`
+
+Provides typed accessors for Streamlit session state. Supports URL-based persistence so that navigation state (selected experiment, active page) survives page reloads.
+
+#### `styles.py`
+
+Defines the CSS design system applied globally across the interface. Uses a teal color palette with Plus Jakarta Sans typography, dark sidebar, and clean white card layouts.
+
+#### `components.py`
+
+Reusable form components shared across pages, including network parameter forms, distribution parameter forms, and simulation configuration inputs.
+
+#### `plotting.py`
+
+Builds interactive Plotly figures for SIR curves, scenario comparisons, and summary statistics. Produces figures consistent with the design system colors.
+
+#### `runner.py`
+
+Executes SPKMC simulations as subprocesses, streaming progress updates back to the interface. Decouples simulation execution from the Streamlit event loop.
+
+#### `analysis_runner.py`
+
+Runs AI-powered analysis of simulation results as a subprocess. Integrates with configured AI providers to generate interpretive summaries of experiment outcomes.
+
+#### `logging.py`
+
+Structured debug logging for the web interface. Activated via the `--verbose` flag on the `spkmc web` command and useful for diagnosing runtime issues.
+
+#### `pages/dashboard.py`
+
+The main landing page. Displays experiment cards with summary statistics, supports creating new experiments via a modal dialog, and uses live polling to reflect filesystem changes.
+
+#### `pages/experiment_detail.py`
+
+Detail view for a single experiment. Shows scenario cards with parameter summaries, interactive SIR charts, cross-scenario comparison plots, and data export options.
+
+#### `pages/settings.py`
+
+Configuration page for user preferences (default simulation parameters, display options) and AI provider settings (API keys, model selection).
+
 ## Execution Flow
 
+### CLI and Programmatic Usage
+
 1. The user creates a distribution instance (`GammaDistribution` or `ExponentialDistribution`).
 2. The user creates an `SPKMC` instance with the distribution.
 3. The user creates a network using `NetworkFactory`.
 4. The user runs the simulation using methods on `SPKMC`.
 5. The user visualizes results using `Visualizer`.
 6. The user saves results using `ResultManager`.
 
+### Web Interface
+
+As an alternative to the CLI, users can launch the web interface with `spkmc web`. The flow in the browser is:
+
+1. The dashboard discovers experiments from the `experiments/` folder and displays them as cards.
+2. The user creates a new experiment or selects an existing one.
+3. The user configures scenarios (network type, distribution, parameters) through form components.
+4. The `runner` module executes simulations as subprocesses, reporting progress in real time.
+5. Results appear as interactive Plotly charts on the experiment detail page.
+6. The user can compare scenarios, export data, or run AI analysis on outcomes.
+
 ## Optimizations
 
 SPKMC uses Numba to optimize critical functions. Optimized functions live in `numba_utils.py` and are decorated with `@njit` or `@njit(parallel=True)` for parallelization.

docs/usage.md

@@ -78,6 +78,8 @@ The SPKMC CLI provides the following main commands:
 - `plot`: Visualize results from previous simulations
 - `info`: Show information about saved simulations
 - `compare`: Compare results from multiple simulations
+- `batch`: Run multiple simulation scenarios from a JSON file
+- `web`: Launch the interactive web interface
 
 ### `run` Command
 
@@ -249,6 +251,79 @@ python spkmc_cli.py compare data/spkmc/gamma/ER/results_1000_50_2.0.json data/sp
 python spkmc_cli.py compare data/spkmc/gamma/ER/results_1000_50_2.0.json data/spkmc/exponential/ER/results_1000_50_.json -o plots/comparison.png
 ```
 
+## Web Interface
+
+SPKMC includes an interactive web interface built with Streamlit that provides a browser-based alternative to the CLI. It supports experiment management, real-time simulation execution, interactive charting, and optional AI-powered analysis.
+
+### Launching the Web Interface
+
+```bash
+# Start with default settings (opens browser automatically)
+spkmc web
+
+# Specify a custom port
+spkmc web --port 8502
+
+# Bind to a specific host (useful for remote servers)
+spkmc web --host 0.0.0.0
+
+# Start without opening a browser window
+spkmc web --no-browser
+
+# Enable verbose debug logging
+spkmc web --verbose
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--port` | int | `8501` | Port number for the Streamlit server |
+| `--host` | string | `localhost` | Host address to bind the server to |
+| `--no-browser` | flag | `False` | Do not open a browser window on startup |
+| `--verbose` | flag | `False` | Enable structured debug logging to the terminal |
+
+### Dashboard
+
+The dashboard is the landing page of the web interface. It provides an overview of all experiments and quick access to create new ones.
+
+- **Experiment cards**: Each experiment discovered in the `experiments/` folder is shown as a card with its name, number of scenarios, and summary statistics (node counts, network types used).
+- **Summary statistics**: Aggregate counts of total experiments, scenarios, and completed runs are displayed at the top of the page.
+- **Create experiment**: A modal dialog allows creating a new experiment by specifying a name and adding one or more scenario configurations. The experiment is saved as a `data.json` file in the `experiments/` directory.
+- **Live polling**: The dashboard periodically checks the filesystem for new or updated experiments, so results from CLI batch runs appear automatically.
+
+### Experiment Detail
+
+Selecting an experiment from the dashboard opens the detail view, which provides full control over that experiment's scenarios and results.
+
+- **Scenario management**: View all scenarios in the experiment as individual cards showing their network type, distribution, node count, and other parameters. New scenarios can be added directly from this page.
+- **SIR charts**: Each completed scenario displays an interactive Plotly chart with Susceptible, Infected, and Recovered curves. Charts support zoom, pan, and hover inspection.
+- **Comparison**: A dedicated comparison view overlays SIR curves from multiple scenarios on the same chart, making it straightforward to evaluate the effect of parameter changes.
+- **Export**: Simulation results can be exported from the detail page in standard formats for further analysis.
+
+### Settings
+
+The settings page provides configuration options that persist across sessions.
+
+- **Preferences**: Default values for simulation parameters (node count, samples, time steps) and display options. These defaults are applied when creating new scenarios in the web interface.
+- **AI configuration**: API key and model selection for optional AI-powered analysis of simulation results. Sensitive values are stored via Streamlit secrets.
+- **Defaults**: Reset all preferences to their factory values.
+
+### Experiment Auto-Discovery
+
+The web interface automatically discovers experiments from the `experiments/` folder in the project root. Any directory containing a `data.json` configuration file is recognized as an experiment. This means experiments created via the CLI `batch` command or by manually placing files in the directory are immediately visible in the dashboard without any import step.
+
+### Verbose Mode
+
+When launched with `--verbose`, the web interface outputs structured debug logs to the terminal. This is useful for diagnosing issues with simulation subprocess execution, AI analysis calls, or Streamlit state management. Log entries include timestamps, module names, and severity levels.
+
+```bash
+# Example: debugging a simulation that fails to start
+spkmc web --verbose --no-browser --port 8502
+```
+
+The verbose output appears in the terminal where the `spkmc web` command was launched, not in the browser.
+
 ## Programmatic Usage
 
 In addition to the CLI, SPKMC can be used programmatically in your own Python scripts.