Metadata-Version: 2.4
Name: kenoma
Version: 1.1.0
Summary: A fake shell powered by raw LLM completion. The model hallucinates command output until it emits the next prompt.
Author-email: a9lim <a9lim@protonmail.com>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/a9lim/kenoma
Project-URL: Source, https://github.com/a9lim/kenoma
Project-URL: Issues, https://github.com/a9lim/kenoma/issues
Project-URL: Changelog, https://github.com/a9lim/kenoma/releases
Project-URL: Documentation, https://github.com/a9lim/kenoma#readme
Keywords: llm,terminal,shell,hallucination,completion,transformers,huggingface
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Emulators
Classifier: Topic :: System :: Shells
Classifier: Topic :: Terminals
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch
Requires-Dist: transformers>=4.44
Requires-Dist: accelerate
Requires-Dist: sentencepiece
Requires-Dist: tomli>=1.1.0; python_version < "3.11"
Provides-Extra: quantize
Requires-Dist: bitsandbytes; platform_system == "Linux" and extra == "quantize"
Provides-Extra: dev
Requires-Dist: ruff>=0.6.9; extra == "dev"
Requires-Dist: pyright>=1.1.400; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# kenoma

[![CI](https://github.com/a9lim/kenoma/actions/workflows/ci.yml/badge.svg)](https://github.com/a9lim/kenoma/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/kenoma)](https://pypi.org/project/kenoma/)
[![Downloads](https://img.shields.io/pypi/dm/kenoma)](https://pypi.org/project/kenoma/)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://pypi.org/project/kenoma/)

A shell powered by LLM completion.

## Install

```
pip install kenoma
```

Or from source:

```
git clone https://github.com/a9lim/kenoma
cd kenoma
pip install -e .
```

For bitsandbytes quantization (CUDA only):

```
pip install kenoma[quantize]
```

## Usage

```
kenoma                                # defaults to Qwen/Qwen2.5-0.5B
kenoma google/gemma-3n-E4B
kenoma /path/to/local/model
```

The model argument is any HuggingFace model id or a local path. This is meant for base/completion models, instruction-tuned models may not work properly.

## Configuration

By precedence: CLI flags, then `KENOMA_*` environment variables, then a TOML config file at `$XDG_CONFIG_HOME/kenoma/config.toml` (falls back to `~/.config/kenoma/config.toml`).

Example config:

```toml
model = "google/gemma-3n-E4B"
device = "auto"
temperature = 1.0
top_p = 0.95
repetition_penalty = 1.05
max_new_tokens = 2048
context_chars = 6000
history = 20
tmux_lines = 300
quantize = "none"
kv_cache = true
compile = false
```

The env var for any key is `KENOMA_<KEY>` uppercased, so `KENOMA_MODEL=gpt2 kenoma` works.

Flags:

- `--version`: print version and exit.
- `--prompt`: override the captured `PS1`. Multi-line prompts are not supported and fall back to a constructed `user@host:cwd $ `.
- `--device {auto,cuda,mps,cpu}`: `auto` resolves to cuda, then mps, then cpu.
- `--quantize {none,4bit,8bit}`: bitsandbytes quantization. Requires CUDA and the `quantize` extra.
- `--no-kv-cache`: disable KV cache reuse across turns.
- `--compile`: `torch.compile` the model with a static KV cache for faster decode (best on CUDA). The first turn pays a compile cost; cross-turn KV cache reuse is forfeited because the static cache doesn't expose `crop()`.
- `--history N`: seed with the last N commands from shell history (0 disables).
- `--tmux-lines N`: if inside tmux, seed with the last N lines of pane scrollback (0 disables).
- `--context-chars N`: cap the rolling buffer at N chars. 
- `--max-new-tokens N`: per-turn cap on generated tokens.

**Cancelling a turn.** Ctrl-C during generation cancels the current turn, invalidates the KV cache, and redraws the prompt. Ctrl-C at the input prompt exits.

## License

AGPL-3.0-or-later. See `LICENSE`.
