kdeps-commands-model

version: 2.1.0
# kdeps update installs these with this command: what its run steps use
requires:
  tools/session_ops: ""
  tools/hf_search: ""
  tools/hf_repo_files: ""
name: model
order: 40
usage:
  - args: "[name]"
    help: Show or set the LLM model (no name opens the picker)
  - args: "record [clear]"
    help: Show the current model's record of caught refusals (sent to it each turn), or clear it
  - args: "default [name]"
    help: Show or save the default startup model
  - args: list
    help: List all available models with provider status
  - args: ps
    help: List running local model servers (llamafile/gguf)
  - args: "ps kill <model>"
    help: Kill a running local model server
  - args: "ps switch <model>"
    help: Switch to a running local model server
  - args: "hff search <query>"
    help: Search HuggingFace for GGUF models
  - args: "hff info <repo>"
    help: List GGUF files available in a HuggingFace repo
  - args: "hff download <repo> <file>"
    help: Download a GGUF file from HuggingFace
  - args: "<url>"
    help: Register a .gguf/.llamafile URL or OpenAI-compatible endpoint
  - args: "favorite <name>"
    help: "Star a model (shown first in /model, persists); unfavorite to remove"
  - args: "name [show|hide|abbreviate|auto]"
    help: Show or set how the modeline displays the model name
  - args: "tool [list]"
    help: "Show agent loop settings (tool rounds, retries, compaction)"
  - args: "tool set <setting> <value>"
    help: "Change a setting for this session (e.g. rounds 80, retry-delay 5s)"
