ThorOdinson246/whatisit-nl2sh

Local natural-language-to-shell command generator. A 941 MB fine-tuned Qwen2.5-Coder-1.5B running on CPU in ~1s.

whatisit‑nl2sh – 平易な英語をシェルコマンドに変換（オフライン）

機能 – whatisit は、タスクの自然言語による説明を受け取り、対応する Unix シェルコマンドを返す小さなコマンドラインツールです。llama.cpp を介してローカルで 1.5 B パラメータの LLM を実行するため、明示的にリモートの OpenAI 互換エンドポイントを指定しない限り、データがマシンの外に出ることはありません。

重要性 – ウェブを検索したり正確な構文を覚えたりすることなく、迅速に正しそうなコマンドを取得でき、プライバシーを保ちながらクラウド API の遅延を回避できます。モデルは小さく（約 941 MiB）、CPU のみのラップトップでも実行可能です。

クイックスタート

# CLI のインストール（pipx 推奨、通常の pip でも可）
pipx install whatisit          # または: pip install whatisit
whatisit setup                 # モデルをダウンロードし、llama.cpp バイナリを確認

既に llama.cpp ビルドがある場合は、--bin-dir で whatisit に指定します。

典型的な使用法

# 簡単なクエリ – コマンドを表示
whatisit find files bigger than 100MB in this folder
# → find . -size +100M -exec ls -lh {} \;

# 確認後にコマンドを実行
whatisit -e compress the logs directory into a tarball

# 複数の代替案を取得
whatisit -n 3 list python files modified today

# スクリプトで出力を使用
cd "$(whatisit -q the directory holding the largest log file)"

フラグ:

-e/--execute – 確認を求めてからコマンドを実行。
-n N – N 個の候補コマンドを返す。
-q/--quiet – 生のコマンドのみ出力（コマンド置換に便利）。
-t/--timing – 生成にかかった時間を表示。
-p/--prefill-command – 実行前に生成されたコマンドを編集可能なプロンプトで開く。

シェルプロンプトに統合することもできます:

# ~/.bashrc または ~/.zshrc に追加
eval "$(whatisit shell-init)"

これで whatisit <request> は生成されたコマンドを次のプロンプト行に配置し、編集が容易になります。

内部の仕組み

モデル – Qwen2.5‑Coder‑1.5B‑Instruct（またはオプションの 3 B バリアント）の LoRA 微調整版で、GGUF Q4_K_M（約 941 MiB）に量子化されています。トレーニングには 125 k の NL‑to‑command ペアが使用されました。
ランタイム – モデルは llama.cpp の llama-server によって提供されます。最初の呼び出しで常駐サーバーが起動し、以降の呼び出しはモデルが RAM に保持されるため高速です（1.5 B モデルで約 1.6 GiB）。
生成 – 温度 0 の貪欲デコードにより、同じクエリは常に同じコマンドを生成します。Intel i5‑11320H での典型的なスループット: 約 39 tokens/s、ウォームアップ後のレイテンシ約 0.6 秒。
安全レイヤー – 出力前に、ルールベースのチェッカーが危険なパターン（/ の再帰的削除、ブロックデバイスへの書き込み、権限昇格のトリック、リバースシェルなど）をスキャンします。フラグが付けられたコマンドは DANGER（自動実行不可）または CAUTION（警告付きで任意）とラベル付けされます。

オフライン vs. リモートモード

デフォルト – 完全オフライン。リクエストはホストから出ません。
リモート – 設定で openai_base_url と openai_model（または Ollama エンドポイント）を設定すると、クエリをホスト型 API にルーティングします。ツールはリモート呼び出しのたびに警告を表示します。

インストール詳細

ステップ	必要なもの
CLI	`pipx install whatisit`（または venv で `pip install whatisit`）
モデルファイル	Hugging Face から `huggingface_hub` 経由で `nl2sh-1.5b-Q4_K_M.gguf`（約 941 MiB）をダウンロード
`llama.cpp` バイナリ	プリビルドリリース（`llama-server`、`llama-cli`）を取得するか、自分でビルド。Linux では glibc ≥ 2.34 が必要
設定	`whatisit setup --model <path> --bin-dir <path/to/llama.cpp/bin>`

Nix/NixOS ユーザー向けに Nix flake も提供されており、llama.cpp パッケージが自動的に組み込まれます。

パフォーマンスとベンチマーク

InterCode‑ALFA ベンチマーク（300 の NL‑to‑shell タスク）
- whatisit（1.5 B）– 62 % の合格率、ウォーム時中央値レイテンシ 0.59 秒、コールドスタート 2 秒。
- オプションの 3 B モデル – 65.7 % の合格率、生成が遅い（約 17 tok/s）、RAM 使用量が高い（約 3.4 GiB）。
- 未調整の Qwen2.5‑Coder‑7B（61.3 %）および GPT‑4o（73 %）と比較。
未調整のベース（54 %）に対する改善は統計的に有意（p ≈ 0.004）。

安全性と制限

安全性 – 再帰的削除、ブロックデバイスへの書き込み、権限変更、ネットワーク取得コマンドなどをカバーするルールベースの拒否リスト。サンドボックスではないため、出力を確認する必要があります。
制限 – 単一ターンのみ（シェル状態なし）、最大 64‑token 出力（複数行スクリプトには不向き）、英語のみ、ベンチマーク固有のパフォーマンス。

ライセンスと帰属

コード: Apache‑2.0
モデル: Qwen2.5‑Coder‑1.5B‑Instruct（Apache‑2.0）から派生し、さまざまな寛容なライセンス（MIT、CC‑BY‑4.0、CC0、Apache‑2.0）のソースからのトレーニングデータを使用。完全なデータセットは後日公開予定。

次のステップ

より高い精度のために 3 B モデルを試す（whatisit setup --size 3b）。
安全チェッカーの改善やマルチターン対話のサポートに貢献。
リポジトリをフォローして毎日の更新チェック（設定で無効化可能）。

まとめ – whatisit は、日常的な英語の指示をシェルコマンドに変換する、プライバシーを保護し低リソースな方法を提供し、組み込みの安全フィルターとオプションのリモート API フォールバックを備えています。