README.md

---
title: "LLM Scope"
emoji: 🔭
short_description: "Explore the inners of your favorite LLMs"
colorFrom: gray
colorTo: blue
sdk: docker
license: mit
tags:
  - deepseek
  - gemma
  - gpt-oss
  - kimi
  - llama
  - llm
  - mistral
  - nemotron
  - qwen
  - transformer
  - trinity
  - visualization
---

# LLM Scope — Explore the inners of your favorite LLMs

Explore the inners of your favorite LLMs. Visualize transformer architectures and parameter counts without downloading weights.

**Space:** https://huggingface.co/spaces/omarkamali/llm-scope

**Contact:** omarkamali.com · omneitylabs.com · hf:omarkamali · x.com/omarkamali · linkedin.com/in/omar-kamali

---

## About / Model Inspector

A beautiful, interactive treemap visualizer for transformer model architectures. Enter a HuggingFace model ID or upload a config.json to see a proportional visualization of the model's structure - all without downloading weights.

## Features

- **No Weights Required**: Calculates parameter counts mathematically from config dimensions only
- **Interactive Treemap**: D3.js zoomable treemap with area proportional to parameter count
- **Multiple Architectures**: Supports LLaMA, Mistral, Mixtral, GPT-2, BERT, T5, Falcon, Gemma, Qwen, and more
- **Beautiful Dark Theme**: Modern, minimal UI designed for ML/AI workflows
- **Drag & Drop Upload**: Upload your own config.json files for analysis

## Local Development

### Prerequisites

- Python 3.9+
- Node.js (for serving frontend during development)

### Setup

1. Clone the repository:
```bash
git clone https://huggingface.co/omarkamali/llm-scope.git
cd model-inspector
```

2. Install Python dependencies:
```bash
cd backend
pip install -r requirements.txt
```

3. Run the server:
```bash
uvicorn main:app --reload --port 7860
```

4. Open http://localhost:7860 in your browser

### Running with Docker

```bash
docker build -t model-inspector .
docker run -p 7860:7860 model-inspector
```

## API Endpoints

### POST /api/inspect

Inspect a model by HuggingFace model ID or config object.

**Request Body:**
```json
{
  "model_id": "qwen/qwen3-4b-instruct-2507"
}
```

or

```json
{
  "config": { /* config.json contents */ }
}
```

**Response:**
```json
{
  "tree": {
    "name": "Qwen Model",
    "type": "model",
    "params": 1234,
    "children": [...]
  },
  "metadata": {
    "model_id": "qwen/qwen3-4b-instruct-2507",
    "model_type": "llama",
    "total_params": 1234,
    "formatted_params": "...",
    "config": {...}
  }
}
```

### POST /api/upload

Upload a config.json file for inspection.

**Request:** `multipart/form-data` with `file` field

### GET /api/health

Health check endpoint.

## Parameter Calculation

Parameters are calculated mathematically from config dimensions:

| Component | Formula |
|-----------|---------|
| Embedding | vocab_size × hidden_size |
| Attention Q/K/V | hidden_size × (num_heads × head_dim) |
| Attention Output | (num_heads × head_dim) × hidden_size |
| MLP Up | hidden_size × intermediate_size |
| MLP Gate (SwiGLU) | hidden_size × intermediate_size |
| MLP Down | intermediate_size × hidden_size |
| LayerNorm | 2 × hidden_size (weight + bias) |
| RMSNorm | hidden_size (weight only) |
| LM Head | hidden_size × vocab_size (if not tied) |

## Tech Stack

- **Backend**: FastAPI (Python)
- **Frontend**: Vanilla JS + D3.js
- **Deployment**: Docker-based HuggingFace Space

## License

MIT