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

{sft_cli-0.1.0 → sft_cli-0.2.0}/.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.11", "3.12"]
     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.12 / 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.12
+
+      - 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
 
@@ -61,11 +93,19 @@ jobs:
         uses: astral-sh/setup-uv@v4
 
       - name: Set up Python
-        run: uv python install 3.14
+        run: uv python install 3.12
 
       - 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.2.0/.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.0/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.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: sft-cli
+Version: 0.2.0
+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
+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: 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
+
+A fast, interactive terminal browser for `.safetensors` files.
+AI-agent friendly — run `sft skill install` to teach Claude, Cursor, and Codex CLI how to use it.
+
+<p align="center">
+  <img src="https://vhs.charm.sh/vhs-6eQ3Cv0oexkfUshZ7PmO3b.gif" alt="sft demo">
+</p>
+
+## Why?
+
+If you work with ML models, you've probably found yourself wondering "what's actually in this .safetensors file?" — the layer names, shapes, dtypes, sizes. Maybe you want to check if a model has the layers you expect, compare two checkpoints, or just explore an unfamiliar architecture.
+
+`sft` lets you do that instantly from your terminal. No Python scripts, no notebooks, no waiting for tensors to load into memory. It reads only the file header, so even multi-gigabyte models open in milliseconds.
+
+## ⚡ Installation
+
+The recommended way to install is via [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install sft-cli
+```
+
+This makes `sft` available globally as a command.
+
+Or install with pip:
+
+```bash
+pip install sft-cli
+```
+
+## Usage
+
+```bash
+sft model.safetensors
+```
+
+That's it. Navigate with arrow keys, search with `/`, quit with `q`.
+
+## ✨ Features
+
+- **Hierarchical browser** — Tensors grouped by namespace (e.g., `model.layers.0.attention`)
+- **Instant startup** — Header-only parsing, works on multi-GB files
+- **Search** — Filter tensors by name with `/`
+- **Sort** — By name, size, or rank with `s`
+- **Inspect** — View full tensor details with `Space`
+- **Metadata** — See embedded file metadata with `m`
+- **Read-only** — Never touches your model files
+
+## ⌨️ Keybindings
+
+| Key | Action |
+|-----|--------|
+| `↑`/`↓` | Navigate |
+| `←`/`→` | Collapse/expand tree |
+| `Tab` | Switch panels |
+| `/` | Search |
+| `s` | Cycle sort mode |
+| `Space` | Tensor details |
+| `m` | File metadata |
+| `f` | Filter by dtype |
+| `q` | Quit |
+
+## Use with AI agents
+
+`sft` ships with an installable agent skill that teaches AI coding agents (Claude Code, Cursor, Codex CLI, and anything supporting the `~/.agents/skills/` open standard) when and how to use the CLI:
+
+```bash
+sft skill install        # auto-detects installed agents
+sft skill status         # see where it's installed and how
+sft skill uninstall      # tidy up
+```
+
+The default install is a symlink (or directory junction on Windows) into each agent's well-known skills directory, so the skill auto-updates whenever you upgrade `sft-cli` (`uv tool upgrade sft-cli` / `pip install -U sft-cli`). Pass `--mode copy` if you'd rather have a frozen copy.
+
+Every command also supports `--json` for reliable parsing — agents are taught to always pass `--json` when their output will be parsed.
+
+## License
+
+MIT

sft_cli-0.2.0/README.md

@@ -0,0 +1,80 @@
+# sft
+
+A fast, interactive terminal browser for `.safetensors` files.
+AI-agent friendly — run `sft skill install` to teach Claude, Cursor, and Codex CLI how to use it.
+
+<p align="center">
+  <img src="https://vhs.charm.sh/vhs-6eQ3Cv0oexkfUshZ7PmO3b.gif" alt="sft demo">
+</p>
+
+## Why?
+
+If you work with ML models, you've probably found yourself wondering "what's actually in this .safetensors file?" — the layer names, shapes, dtypes, sizes. Maybe you want to check if a model has the layers you expect, compare two checkpoints, or just explore an unfamiliar architecture.
+
+`sft` lets you do that instantly from your terminal. No Python scripts, no notebooks, no waiting for tensors to load into memory. It reads only the file header, so even multi-gigabyte models open in milliseconds.
+
+## ⚡ Installation
+
+The recommended way to install is via [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install sft-cli
+```
+
+This makes `sft` available globally as a command.
+
+Or install with pip:
+
+```bash
+pip install sft-cli
+```
+
+## Usage
+
+```bash
+sft model.safetensors
+```
+
+That's it. Navigate with arrow keys, search with `/`, quit with `q`.
+
+## ✨ Features
+
+- **Hierarchical browser** — Tensors grouped by namespace (e.g., `model.layers.0.attention`)
+- **Instant startup** — Header-only parsing, works on multi-GB files
+- **Search** — Filter tensors by name with `/`
+- **Sort** — By name, size, or rank with `s`
+- **Inspect** — View full tensor details with `Space`
+- **Metadata** — See embedded file metadata with `m`
+- **Read-only** — Never touches your model files
+
+## ⌨️ Keybindings
+
+| Key | Action |
+|-----|--------|
+| `↑`/`↓` | Navigate |
+| `←`/`→` | Collapse/expand tree |
+| `Tab` | Switch panels |
+| `/` | Search |
+| `s` | Cycle sort mode |
+| `Space` | Tensor details |
+| `m` | File metadata |
+| `f` | Filter by dtype |
+| `q` | Quit |
+
+## Use with AI agents
+
+`sft` ships with an installable agent skill that teaches AI coding agents (Claude Code, Cursor, Codex CLI, and anything supporting the `~/.agents/skills/` open standard) when and how to use the CLI:
+
+```bash
+sft skill install        # auto-detects installed agents
+sft skill status         # see where it's installed and how
+sft skill uninstall      # tidy up
+```
+
+The default install is a symlink (or directory junction on Windows) into each agent's well-known skills directory, so the skill auto-updates whenever you upgrade `sft-cli` (`uv tool upgrade sft-cli` / `pip install -U sft-cli`). Pass `--mode copy` if you'd rather have a frozen copy.
+
+Every command also supports `--json` for reliable parsing — agents are taught to always pass `--json` when their output will be parsed.
+
+## License
+
+MIT