Metadata-Version: 2.4
Name: cmdrun
Version: 0.1.0
Summary: A CLI tool to register and retrieve terminal commands using natural language and semantic search
Project-URL: Homepage, https://github.com/your-username/cmdrun
Project-URL: Repository, https://github.com/your-username/cmdrun
Project-URL: Issues, https://github.com/your-username/cmdrun/issues
Project-URL: Changelog, https://github.com/your-username/cmdrun/releases
Author: cmdrun contributors
License: MIT License
        
        Copyright (c) 2025 cmdrun contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cli,commands,embeddings,nlp,semantic-search,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: faiss-cpu>=1.8.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# cmdrun

Remember terminal commands using natural language and semantic search — entirely offline.

```
cmdrun "show all pods"

╭─ Best match ────────────────────────────────╮
│ kubectl get pods -A                          │
╰─ similarity 0.87 ───────────────────────────╯
```

---

## Table of contents

- [Installation](#installation)
- [Quick start](#quick-start)
- [Commands](#commands)
- [Architecture](#architecture)
- [Configuration](#configuration)
- [Development](#development)

---

## Installation

```bash
pip install cmdrun
```

Requires Python 3.9+.  All data is stored locally under `~/.cmdrun/` — nothing leaves your machine.

---

## Quick start

### 1. Register a command

```
$ cmdrun register

Register a new command

  Description: list all kubernetes pods
  Command: kubectl get pods -A

✓ Registered: 'list all kubernetes pods' → kubectl get pods -A
```

### 2. Retrieve it with natural language

```
$ cmdrun "show pods"

╭─ Best match ────────────────────────────────╮
│ kubectl get pods -A                          │
╰─ similarity 0.87 ───────────────────────────╯
```

### 3. Run it immediately

```
$ cmdrun --run "show pods"

Running: kubectl get pods -A

NAME           READY  STATUS   RESTARTS  AGE
...
```

---

## Commands

| Command | Description |
|---|---|
| `cmdrun register` | Interactively register a new description → command mapping |
| `cmdrun "query"` | Retrieve the best-matching command for a natural language query |
| `cmdrun --run "query"` | Retrieve **and execute** the best-matching command |
| `cmdrun list` | Show all registered commands in a table |
| `cmdrun remove` | Remove a registered command by list index |
| `cmdrun rebuild` | Rebuild the FAISS index from `commands.json` |

### Options

| Flag | Description |
|---|---|
| `--run` / `-r` | Execute the matched command after displaying it |
| `--verbose` / `-v` | Enable debug-level logging |

---

## Architecture

```
cmdrun "show all pods"
        │
        ▼
   cli.py  (Typer + Rich)
        │
        ▼
  embeddings.py  — sentence-transformers/all-MiniLM-L6-v2 (384d, lazy-loaded)
        │
        ▼
  vector_store.py  — FAISS IndexFlatIP (cosine similarity via normalised vectors)
        │
        ▼
   matcher.py  — top-k search, threshold filtering, MatchResponse
        │
        ▼
  storage.py  — commands.json  (source of truth, Pydantic models)
```

### Data files

All data lives in `~/.cmdrun/`:

| File | Purpose |
|---|---|
| `commands.json` | Human-readable list of description → command pairs |
| `index.faiss` | FAISS binary index (vector search) |
| `metadata.pkl` | Maps FAISS vector positions back to CommandEntry objects |

### Similarity search

1. Query text is embedded with `all-MiniLM-L6-v2` (384 dimensions, L2-normalised).
2. FAISS `IndexFlatIP` performs an inner-product search (≡ cosine similarity for unit vectors).
3. The top-*k* (default 3) candidates are returned.
4. If the best candidate's similarity is below **0.60** the tool reports "No command found".

---

## Configuration

The following constants in `cmdrun/config.py` can be adjusted:

| Constant | Default | Description |
|---|---|---|
| `SIMILARITY_THRESHOLD` | `0.60` | Minimum cosine similarity to accept a match |
| `TOP_K` | `3` | Number of candidates to surface |
| `EMBEDDING_MODEL` | `sentence-transformers/all-MiniLM-L6-v2` | HuggingFace model ID |

---

## Development

```bash
# Clone / enter the project
cd cmdrun

# Install in editable mode with dev extras
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=cmdrun --cov-report=term-missing

# Lint
ruff check cmdrun tests

# Type-check
mypy cmdrun
```

### Project layout

```
cmdrun/
├── __init__.py       Package metadata
├── cli.py            Typer app — all user-facing commands
├── config.py         Paths, model name, thresholds
├── storage.py        commands.json read/write (Pydantic models)
├── embeddings.py     Lazy-loaded sentence-transformers wrapper
├── vector_store.py   FAISS index management
└── matcher.py        High-level matching pipeline

tests/
└── test_matcher.py   pytest suite (embeddings, vector store, matcher, storage)

data/
└── commands.json     Seed/example data (empty by default)

pyproject.toml
README.md
```

---

## Examples

### Register a handful of commands

```
cmdrun register
  Description: list all kubernetes pods across namespaces
  Command: kubectl get pods -A

cmdrun register
  Description: list running docker containers
  Command: docker ps

cmdrun register
  Description: show disk usage human readable
  Command: df -h

cmdrun register
  Description: find large files in current directory
  Command: find . -type f -size +100M

cmdrun register
  Description: tail application logs
  Command: tail -f /var/log/app.log
```

### Query examples

```bash
cmdrun "pods in kubernetes"
cmdrun "docker running"
cmdrun "how much disk space"
cmdrun "big files"
cmdrun "follow logs"
```

### Execute directly

```bash
cmdrun --run "show disk usage"
```

### Manage your catalogue

```bash
cmdrun list      # view all entries with their index numbers
cmdrun remove    # choose an entry to delete by number
cmdrun rebuild   # re-sync index after manually editing commands.json
```

---

## Performance

| Operation | Typical latency |
|---|---|
| Cold start (first query, model load) | ~1–2 s |
| Subsequent queries (model cached) | < 50 ms |
| Index rebuild (100 entries) | ~2 s |

---

## License

MIT
