Metadata-Version: 2.4
Name: nock-cli
Version: 0.6.0
Summary: Open models that live on your machine: code, video and a coding agent, offline.
Author: NockAI
License-Expression: Apache-2.0
Project-URL: Homepage, https://nockai.dev
Project-URL: Model, https://huggingface.co/Nock-AI/nock-video-4b-GGUF
Keywords: local,offline,llm,video,llama.cpp,gguf
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: links
Requires-Dist: yt-dlp; extra == "links"
Dynamic: license-file

# Nock CLI

Open models that live on your machine. One tool for the NockAI family: code, video, and a coding agent, offline.

```bash
nock add coder video
nock code "regex for an EVM address"
nock video find meeting.mp4 "when do they talk about the budget"
nock fix ./my-project "the total is off by one"     # experimental, big GPU
```

Everything runs on your computer. The models run in a local llama.cpp server on `127.0.0.1`. Nothing is uploaded.

## Install

You need Python 3.9 or newer.

```bash
pipx install nock-cli
nock add coder        # or: video, agent
nock doctor
```

`nock add` downloads, once:
- the engine: an official [llama.cpp](https://github.com/ggml-org/llama.cpp) build (about 35 MB; Vulkan on Windows
  and Linux, Metal on Apple Silicon). Already have `llama-server`? Nock uses it.
- the skill's model from Hugging Face.

| Skill | Model | Download | Needs |
|---|---|---|---|
| `coder` | [Nock Coder 1.5B](https://huggingface.co/Nock-AI/nock-coder-1.5b-GGUF) | 1 GB | any laptop |
| `video` | [Nock Video 4B](https://huggingface.co/Nock-AI/nock-video-4b-GGUF) (preview) | 3.4 GB | a GPU with 6 GB for 64 frames; [ffmpeg](https://ffmpeg.org/download.html) |
| `agent` | [Nock Agent 31B](https://huggingface.co/Nock-AI/nock-agent-31b-GGUF) (experimental) | 18.7 GB | a GPU with about 20 GB (a Mac with 32 GB or more may work; not tested) |

`nock list` shows what is installed, `nock remove <skill>` deletes a skill's files. Files go to `~/.nock`
(set `NOCK_HOME` to use another folder).

## Nock Coder: `nock code`

```bash
nock code "write a Solidity ERC-20 with a cap"
cat error.log | nock code "why does this fail?"
nock code                                  # a chat; type exit to quit
```

Code first, one short line of explanation. The same model and prompt as `ollama run nockai/nock-coder`. It is a
1.5B model, so review code before you run it. On HumanEval it passes 118 of 164.

## Nock Video: `nock video`

```bash
nock video summarize meeting.mp4
nock video ask clip.mp4 "what error message shows on screen?"
nock video find clip.mp4 "when the cake comes out"
```

Files or links. Links are downloaded to your own machine with [yt-dlp](https://github.com/yt-dlp/yt-dlp), which
you install yourself (`pipx inject nock-cli yt-dlp`). Only use videos you have the right to use.

Nock Video 4B is a **preview**. On our test of 20 videos, through llama.cpp at 64 frames, it found the moment in
43 of 56 questions, answered 59 of 60 questions about what is on screen, and gave 6 of 7 good summaries. Full
results, including the misses, are on the [model card](https://huggingface.co/Nock-AI/nock-video-4b-GGUF).

- It reads frames only, not sound.
- A long video is read as at most 64 frames, so short events in long videos can be missed.
- 64 frames used about 5.5 GB of GPU memory in our test. On GPUs under 6 GB, Nock uses 32 frames (the first
  preview dropped from 42 to 35 of 56 moments at 32 frames; the current model was not measured at 32).
  `--frames` overrides it.

## Nock Agent: `nock fix` (experimental)

```bash
nock fix ./my-project "the total is off by one"
```

Nock Agent reads the code, makes the smallest edit and runs the tests. On our agent test it solved 145 of 150 runs
and edited a test file 0 times. It works on your own files, so **every edit is shown as a diff and every command
before it runs, and each one needs your yes**. `--yes` skips the questions; use it only in a copy or a git branch.
It refuses to start on GPUs under about 20 GB (`--force` to try anyway, very slowly).

## Nock Hub: open models from other builders

```bash
nock hub                                   # what you can add
nock add index-translate-2b
nock ask index-translate-2b "Never share your seed phrase." --to Spanish
nock ask index-translate-2b "Send it to your wallet address." --to Japanese --glossary terms.txt
nock add minicpm-ocr
nock ask minicpm-ocr scan.png
```

Nock Hub lists small open models made by other people, each with the test we ran on it, misses included. Listed
models are not made by NockAI. Only Apache-2.0 and MIT models are listed; each is pinned to an exact revision and runs
from its model files only, nothing from its author runs on your machine. The list lives at
`https://nockai.dev/hub/models-v2.json` and is saved locally, so installed models work offline. `nock serve` also serves
Hub models under their own id.

A glossary keeps your terms consistent. Write one pair per line in a text file (`wallet address = ウォレットアドレス`);
nock passes only the terms that appear in your text. In our test it raised Index-Translate from 81% to 98% of terms
translated the agreed way. Models whose listing shows `--glossary` support it.

## Use it from your apps: `nock serve`

```bash
nock serve
```

One local, OpenAI-compatible address for every skill you have installed. In your editor or tool, set the base URL to
`http://127.0.0.1:8080/v1`, any API key, and the model to `nock-coder`, `nock-video` or `nock-agent`.

```bash
curl http://127.0.0.1:8080/v1/chat/completions -H "Content-Type: application/json"   -d '{"model": "nock-coder", "messages": [{"role": "user", "content": "regex for an EVM address"}]}'
```

The model starts on first use, and one model is in memory at a time, so asking for another swaps them (it can take
a while). Streaming works. It listens on this machine only, refuses requests from websites, and logs no questions or
answers. `--port` changes the port.

## Speed and GPUs

`nock doctor` shows which device the engine uses. If it says **software device** or **no GPU device**, the
engine runs on the CPU and answers take many minutes. This happens inside most containers and VMs. On a machine
with an NVIDIA GPU, `nock setup --backend cuda` installs the CUDA build instead (a bigger download: about 630 MB on Windows, 740 MB on Linux).

| Option | Meaning |
|---|---|
| `--backend vulkan\|cuda\|cpu\|metal` | which llama.cpp build `nock add` / `nock setup` installs |
| `NOCK_LLAMA_SERVER=/path/llama-server` | use your own llama.cpp build |
| `NOCK_HOME=/path` | where models and the engine are stored |

Server logs are in `~/.nock/logs/` if something goes wrong.

## License

Apache-2.0. Each model has its own license on its model card (all Apache-2.0).
