sft-cli 0.1.0__tar.gz → 0.2.1__tar.gz

{sft_cli-0.1.0 → sft_cli-0.2.1}/.github/workflows/ci.yml

@@ -32,11 +32,13 @@ jobs:
         run: uv run ruff format --check .
 
   test:
-    runs-on: ubuntu-latest
+    name: test (py${{ matrix.python-version }} / ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.9", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@v4
 
@@ -47,13 +49,43 @@ jobs:
         run: uv python install ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: uv sync
+        run: uv sync --dev
 
       - name: Verify package imports
         run: uv run python -c "from sft.cli import app; from sft.browser import SftApp; from sft.index import TensorIndex; print('All imports successful')"
 
+      - name: Run fast test suite
+        run: uv run pytest -q
+
+  test-slow:
+    # Long-running tests (subprocess E2E, perf smoke, build-hook) only need
+    # to pass on one cell — they exercise behavior that's OS- and version-
+    # independent.
+    name: slow tests (py3.14 / ubuntu)
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Install package (so the `sft` console script is on PATH)
+        run: uv pip install -e .
+
+      - name: Run slow tests
+        run: uv run pytest -q -m slow
+
   build:
+    name: build wheel + smoke install
     runs-on: ubuntu-latest
+    needs: test
     steps:
       - uses: actions/checkout@v4
 
@@ -66,6 +98,14 @@ jobs:
       - name: Build package
         run: uv build
 
+      - name: Smoke install + help from a clean venv
+        run: |
+          python3 -m venv /tmp/sft-smoke
+          /tmp/sft-smoke/bin/pip install --upgrade pip
+          /tmp/sft-smoke/bin/pip install dist/sft_cli-*.whl
+          /tmp/sft-smoke/bin/sft --help
+          /tmp/sft-smoke/bin/sft --version
+
       - name: Upload build artifacts
         uses: actions/upload-artifact@v4
         with:

{sft_cli-0.1.0 → sft_cli-0.2.1}/.github/workflows/publish.yml

@@ -14,7 +14,7 @@ jobs:
         uses: astral-sh/setup-uv@v4
 
       - name: Set up Python
-        run: uv python install 3.12
+        run: uv python install 3.14
 
       - name: Build package
         run: uv build

sft_cli-0.2.1/.gitignore

@@ -0,0 +1,34 @@
+# macOS
+.DS_Store
+
+# Generated demo artifacts
+demo.gif
+demo.tape
+
+# AI agent documents
+.ai/
+
+# Python
+__pycache__/
+*.py[cod]
+*.so
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+
+# IDE
+.vscode/
+.idea/
+
+# Testing
+.pytest_cache/
+.coverage
+
+# Test files
+*.safetensors
+
+# Skill installer state (written by `sft skill install` into the source dir
+# when developing locally — not source code).
+.sft-skill-install.json

sft_cli-0.2.1/AGENTS.md

@@ -0,0 +1,92 @@
+# AGENTS.md — guidance for AI agents working on `sft-cli`
+
+This file is read by Claude Code, Cursor, Codex CLI, and other agents to understand the repo. It is meant for agents **modifying this codebase**, not end-users of the CLI.
+
+## What this project is
+
+`sft-cli` is a CLI ("`sft`") for inspecting and editing `.safetensors` files. It is published on PyPI as `sft-cli` and the user-facing command is `sft`.
+
+## Repo layout
+
+- `src/sft/cli.py` — Typer app entry point, the auto-`browse` shim, and top-level commands (`browse`, `info`, `check`). Every other subcommand is registered by importing its module at the bottom of this file.
+- `src/sft/commands/<name>.py` — thin CLI wrappers (Typer surface, argument parsing, formatting, `--json`). They delegate to `src/sft/ops/<name>.py`.
+- `src/sft/ops/<name>.py` — pure business logic. No Typer, no printing; returns dataclasses. Always testable in isolation.
+- `src/sft/utils/` — shared helpers (formatting, dtype mapping, glob filtering, tensor IO, cross-platform linking for the skill installer).
+- `src/sft/browser.py` — the interactive Textual TUI (the `browse` command). Self-contained, do not import from other commands.
+- `src/sft/index.py` — the `TensorIndex` / `PrefixTree` data model, parsed header-only from `.safetensors` files.
+- `src/sft/skill/` — the agent skill that ships inside the wheel and is installed by `sft skill install`. Two files: `SKILL.md` (hand-written: trigger description, command map, cookbook of cross-command patterns) and `REFERENCE.md` (**auto-generated** — never edit by hand).
+- `scripts/build_skill_reference.py` — regenerates `src/sft/skill/REFERENCE.md` from the live Typer CLI.
+- `scripts/hatch_build_hook.py` — hatch build hook that runs the regenerator at wheel-build time (tolerates missing deps in isolated builds).
+- `tests/` — pytest tests, one file per command. Shared fixtures in `tests/conftest.py`.
+
+## Conventions
+
+1. **`--json` everywhere on commands an agent might parse.** Every command supports `--json` and outputs a stable JSON contract. When you add a new command, add `--json` from day one and update `SKILL.md`. The pattern is:
+
+   ```python
+   if json_output:
+       typer.echo(json.dumps(data, indent=2))
+       return
+   # human-readable fallback below
+   ```
+
+   Errors raised via `--json` should also be JSON: `typer.echo(json.dumps({"error": str(e)}, indent=2))` before `raise typer.Exit(code=1)`.
+
+2. **Separation of concerns.** A new feature `foo` means:
+   - Pure logic in `src/sft/ops/foo.py` (returns a dataclass).
+   - CLI wrapper in `src/sft/commands/foo.py` (imports `ops/foo.py`, owns flags and printing).
+   - Register by adding `import sft.commands.foo` to the bottom of `src/sft/cli.py` (the imports there look stylistically dead but they trigger `@app.command(...)` decorators — keep them sorted alphabetically).
+   - Tests in `tests/test_foo.py` (CLI tests use `typer.testing.CliRunner`).
+
+3. **The auto-`browse` shim** in `_entry()` rewrites `sft x.safetensors` → `sft browse x.safetensors`. Do not add subcommands whose names end in `.safetensors`.
+
+4. **`validate_safetensors(path)`** in `src/sft/cli.py` is the canonical "is this a `.safetensors` file?" check. Use it from every command that takes a `.safetensors` argument.
+
+5. **Output paths** use the `resolve_output(output, src, suffix)` helper in `src/sft/utils/output.py` to default to `{stem}.{suffix}.safetensors`. Write commands should never overwrite the source file.
+
+6. **Dry-run.** Every write-side command exposes `--dry-run` and the underlying op must support `dry_run=True` to return a result without touching disk.
+
+7. **Header-only reads.** Prefer `TensorIndex.from_file(path)` (header-only, milliseconds) over loading tensor data unless you specifically need values. Header-only operations are why `sft` exists.
+
+## Updating the agent skill
+
+The shipped skill lives in `src/sft/skill/`:
+
+- `SKILL.md` — hand-written: trigger description (YAML frontmatter), golden `--json` rule, command map, "when to use" guidance, and an inline cookbook of cross-command patterns and `jq` recipes.
+- `REFERENCE.md` — **auto-generated** from Typer introspection. Regenerate with:
+
+  ```bash
+  python scripts/build_skill_reference.py
+  ```
+
+  This also runs as a hatch build hook during `uv build`, so the wheel always contains an up-to-date reference. The script is best-effort: if it can't import `sft` (e.g. inside an isolated build env), it leaves the committed file alone.
+
+When you add a new command or flag, also:
+
+- Update the command-map table in `SKILL.md` if the command is something agents should reach for.
+- If the command enables a cross-command workflow or a useful `--json` parsing pattern that isn't obvious from the single-command help, add it to the "Cookbook" section in `SKILL.md`. Resist the urge to write per-command tutorials — `REFERENCE.md` already covers single-command usage.
+
+## Dev commands
+
+```bash
+uv sync                                          # install deps
+uv run pytest -q                                  # full test suite
+uv run pytest tests/test_<command>.py -q         # one file
+uv run ruff check                                # lint
+uv run ruff format                               # format
+python scripts/build_skill_reference.py          # regenerate skill reference
+uv build                                          # produce wheel + sdist (regenerates skill ref via hook)
+uv run sft skill install --dry-run               # preview a skill install locally
+```
+
+## Known stylistic notes
+
+- Top-level imports in `src/sft/cli.py` use `# noqa: F401, E402` because they're after function definitions and are imported for their side effect (registering commands). Keep that pattern.
+- We support Python ≥ 3.9. Avoid `match` statements, walrus inside comprehensions, and other newer syntax in shared code paths. Use `from __future__ import annotations` at the top of every module.
+- The pre-commit config runs `ruff` (lint + format). Run `uv run ruff check` and `uv run ruff format` before committing.
+
+## Out-of-scope for changes
+
+- Do **not** add an MCP server module. The skill + reliable `--json` is the intended agent integration story.
+- Do **not** silently rewrite `src/sft/skill/REFERENCE.md` by hand; always regenerate via the script.
+- Do **not** invent new install locations for the skill installer without updating `AGENT_DIRS` in `src/sft/commands/skill.py` and the corresponding docs in `SKILL.md` and `README.md`.

sft_cli-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matan Ben-Yosef
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sft_cli-0.2.1/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: sft-cli
+Version: 0.2.1
+Summary: An interactive terminal browser for .safetensors files
+Project-URL: Homepage, https://github.com/matanby/sft-cli
+Project-URL: Repository, https://github.com/matanby/sft-cli
+Author: Matan Ben-Yosef
+License: MIT
+License-File: LICENSE
+Keywords: browser,cli,machine-learning,safetensors,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: ml-dtypes>=0.3
+Requires-Dist: numpy>=1.24
+Requires-Dist: safetensors>=0.4
+Requires-Dist: textual>=0.40
+Requires-Dist: typer>=0.9
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# sft
+
+> The Swiss army knife for `.safetensors` files.
+
+[![PyPI](https://img.shields.io/pypi/v/sft-cli?style=flat-square)](https://pypi.org/project/sft-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/sft-cli?style=flat-square)](https://pypi.org/project/sft-cli/)
+[![CI](https://img.shields.io/github/actions/workflow/status/matanby/sft-cli/ci.yml?branch=main&style=flat-square)](https://github.com/matanby/sft-cli/actions)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+
+<img src="https://vhs.charm.sh/vhs-3nFXGLuvC5swABYCewgchD.gif" alt="sft demo">
+
+`sft` is a single-binary CLI for inspecting, editing, and diffing `.safetensors` files — and an interactive terminal browser for poking around large checkpoints. Most commands read the file header only, so multi-gigabyte models open in milliseconds.
+
+It also ships a [skill](#-ai-agents) that teaches AI coding agents (Claude Code, Cursor, Codex CLI) when to reach for it and how to parse the output.
+
+## Install
+
+```bash
+uv tool install sft-cli                 # recommended
+pip install sft-cli                     # or pip
+uv tool install 'sft-cli[torch]'        # + .pt/.pth conversion
+```
+
+## 🚀 Quick start
+
+```bash
+sft model.safetensors                   # open the interactive browser
+sft info model.safetensors              # one-shot summary
+sft info model.safetensors --json       # machine-readable
+```
+
+The bare `sft <file>` form is a shortcut for `sft browse <file>`. Inside the browser: `↑↓` to navigate, `/` to filter, `L` on a LoRA file for LoRA Mode, `D` to diff against another file, `q` to quit.
+
+## What it does
+
+**Inspect** a file without loading it:
+
+```bash
+sft info  model.safetensors             # size, tensor count, dtypes, metadata
+sft ls    model.safetensors             # flat list, sort/filter friendly
+sft tree  model.safetensors --depth=2   # hierarchical view
+sft stat  model.safetensors             # per-tensor mean/std/min/max/sparsity
+sft check model.safetensors             # corruption + NaN/Inf scan
+```
+
+**Compare** two checkpoints:
+
+```bash
+sft diff base.safetensors finetuned.safetensors --delta \
+    --include='**.self_attn.**'         # cosine, L2, max-abs per tensor
+```
+
+**Edit** without writing Python:
+
+```bash
+sft slice  big.safetensors --include='**.weight' -o weights-only.safetensors
+sft strip  big.safetensors --exclude='*lora_*'
+sft cast   model.safetensors --dtype fp16
+sft cat    a.safetensors b.safetensors -o merged.safetensors
+sft rename model.safetensors --sub 'model\.' 'backbone.'
+sft split  model.safetensors --max-size 4GB
+sft convert pytorch_model.bin           # → safetensors
+```
+
+Every write command supports `--dry-run` and never overwrites the input — outputs default to `{stem}.{suffix}.safetensors`.
+
+**Adapter workflows** (PEFT and Kohya):
+
+```bash
+sft lora info    adapter.safetensors            # rank, alpha, target modules
+sft lora svd     adapter.safetensors            # singular-value spectrum
+sft lora compat  base.safetensors adapter.safetensors
+sft lora extract base.safetensors ft.safetensors --rank 16
+sft lora resize  adapter.safetensors --rank auto    # per-pair adaptive rank
+sft lora stack   a.safetensors b.safetensors -a 0.7 -b 0.3
+sft lora merge   base.safetensors adapter.safetensors
+sft lora convert adapter.safetensors --to peft      # Kohya ↔ PEFT
+```
+
+`--rank auto` picks each pair's output rank from its singular-value spectrum (`ceil(stable_rank) + 1`), so over-parameterized pairs compress harder than rich ones. `auto+N` adds a safety margin.
+
+## The browser
+
+Press a key, get a result.
+
+| Key | Action |
+|:---:|---|
+| `↑` `↓` | Navigate |
+| `←` `→` | Collapse / expand tree |
+| `Tab` | Switch between tree and table |
+| `/` | Search / filter |
+| `s` | Cycle sort |
+| `Enter` | Tensor stats popup |
+| `m` | File metadata |
+| `c` | Cast file dtype |
+| `L` | LoRA Mode (per-pair stats, SVD, compress) |
+| `D` | Diff against another file |
+| `:` | Command palette |
+| `q` | Quit |
+
+## 🤖 AI agents
+
+```bash
+sft skill install                       # auto-detects Claude / Cursor / Codex
+sft skill status
+sft skill uninstall
+```
+
+The installer symlinks `sft`'s skill into your agent's well-known skills directory (`~/.claude/skills/sft`, `~/.cursor/skills/sft`, etc.), so it stays in sync when you `uv tool upgrade sft-cli`. Pass `--mode copy` for a frozen snapshot.
+
+Every command supports `--json` for clean parsing:
+
+```bash
+sft info model.safetensors --json | jq '.tensors'
+sft lora info adapter.safetensors --json | jq '.rank'
+sft stat model.safetensors --json --include='**.q_proj.*'
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sft_cli-0.2.1/README.md

@@ -0,0 +1,121 @@
+# sft
+
+> The Swiss army knife for `.safetensors` files.
+
+[![PyPI](https://img.shields.io/pypi/v/sft-cli?style=flat-square)](https://pypi.org/project/sft-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/sft-cli?style=flat-square)](https://pypi.org/project/sft-cli/)
+[![CI](https://img.shields.io/github/actions/workflow/status/matanby/sft-cli/ci.yml?branch=main&style=flat-square)](https://github.com/matanby/sft-cli/actions)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+
+<img src="https://vhs.charm.sh/vhs-3nFXGLuvC5swABYCewgchD.gif" alt="sft demo">
+
+`sft` is a single-binary CLI for inspecting, editing, and diffing `.safetensors` files — and an interactive terminal browser for poking around large checkpoints. Most commands read the file header only, so multi-gigabyte models open in milliseconds.
+
+It also ships a [skill](#-ai-agents) that teaches AI coding agents (Claude Code, Cursor, Codex CLI) when to reach for it and how to parse the output.
+
+## Install
+
+```bash
+uv tool install sft-cli                 # recommended
+pip install sft-cli                     # or pip
+uv tool install 'sft-cli[torch]'        # + .pt/.pth conversion
+```
+
+## 🚀 Quick start
+
+```bash
+sft model.safetensors                   # open the interactive browser
+sft info model.safetensors              # one-shot summary
+sft info model.safetensors --json       # machine-readable
+```
+
+The bare `sft <file>` form is a shortcut for `sft browse <file>`. Inside the browser: `↑↓` to navigate, `/` to filter, `L` on a LoRA file for LoRA Mode, `D` to diff against another file, `q` to quit.
+
+## What it does
+
+**Inspect** a file without loading it:
+
+```bash
+sft info  model.safetensors             # size, tensor count, dtypes, metadata
+sft ls    model.safetensors             # flat list, sort/filter friendly
+sft tree  model.safetensors --depth=2   # hierarchical view
+sft stat  model.safetensors             # per-tensor mean/std/min/max/sparsity
+sft check model.safetensors             # corruption + NaN/Inf scan
+```
+
+**Compare** two checkpoints:
+
+```bash
+sft diff base.safetensors finetuned.safetensors --delta \
+    --include='**.self_attn.**'         # cosine, L2, max-abs per tensor
+```
+
+**Edit** without writing Python:
+
+```bash
+sft slice  big.safetensors --include='**.weight' -o weights-only.safetensors
+sft strip  big.safetensors --exclude='*lora_*'
+sft cast   model.safetensors --dtype fp16
+sft cat    a.safetensors b.safetensors -o merged.safetensors
+sft rename model.safetensors --sub 'model\.' 'backbone.'
+sft split  model.safetensors --max-size 4GB
+sft convert pytorch_model.bin           # → safetensors
+```
+
+Every write command supports `--dry-run` and never overwrites the input — outputs default to `{stem}.{suffix}.safetensors`.
+
+**Adapter workflows** (PEFT and Kohya):
+
+```bash
+sft lora info    adapter.safetensors            # rank, alpha, target modules
+sft lora svd     adapter.safetensors            # singular-value spectrum
+sft lora compat  base.safetensors adapter.safetensors
+sft lora extract base.safetensors ft.safetensors --rank 16
+sft lora resize  adapter.safetensors --rank auto    # per-pair adaptive rank
+sft lora stack   a.safetensors b.safetensors -a 0.7 -b 0.3
+sft lora merge   base.safetensors adapter.safetensors
+sft lora convert adapter.safetensors --to peft      # Kohya ↔ PEFT
+```
+
+`--rank auto` picks each pair's output rank from its singular-value spectrum (`ceil(stable_rank) + 1`), so over-parameterized pairs compress harder than rich ones. `auto+N` adds a safety margin.
+
+## The browser
+
+Press a key, get a result.
+
+| Key | Action |
+|:---:|---|
+| `↑` `↓` | Navigate |
+| `←` `→` | Collapse / expand tree |
+| `Tab` | Switch between tree and table |
+| `/` | Search / filter |
+| `s` | Cycle sort |
+| `Enter` | Tensor stats popup |
+| `m` | File metadata |
+| `c` | Cast file dtype |
+| `L` | LoRA Mode (per-pair stats, SVD, compress) |
+| `D` | Diff against another file |
+| `:` | Command palette |
+| `q` | Quit |
+
+## 🤖 AI agents
+
+```bash
+sft skill install                       # auto-detects Claude / Cursor / Codex
+sft skill status
+sft skill uninstall
+```
+
+The installer symlinks `sft`'s skill into your agent's well-known skills directory (`~/.claude/skills/sft`, `~/.cursor/skills/sft`, etc.), so it stays in sync when you `uv tool upgrade sft-cli`. Pass `--mode copy` for a frozen snapshot.
+
+Every command supports `--json` for clean parsing:
+
+```bash
+sft info model.safetensors --json | jq '.tensors'
+sft lora info adapter.safetensors --json | jq '.rank'
+sft stat model.safetensors --json --include='**.q_proj.*'
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).