subcommands:
  "":                     # no argument: the picker, or the current model without one
    run:
      - tool: session_ops
        args: {operation: model_pick}
        print: "{{if not .picked}}Current model: {{.model}}{{end}}"
  "*": &switch           # any other word: a model name or URL to switch to
    run:
      - tool: session_ops
        args: {operation: model, name: "$1"}
        # the switch itself prints the new model; these are the notes on how the name resolved
        print: >-
          {{if .registered}}Registered as {{.registered}} -- use `/model {{.registered}}` next time.{{end}}{{if .ambiguous}}{{printf "%q" .typed}} is ambiguous across backends ({{join .ambiguous ", "}}) -- using {{.model}}. Use the full name to pick a specific one.{{end}}{{if .closest}}No exact match for {{printf "%q" .typed}} -- switched to closest: {{.closest}}{{end}}
  default:
    run:
      - tool: session_ops
        args: {operation: model_default, name: "$1"}
        print: >-
          {{if .typed}}{{printf "%q" .typed}} is ambiguous across backends ({{join .ambiguous ", "}}) -- saving {{.model}} as default. Use the full name to pick a specific one.
          {{end}}{{if eq (printf "%v" .configured) "false"}}No default persistence configured.{{else if eq (printf "%v" .configured) "true"}}**Default model**
            Use `/model default <name>` to set the startup model.{{else}}Default model saved - will be used at next startup.{{end}}
  record:
    subcommands:
      "":
        run:
          - tool: session_ops
            args: {operation: model_record}
            print: |-
              {{if not .refusals}}{{.model}} has no refusals on record.{{else}}**{{.model}}: {{.count}} caught refusals** (sent to the model as its record)
              {{range .refusals}}
              - {{.at}} [{{.kind}}] {{.text}}{{end}}{{end}}
      clear:
        run:
          - tool: session_ops
            args: {operation: model_record_clear}
            print: "{{if .cleared}}Cleared the refusal record of {{.model}}.{{else}}{{.model}} has no refusal record.{{end}}"
  list:
    run:
      - tool: session_ops
        args: {operation: models}
        print: |-
          **Available models** (use `/model <id>` to switch)
          {{range .cloud}}
          **{{.backend}}** {{if .ready}}[READY]{{else}}[NO KEY - set {{.env}}]{{end}}
          {{range .models}}
          - `{{.id}}` {{.desc}}{{if .current}} **<-- current**{{end}}{{end}}
          {{end}}{{if .local}}
          **LOCAL** (ollama / llamafile / gguf)
          {{range .local}}
          - {{if .downloaded}}\* {{end}}`{{.id}}`{{if .repo}} {{.repo}}{{end}}{{if .current}} **<-- current**{{else if .downloaded}} downloaded{{end}}{{end}}
          {{end}}
          \* = downloaded locally | `/model default <name>` to set the startup model | `/model <id>` to switch
  ps:
    subcommands:
      "":
        run:
          - tool: session_ops
            args: {operation: servers}
            print: |-
              {{if not .servers}}No local model servers running.{{else}}```
              {{printf "%-8s %-6s %-12s %-36s %s" "PID" "PORT" "BACKEND" "MODEL" "STATUS"}}
              {{range .servers}}{{printf "%-8v %-6v %-12s %-36s %s" .pid .port .backend .model .status}}
              {{end}}```{{end}}
      kill:
        run:
          - tool: session_ops
            args: {operation: server_kill, model: "$1"}
            print: "Killed server for: {{.model}}"
      switch: *switch
  hff:
    subcommands:
      search:
        run:
          - tool: hf_search
            args: {query: "$@"}
            print: |-
              ```
              {{.output}}
              ```
              Use `/model hff download <repo> <file>` to download.
      info:
        run:
          - tool: hf_repo_files
            args: {repo: "$1"}
            print: |-
              ```
              {{.output}}
              ```
              Use `/model hff download <repo> <file>` to download.
      download:
        run:
          - tool: session_ops
            args: {operation: hf_download, repo: "$1", file: "$2"}
            print: |-
              Downloaded: {{.path}}
              Registered as: {{.alias}}
              Use `/model {{.alias}}` to switch to it.
  tool:
    subcommands:
      "": &loopSettings
        run:
          - tool: session_ops
            args: {operation: loop_settings}
            print: |-
              Agent loop settings (`/model tool set <setting> <value>`):
              ```
                rounds             {{index . "rounds"}}  (max tool-call rounds per turn, 0 = unlimited)
                retries            {{index . "retries"}}  (auto-retries on transient API errors)
                retry-delay        {{index . "retry-delay"}}  (initial retry backoff, doubles per retry)
                stall-timeout      {{index . "stall-timeout"}}  (kill a tool after this much silence, set 0 to disable)
                compact-threshold  {{index . "compact-threshold"}}  (tokens; auto-compact trigger, 0 = off)
                compact-budget     {{index . "compact-budget"}}  (tokens kept after compaction)
                max-turns          {{index . "max-turns"}}  (history turns retained, 0 = unlimited)
                history-tokens     {{index . "history-tokens"}}  (history token cap, 0 = unlimited)
                web-limit          {{index . "web-limit"}}  (max web_search/web_scraper per request, 0=unlimited)
                bash-limit         {{index . "bash-limit"}}  (max bash_exec per request, 0=unlimited)
                file-limit         {{index . "file-limit"}}  (max read_file/list_files per request, 0=unlimited)
                code-limit         {{index . "code-limit"}}  (max search_local per request, 0=unlimited)
                leaf-nodes         {{index . "leaf-nodes"}}  (max memory-graph leaf entries kept in the prompt, 0 = unlimited)
                leaf-chars         {{index . "leaf-chars"}}  (max characters kept per leaf entry, 0 = unlimited)
              ```
      list: *loopSettings
      set:
        run:
          - tool: session_ops
            args: {operation: loop_set, setting: "$1", value: "$2"}
            print: "{{.setting}} set to {{.value}} (saved; applies from the next turn)"
  favorite: &favorite
    run:
      - tool: session_ops
        args: {operation: model_favorite, name: "$@", "on": "on"}
        print: "Favorited {{.name}}{{if .warning}} ({{.warning}}){{end}}"
  fav: *favorite
  star: *favorite
  unfavorite: &unfavorite
    run:
      - tool: session_ops
        args: {operation: model_favorite, name: "$@", "on": "off"}
        print: "Unfavorited {{.name}}{{if .warning}} ({{.warning}}){{end}}"
  unfav: *unfavorite
  unstar: *unfavorite
  name:
    setting:
      key: model-name
      values: [show, hide, abbreviate, auto]
      show: |-
        Model name display: {{.value}}
        Valid: {{join .values ", "}}
      set: "Model name display set to {{.value}} (saved)"
      invalid: "Unknown /model name mode: {{.arg}}. Valid: {{join .values \", \"}}"