Metadata-Version: 2.4
Name: nock-cli
Version: 0.2.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).

## 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).
