Metadata-Version: 2.4
Name: haoline
Version: 0.2.0
Summary: HaoLine (好线) - Universal Model Inspector. See what's really inside your models.
Project-URL: Homepage, https://github.com/mdayku/HaoLine
Project-URL: Documentation, https://github.com/mdayku/HaoLine#readme
Project-URL: Repository, https://github.com/mdayku/HaoLine
Project-URL: Issues, https://github.com/mdayku/HaoLine/issues
Author-email: Marcus Day <marcusday3586@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: deep-learning,flops,machine-learning,memory,model-analysis,model-inspector,neural-network,onnx,parameters,profiling,pytorch,tensorflow,tensorrt
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: onnx>=1.14.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: anthropic>=0.20.0; extra == 'full'
Requires-Dist: google-generativeai>=0.3.0; extra == 'full'
Requires-Dist: matplotlib>=3.5.0; extra == 'full'
Requires-Dist: nvidia-ml-py>=12.0.0; extra == 'full'
Requires-Dist: onnxruntime>=1.16.0; extra == 'full'
Requires-Dist: openai>=1.0.0; extra == 'full'
Requires-Dist: playwright>=1.40.0; extra == 'full'
Provides-Extra: gpu
Requires-Dist: nvidia-ml-py>=12.0.0; extra == 'gpu'
Provides-Extra: llm
Requires-Dist: anthropic>=0.20.0; extra == 'llm'
Requires-Dist: google-generativeai>=0.3.0; extra == 'llm'
Requires-Dist: openai>=1.0.0; extra == 'llm'
Provides-Extra: pdf
Requires-Dist: playwright>=1.40.0; extra == 'pdf'
Provides-Extra: runtime
Requires-Dist: onnxruntime>=1.16.0; extra == 'runtime'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5.0; extra == 'viz'
Description-Content-Type: text/markdown

# HaoLine (好线)

**Universal Model Inspector — See what's really inside your models.**

[![PyPI version](https://badge.fury.io/py/haoline.svg)](https://badge.fury.io/py/haoline)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A graph-level analysis tool that inspects neural network architectures (ONNX, PyTorch, TensorFlow, TensorRT), computes static complexity metrics, surfaces structural risk signals, and auto-generates human-readable reports.

---

## Installation

```bash
pip install haoline

# With LLM summaries (requires API key)
pip install haoline[llm]

# With all features (LLM, PDF export, GPU metrics)
pip install haoline[full]
```

---

## Quick Start

### Analyze a Model

```bash
# Basic analysis
haoline analyze model.onnx

# With hardware profile
haoline analyze model.onnx --hardware rtx4090

# Generate HTML report with charts
haoline analyze model.onnx --out-html report.html --with-plots

# Full analysis with AI summary
haoline analyze model.onnx --hardware auto --with-plots --llm-summary --out-html full_report.html
```

### Compare Model Variants

```bash
# Compare FP32, FP16, INT8 quantizations
haoline compare \
  --models resnet_fp32.onnx resnet_fp16.onnx resnet_int8.onnx \
  --baseline-precision fp32 \
  --out-html comparison.html --with-charts
```

---

## Features

- **Parameter counts** - Per node, per block, and globally
- **FLOP estimates** - Identify compute hotspots
- **Memory analysis** - Peak activation memory and VRAM requirements
- **Risk signals** - Detect problematic architecture patterns
- **Hardware estimates** - GPU utilization predictions for 30+ NVIDIA profiles
- **Runtime profiling** - Actual inference benchmarks with ONNX Runtime
- **Visualizations** - Operator histograms, parameter/FLOPs distribution charts
- **LLM Summaries** - AI-generated executive summaries
- **Interactive graphs** - D3.js neural network visualizations
- **Shareable Reports** - HTML, Markdown, PDF, and JSON output formats

---

## Supported Formats

| Format | Read | Write |
|--------|------|-------|
| ONNX | ✅ | - |
| PyTorch (.pt, .pth) | ✅ | - |
| TensorFlow SavedModel | ✅ | - |
| TensorRT Engine | 🔜 | - |
| SafeTensors | 🔜 | - |

---

## Python API

```python
from haoline import ModelInspector

inspector = ModelInspector()
report = inspector.inspect("model.onnx")

# Get metrics
print(f"Parameters: {report.params.total:,}")
print(f"FLOPs: {report.flops.total:,}")
print(f"Peak Memory: {report.memory.peak_activation_bytes / 1e9:.2f} GB")

# Export
report.to_json("report.json")
report.to_markdown("model_card.md")
report.to_html("report.html")
```

---

## LLM Setup (Optional)

HaoLine can generate AI-powered summaries of your model architectures. Install with LLM support and set the API key for your preferred provider:

```bash
pip install haoline[llm]
```

| Provider | Environment Variable | Get API Key |
|----------|---------------------|-------------|
| OpenAI | `OPENAI_API_KEY` | [platform.openai.com](https://platform.openai.com/api-keys) |
| Anthropic | `ANTHROPIC_API_KEY` | [console.anthropic.com](https://console.anthropic.com/) |
| Google Gemini | `GOOGLE_API_KEY` | [aistudio.google.com](https://aistudio.google.com/app/apikey) |
| xAI Grok | `XAI_API_KEY` | [console.x.ai](https://console.x.ai/) |

```bash
# Set your preferred provider's API key
export OPENAI_API_KEY="sk-..."           # OpenAI
export ANTHROPIC_API_KEY="sk-ant-..."    # Anthropic
export GOOGLE_API_KEY="..."              # Google Gemini
export XAI_API_KEY="xai-..."             # xAI Grok

# Windows PowerShell
$env:OPENAI_API_KEY="sk-..."

# Use in analysis (auto-detects available provider)
haoline model.onnx --llm-summary
```

---

## Security Notice

⚠️ **Loading untrusted models is inherently risky.**

Like PyTorch's `torch.load()`, HaoLine uses `pickle` and `numpy.load(allow_pickle=True)` when loading JAX model parameters. These can execute arbitrary code if the model file is malicious.

**Best practices:**
- Only analyze models from trusted sources
- Run in a sandboxed environment (Docker, VM) when analyzing unknown models
- Review model provenance before loading

---

## License

MIT License - See [LICENSE](LICENSE) for details.

---

## Etymology

**HaoLine** (好线) combines:
- 好 (hǎo) = "good" in Chinese
- A personal touch from the author

*"The good path through your neural network."*
