ssmforge 0.2.0__tar.gz → 0.2.2__tar.gz

{ssmforge-0.2.0/src/ssmforge.egg-info → ssmforge-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ssmforge
-Version: 0.2.0
+Version: 0.2.2
 Summary: Standalone HF architecture analyzer (`ssmforge arch`). Inspects any HuggingFace model and reports architectural quirks — attention biases, fused QKV/gate-up, tied embeddings, GQA, MQA, MoE, sliding window, LayerScale, soft-capping, partial RoPE, MLP type, norm type. Outputs structured JSON + human-readable summary.
 Author: SSMForge Contributors
 License-Expression: Apache-2.0
@@ -82,6 +82,28 @@ visible *before* you spend the next hour finding out the hard way.
 It does **not** modify the model. It does **not** run inference. It only
 inspects.
 
+### What's new in 0.2.2
+
+| Fix | What was broken |
+|-----|-----------------|
+| `--output PATH` with bad parent dir | Previously got a generic `bash: Permission denied` (when redirecting) or a Python traceback (when using `--output`). Now pre-flight checks the parent directory, prints a clear hint pointing at writable locations like `./` and `~/`, then exits 1. |
+
+Plus 6 new tests (162 total). Tiny release — main bug fix only.
+
+### What's new in 0.2.1
+
+| Feature | Why it matters |
+|---------|----------------|
+| `doctor --check-install` | Diagnoses "ssmforge: command not found" in one command. Prints `✓` when on PATH, `✗` + a copy-pasteable fix hint when not. Exits non-zero so you can use it in scripts. |
+| One-time PATH warning | First invocation when `ssmforge` is off-PATH prints a hint to stderr pointing at `python -m ssmforge.cli`. Suppressed by `SSMFORGE_NO_PATH_WARN=1`. Skipped for `doctor` so its output stays clean. |
+| `--graph --format {text,json,markdown}` | `--graph` now respects `--format`. Single + compare modes emit ASCII (text), structured JSON (for pipelines), or GitHub-flavored Markdown (for docs/Issues). |
+| `--graph` ASCII cleanup | Box-drawing hierarchy fixed: single-rail `▼` flow + box `╭╮╰╯` panels for ATTENTION and MLP, `├─/└─` decision-tree style inside. |
+| Qwen2 attention_bias fixed | `config.attention_bias=None` + zero bias tensors (Qwen2's vestigial biases) no longer reports `attention_bias=True`. Now requires either config explicit True OR non-zero bias values. |
+| `--compare A A` is now valid | Was previously dedup'd to `[A]` and rejected. Now produces a 2-way "all identical" report. |
+| README install lead | Section 4.2 now recommends a venv more strongly + explains why + gives `python -m ssmforge.cli` as the universal workaround. |
+
+Plus 26 new tests (156 total).
+
 ### What's new in 0.2.0
 
 | Feature | Why it matters |
@@ -252,7 +274,13 @@ If you don't have it:
 - macOS: `brew install python@3.12`
 - Windows: download from https://www.python.org/downloads/
 
-### 4.2 Create a virtual environment (recommended)
+### 4.2 Create a virtual environment (recommended — strongly)
+
+**Use a venv.** It sidesteps the most common install problem on Windows
+(`ssmforge: command not found` after pip install). With a venv, the
+`ssmforge` script lands at `.venv\Scripts\ssmforge.exe` (Windows) or
+`.venv/bin/ssmforge` (Linux/macOS), which is automatically on PATH after
+you activate.
 
 A venv keeps ssmforge and its dependencies isolated from system Python.
 
@@ -273,6 +301,15 @@ python -m venv .venv
 You should see `(.venv)` in your prompt after activating. From here on,
 `pip install` only affects this venv.
 
+**Alternative: use `python -m ssmforge.cli`** as a workaround without a
+venv. Works anywhere, doesn't need any PATH setup, but requires typing
+`python -m ssmforge.cli` instead of just `ssmforge`.
+
+```bash
+python -m ssmforge.cli --version
+python -m ssmforge.cli arch hf-internal-testing/tiny-random-LlamaForCausalLM --dry-run
+```
+
 ### 4.3 Install ssmforge
 
 ```bash
@@ -416,6 +453,52 @@ JSON variant:
 ssmforge doctor --format json
 ```
 
+#### `ssmforge doctor --check-install`
+
+Run install checks (PATH, scripts location) and exit non-zero on issues.
+Useful in scripts or when troubleshooting "command not found":
+
+```bash
+ssmforge doctor --check-install
+```
+
+```
+ssmforge doctor --check-install (0.2.1)
+--------------------------------------------------
+  ✓ ssmforge command on PATH: True
+  python: C:\Users\netge\.venv\Scripts\python.exe
+  platform: win32
+```
+
+If `ssmforge` isn't on PATH, you get a fix-hint block:
+
+```
+ssmforge doctor --check-install (0.2.1)
+--------------------------------------------------
+  ✗ ssmforge command on PATH: False
+  python: C:\Python314\python.exe
+  platform: win32
+
+The 'ssmforge' script was installed to:
+    C:\Users\netge\AppData\Roaming\Python\Python314\Scripts\ssmforge.exe
+but that folder is not on PATH.
+
+  Quick fix (current shell):
+    export PATH="/c/Users/netge/AppData/Roaming/Python/Python314/Scripts:$PATH"
+
+  Permanent fix (PowerShell, restart shell after):
+    [Environment]::SetEnvironmentVariable("PATH", "<scripts>;" + [Environment]::GetEnvironmentVariable("PATH", "User"), "User")
+
+  Or just use: python -m ssmforge.cli
+```
+
+JSON variant:
+
+```bash
+ssmforge doctor --check-install --format json
+# {"ssmforge_command_on_path": false, "fix_hint": "...", ...}
+```
+
 ### `ssmforge arch MODEL`
 
 The main command. Inspect a HuggingFace model.
@@ -436,7 +519,7 @@ ssmforge arch <model_id_or_path> [options]
 | `--fields name1,name2` | | Subset output to comma-separated field names. Dotted paths supported (e.g. `quirks.attention_bias`) | all |
 | `--profile` | | Emit only the profile section (family, attention_type, mlp_type, norm_type, descriptors) | full report |
 | `--only-different` | | In `--compare` mode, hide the "Identical across all models" section | show identical |
-| `--graph` | | Render a text-based decision-graph in your terminal. Single-model shows the full pipeline with decisions inline. `--compare --graph` shows an N-way decision table. | JSON |
+| `--graph` | | Render a text-based decision-graph in your terminal. Single-model shows the full pipeline with decisions inline. `--compare --graph` shows an N-way decision table. Honors `--format` (`text`, `json`, `markdown`/`md`) for JSON pipeline consumption and GFM-friendly docs. | JSON |
 
 **Examples:**
 
@@ -1114,7 +1197,7 @@ use a newer Python.
 **`pip install ssmforge` succeeds but `ssmforge` command not found**
 
 The install put the script in a directory not on your PATH. Activate
-your venv (see [4.2](#42-create-a-virtual-environment-recommended)) or
+your venv (see [4.2](#42-create-a-virtual-environment-recommended-strongly)) or
 check `pip show ssmforge` for the install location.
 
 **`ssmforge: command not found` after `pip install` succeeds (Windows)**
@@ -1317,7 +1400,143 @@ install.
 
 ## 16. Update log
 
-### v0.2.0 (current) — 2026-09-22
+### v0.2.2 (current) — 2026-09-23
+
+**Bug fix: `--output PATH` directory validation**
+
+When `--output PATH` points to a non-writable location, users were getting
+either a generic shell `Permission denied` (when using shell redirection)
+or an opaque Python `OSError` (when using `--output` directly). Now
+ssmforge pre-flight checks the parent directory and prints a friendly
+hint pointing at writable alternatives.
+
+**Before:**
+```
+$ python -m ssmforge.cli arch X --graph --format markdown > q.md
+bash: q.md: Permission denied
+
+$ python -m ssmforge.cli arch X --graph --format markdown --output C:\q.md
+Error: cannot write to 'C:\\q.md': [Errno 13] Permission denied: 'C:\\q.md'
+```
+
+**After:**
+```
+$ python -m ssmforge.cli arch X --graph --format markdown > q.md
+# (still works in any shell that allows the redirect)
+
+$ python -m ssmforge.cli arch X --graph --format markdown --output C:\q.md
+Error: cannot write to directory: C:\
+  Permission denied.
+  Try a writable location like:
+    --output ./report.md        (current directory)
+    --output ~/report.md        (your home directory)
+    --output $TMPDIR/report.md  (system temp)
+```
+
+Tests: 162 passed (was 156). 6 new tests for `_check_output_path`
+(returns (None, None) for None / '-' paths, validates writability,
+emits helpful hints for missing or read-only parents).
+
+### v0.2.1 — 2026-09-23
+
+**New feature: `doctor --check-install`**
+
+Run install checks (PATH, scripts location, platform) and exit non-zero
+when something is wrong. Use in scripts or when troubleshooting:
+
+```bash
+ssmforge doctor --check-install
+# prints ✓ or ✗ + fix hint
+echo $?  # 0 = good, 1 = something off
+```
+
+The fix-hint output is a copy-pasteable shell command — exactly the
+right `export PATH=...` or `[Environment]::SetEnvironmentVariable(...)`
+line for your platform.
+
+**New: one-time PATH warning on stderr**
+
+When ssmforge detects it's been installed off-PATH, every `ssmforge
+arch ...` call prints a one-time hint to stderr:
+
+```
+Note: 'ssmforge' is not on your PATH for `python -m ssmforge.cli` users.
+      This is normal if you're running via 'python -m ssmforge.cli'.
+      If 'ssmforge --version' fails, see: https://github.com/lordxmen2k/SSMForge#troubleshooting
+```
+
+This is suppressed:
+- when ssmforge IS on PATH
+- when the user explicitly runs `ssmforge doctor ...`
+- when `SSMFORGE_NO_PATH_WARN=1` is set in the env
+
+**README install lead**
+
+Section 4.2 (Create a virtual environment) now leads with a stronger
+recommendation and a fallback path (`python -m ssmforge.cli`). No
+changes to the install command itself — just clearer context.
+
+**Bug fix: Qwen2 attention_bias false positive**
+
+Previously, `scan_state_dict` set `attention_bias=True` whenever
+`*self_attn.*.bias` tensors existed in the state dict. Qwen2 ships
+zero-initialized bias tensors (vestigial, never used) and was
+incorrectly reported as having attention biases.
+
+Now: `attention_bias` is set to True only when **either** the config
+explicitly says `attention_bias=True` **or** the bias tensors contain
+non-zero values. The `bias_keys_found` list still records that the
+tensors exist for transparency.
+
+Tests:
+- `test_scan_detects_attention_bias` (updated) — zero biases → False
+- `test_scan_detects_nonzero_attention_bias` (new) — non-zero → True
+- `test_reports_attention_bias_from_state_dict_when_config_missing`
+  (updated) — config.attention_bias=None + zero biases → False
+
+**Bug fix: `--compare A A` no longer rejected**
+
+Previously `--compare A A` was dedup'd to `[A]` and rejected with
+"requires at least 2 models". Now produces a valid 2-way "all identical"
+report.
+
+**Feature: `--graph` honors `--format {text,json,markdown}`**
+
+Three output modes for `--graph`:
+- `--format text` (default for `--graph`) — ASCII with box-drawing
+- `--format json` — structured pipeline + decisions for piping into
+  other tools
+- `--format markdown`/`md` — GitHub-flavored Markdown tables for
+  embedding in docs, Issues, PRs
+
+All three work for both single-model and `--compare --graph` modes.
+
+**Bug fix: `--graph` ASCII hierarchy**
+
+The previous box-drawing had two parallel rails (`├─` and `▼`) that
+suggested two unrelated flows. Replaced with single-rail `▼` flow and
+`╭╮╰╯` panels for ATTENTION and MLP blocks. Decision-tree style
+`├─/└─` inside each panel. Renders correctly in any terminal.
+
+**Tests: 156 passed** (was 142). 14 new tests:
+- 12 from `test_v021_check_install.py` (PATH detection, doctor
+  --check-install, main() integration)
+- 1 from `test_v017_compare.py` (`--compare A A` regression)
+- 1 from `test_analyze.py` (nonzero attention_bias detection)
+- 13 from `test_graph.py` (JSON/Markdown formatters, GFM
+  compatibility, edge cases)
+- (some overlap with existing test updates for attention_bias fix)
+
+Tests: 142 passed (was 130). 12 new tests:
+- `_check_ssmforge_on_path`: returns correct tuple, finds off-path
+  install, returns no fix when on PATH
+- `_warn_path_once`: writes to stderr when off-path, respects env
+  var, skips when on PATH
+- `main()` integration: suppresses warning for doctor, emits for arch
+- `doctor --check-install`: text output on/off PATH, JSON output,
+  exit codes (0 / 1), back-compat with default `doctor`
+
+### v0.2.0 — 2026-09-22
 
 **New feature: `--graph`**
 

{ssmforge-0.2.0 → ssmforge-0.2.2}/README.md

@@ -59,6 +59,28 @@ visible *before* you spend the next hour finding out the hard way.
 It does **not** modify the model. It does **not** run inference. It only
 inspects.
 
+### What's new in 0.2.2
+
+| Fix | What was broken |
+|-----|-----------------|
+| `--output PATH` with bad parent dir | Previously got a generic `bash: Permission denied` (when redirecting) or a Python traceback (when using `--output`). Now pre-flight checks the parent directory, prints a clear hint pointing at writable locations like `./` and `~/`, then exits 1. |
+
+Plus 6 new tests (162 total). Tiny release — main bug fix only.
+
+### What's new in 0.2.1
+
+| Feature | Why it matters |
+|---------|----------------|
+| `doctor --check-install` | Diagnoses "ssmforge: command not found" in one command. Prints `✓` when on PATH, `✗` + a copy-pasteable fix hint when not. Exits non-zero so you can use it in scripts. |
+| One-time PATH warning | First invocation when `ssmforge` is off-PATH prints a hint to stderr pointing at `python -m ssmforge.cli`. Suppressed by `SSMFORGE_NO_PATH_WARN=1`. Skipped for `doctor` so its output stays clean. |
+| `--graph --format {text,json,markdown}` | `--graph` now respects `--format`. Single + compare modes emit ASCII (text), structured JSON (for pipelines), or GitHub-flavored Markdown (for docs/Issues). |
+| `--graph` ASCII cleanup | Box-drawing hierarchy fixed: single-rail `▼` flow + box `╭╮╰╯` panels for ATTENTION and MLP, `├─/└─` decision-tree style inside. |
+| Qwen2 attention_bias fixed | `config.attention_bias=None` + zero bias tensors (Qwen2's vestigial biases) no longer reports `attention_bias=True`. Now requires either config explicit True OR non-zero bias values. |
+| `--compare A A` is now valid | Was previously dedup'd to `[A]` and rejected. Now produces a 2-way "all identical" report. |
+| README install lead | Section 4.2 now recommends a venv more strongly + explains why + gives `python -m ssmforge.cli` as the universal workaround. |
+
+Plus 26 new tests (156 total).
+
 ### What's new in 0.2.0
 
 | Feature | Why it matters |
@@ -229,7 +251,13 @@ If you don't have it:
 - macOS: `brew install python@3.12`
 - Windows: download from https://www.python.org/downloads/
 
-### 4.2 Create a virtual environment (recommended)
+### 4.2 Create a virtual environment (recommended — strongly)
+
+**Use a venv.** It sidesteps the most common install problem on Windows
+(`ssmforge: command not found` after pip install). With a venv, the
+`ssmforge` script lands at `.venv\Scripts\ssmforge.exe` (Windows) or
+`.venv/bin/ssmforge` (Linux/macOS), which is automatically on PATH after
+you activate.
 
 A venv keeps ssmforge and its dependencies isolated from system Python.
 
@@ -250,6 +278,15 @@ python -m venv .venv
 You should see `(.venv)` in your prompt after activating. From here on,
 `pip install` only affects this venv.
 
+**Alternative: use `python -m ssmforge.cli`** as a workaround without a
+venv. Works anywhere, doesn't need any PATH setup, but requires typing
+`python -m ssmforge.cli` instead of just `ssmforge`.
+
+```bash
+python -m ssmforge.cli --version
+python -m ssmforge.cli arch hf-internal-testing/tiny-random-LlamaForCausalLM --dry-run
+```
+
 ### 4.3 Install ssmforge
 
 ```bash
@@ -393,6 +430,52 @@ JSON variant:
 ssmforge doctor --format json
 ```
 
+#### `ssmforge doctor --check-install`
+
+Run install checks (PATH, scripts location) and exit non-zero on issues.
+Useful in scripts or when troubleshooting "command not found":
+
+```bash
+ssmforge doctor --check-install
+```
+
+```
+ssmforge doctor --check-install (0.2.1)
+--------------------------------------------------
+  ✓ ssmforge command on PATH: True
+  python: C:\Users\netge\.venv\Scripts\python.exe
+  platform: win32
+```
+
+If `ssmforge` isn't on PATH, you get a fix-hint block:
+
+```
+ssmforge doctor --check-install (0.2.1)
+--------------------------------------------------
+  ✗ ssmforge command on PATH: False
+  python: C:\Python314\python.exe
+  platform: win32
+
+The 'ssmforge' script was installed to:
+    C:\Users\netge\AppData\Roaming\Python\Python314\Scripts\ssmforge.exe
+but that folder is not on PATH.
+
+  Quick fix (current shell):
+    export PATH="/c/Users/netge/AppData/Roaming/Python/Python314/Scripts:$PATH"
+
+  Permanent fix (PowerShell, restart shell after):
+    [Environment]::SetEnvironmentVariable("PATH", "<scripts>;" + [Environment]::GetEnvironmentVariable("PATH", "User"), "User")
+
+  Or just use: python -m ssmforge.cli
+```
+
+JSON variant:
+
+```bash
+ssmforge doctor --check-install --format json
+# {"ssmforge_command_on_path": false, "fix_hint": "...", ...}
+```
+
 ### `ssmforge arch MODEL`
 
 The main command. Inspect a HuggingFace model.
@@ -413,7 +496,7 @@ ssmforge arch <model_id_or_path> [options]
 | `--fields name1,name2` | | Subset output to comma-separated field names. Dotted paths supported (e.g. `quirks.attention_bias`) | all |
 | `--profile` | | Emit only the profile section (family, attention_type, mlp_type, norm_type, descriptors) | full report |
 | `--only-different` | | In `--compare` mode, hide the "Identical across all models" section | show identical |
-| `--graph` | | Render a text-based decision-graph in your terminal. Single-model shows the full pipeline with decisions inline. `--compare --graph` shows an N-way decision table. | JSON |
+| `--graph` | | Render a text-based decision-graph in your terminal. Single-model shows the full pipeline with decisions inline. `--compare --graph` shows an N-way decision table. Honors `--format` (`text`, `json`, `markdown`/`md`) for JSON pipeline consumption and GFM-friendly docs. | JSON |
 
 **Examples:**
 
@@ -1091,7 +1174,7 @@ use a newer Python.
 **`pip install ssmforge` succeeds but `ssmforge` command not found**
 
 The install put the script in a directory not on your PATH. Activate
-your venv (see [4.2](#42-create-a-virtual-environment-recommended)) or
+your venv (see [4.2](#42-create-a-virtual-environment-recommended-strongly)) or
 check `pip show ssmforge` for the install location.
 
 **`ssmforge: command not found` after `pip install` succeeds (Windows)**
@@ -1294,7 +1377,143 @@ install.
 
 ## 16. Update log
 
-### v0.2.0 (current) — 2026-09-22
+### v0.2.2 (current) — 2026-09-23
+
+**Bug fix: `--output PATH` directory validation**
+
+When `--output PATH` points to a non-writable location, users were getting
+either a generic shell `Permission denied` (when using shell redirection)
+or an opaque Python `OSError` (when using `--output` directly). Now
+ssmforge pre-flight checks the parent directory and prints a friendly
+hint pointing at writable alternatives.
+
+**Before:**
+```
+$ python -m ssmforge.cli arch X --graph --format markdown > q.md
+bash: q.md: Permission denied
+
+$ python -m ssmforge.cli arch X --graph --format markdown --output C:\q.md
+Error: cannot write to 'C:\\q.md': [Errno 13] Permission denied: 'C:\\q.md'
+```
+
+**After:**
+```
+$ python -m ssmforge.cli arch X --graph --format markdown > q.md
+# (still works in any shell that allows the redirect)
+
+$ python -m ssmforge.cli arch X --graph --format markdown --output C:\q.md
+Error: cannot write to directory: C:\
+  Permission denied.
+  Try a writable location like:
+    --output ./report.md        (current directory)
+    --output ~/report.md        (your home directory)
+    --output $TMPDIR/report.md  (system temp)
+```
+
+Tests: 162 passed (was 156). 6 new tests for `_check_output_path`
+(returns (None, None) for None / '-' paths, validates writability,
+emits helpful hints for missing or read-only parents).
+
+### v0.2.1 — 2026-09-23
+
+**New feature: `doctor --check-install`**
+
+Run install checks (PATH, scripts location, platform) and exit non-zero
+when something is wrong. Use in scripts or when troubleshooting:
+
+```bash
+ssmforge doctor --check-install
+# prints ✓ or ✗ + fix hint
+echo $?  # 0 = good, 1 = something off
+```
+
+The fix-hint output is a copy-pasteable shell command — exactly the
+right `export PATH=...` or `[Environment]::SetEnvironmentVariable(...)`
+line for your platform.
+
+**New: one-time PATH warning on stderr**
+
+When ssmforge detects it's been installed off-PATH, every `ssmforge
+arch ...` call prints a one-time hint to stderr:
+
+```
+Note: 'ssmforge' is not on your PATH for `python -m ssmforge.cli` users.
+      This is normal if you're running via 'python -m ssmforge.cli'.
+      If 'ssmforge --version' fails, see: https://github.com/lordxmen2k/SSMForge#troubleshooting
+```
+
+This is suppressed:
+- when ssmforge IS on PATH
+- when the user explicitly runs `ssmforge doctor ...`
+- when `SSMFORGE_NO_PATH_WARN=1` is set in the env
+
+**README install lead**
+
+Section 4.2 (Create a virtual environment) now leads with a stronger
+recommendation and a fallback path (`python -m ssmforge.cli`). No
+changes to the install command itself — just clearer context.
+
+**Bug fix: Qwen2 attention_bias false positive**
+
+Previously, `scan_state_dict` set `attention_bias=True` whenever
+`*self_attn.*.bias` tensors existed in the state dict. Qwen2 ships
+zero-initialized bias tensors (vestigial, never used) and was
+incorrectly reported as having attention biases.
+
+Now: `attention_bias` is set to True only when **either** the config
+explicitly says `attention_bias=True` **or** the bias tensors contain
+non-zero values. The `bias_keys_found` list still records that the
+tensors exist for transparency.
+
+Tests:
+- `test_scan_detects_attention_bias` (updated) — zero biases → False
+- `test_scan_detects_nonzero_attention_bias` (new) — non-zero → True
+- `test_reports_attention_bias_from_state_dict_when_config_missing`
+  (updated) — config.attention_bias=None + zero biases → False
+
+**Bug fix: `--compare A A` no longer rejected**
+
+Previously `--compare A A` was dedup'd to `[A]` and rejected with
+"requires at least 2 models". Now produces a valid 2-way "all identical"
+report.
+
+**Feature: `--graph` honors `--format {text,json,markdown}`**
+
+Three output modes for `--graph`:
+- `--format text` (default for `--graph`) — ASCII with box-drawing
+- `--format json` — structured pipeline + decisions for piping into
+  other tools
+- `--format markdown`/`md` — GitHub-flavored Markdown tables for
+  embedding in docs, Issues, PRs
+
+All three work for both single-model and `--compare --graph` modes.
+
+**Bug fix: `--graph` ASCII hierarchy**
+
+The previous box-drawing had two parallel rails (`├─` and `▼`) that
+suggested two unrelated flows. Replaced with single-rail `▼` flow and
+`╭╮╰╯` panels for ATTENTION and MLP blocks. Decision-tree style
+`├─/└─` inside each panel. Renders correctly in any terminal.
+
+**Tests: 156 passed** (was 142). 14 new tests:
+- 12 from `test_v021_check_install.py` (PATH detection, doctor
+  --check-install, main() integration)
+- 1 from `test_v017_compare.py` (`--compare A A` regression)
+- 1 from `test_analyze.py` (nonzero attention_bias detection)
+- 13 from `test_graph.py` (JSON/Markdown formatters, GFM
+  compatibility, edge cases)
+- (some overlap with existing test updates for attention_bias fix)
+
+Tests: 142 passed (was 130). 12 new tests:
+- `_check_ssmforge_on_path`: returns correct tuple, finds off-path
+  install, returns no fix when on PATH
+- `_warn_path_once`: writes to stderr when off-path, respects env
+  var, skips when on PATH
+- `main()` integration: suppresses warning for doctor, emits for arch
+- `doctor --check-install`: text output on/off PATH, JSON output,
+  exit codes (0 / 1), back-compat with default `doctor`
+
+### v0.2.0 — 2026-09-22
 
 **New feature: `--graph`**
 

{ssmforge-0.2.0 → ssmforge-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ssmforge"
-version = "0.2.0"
+version = "0.2.2"
 description = "Standalone HF architecture analyzer (`ssmforge arch`). Inspects any HuggingFace model and reports architectural quirks — attention biases, fused QKV/gate-up, tied embeddings, GQA, MQA, MoE, sliding window, LayerScale, soft-capping, partial RoPE, MLP type, norm type. Outputs structured JSON + human-readable summary."
 readme = "README.md"
 license = "Apache-2.0"

{ssmforge-0.2.0 → ssmforge-0.2.2}/src/ssmforge/__init__.py

@@ -1,3 +1,3 @@
 """SSMForge — architecture analyzer for HuggingFace models."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{ssmforge-0.2.0 → ssmforge-0.2.2}/src/ssmforge/analyze/__init__.py

@@ -34,7 +34,14 @@ from ssmforge.analyze.state_dict_scan import (
 from ssmforge.analyze.summary import render_summary
 from ssmforge.analyze.markdown_render import format_report_markdown
 from ssmforge.analyze.diff import diff_reports, compare_reports, format_compare_markdown
-from ssmforge.analyze.graph import render_graph_text, render_graph_compare
+from ssmforge.analyze.graph import (
+    render_graph_text,
+    render_graph_compare,
+    render_graph_json,
+    render_graph_compare_json,
+    render_graph_markdown,
+    render_graph_compare_markdown,
+)
 
 __all__ = [
     "build_report",