Metadata-Version: 2.3
Name: terminal-buddy
Version: 0.1.2
Summary: A terminal assistant powered by On-Device LLM
Author: Atharva Choudhary
Author-email: atharvasteam@gmail.com
Requires-Python: >=3.12,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: annotated-types (==0.7.0)
Requires-Dist: anyio (==4.10.0)
Requires-Dist: attrs (==25.3.0)
Requires-Dist: backoff (==2.2.1)
Requires-Dist: bcrypt (==4.3.0)
Requires-Dist: build (==1.3.0)
Requires-Dist: cachecontrol (==0.14.3)
Requires-Dist: cachetools (==5.5.2)
Requires-Dist: certifi (==2025.8.3)
Requires-Dist: cffi (==1.17.1)
Requires-Dist: charset-normalizer (==3.4.3)
Requires-Dist: chromadb (==1.0.20)
Requires-Dist: cleo (==2.1.0)
Requires-Dist: click (==8.2.1)
Requires-Dist: coloredlogs (==15.0.1)
Requires-Dist: crashtest (==0.4.1)
Requires-Dist: distlib (==0.4.0)
Requires-Dist: distro (==1.9.0)
Requires-Dist: dulwich (==0.22.8)
Requires-Dist: durationpy (==0.10)
Requires-Dist: fastjsonschema (==2.21.2)
Requires-Dist: filelock (==3.19.1)
Requires-Dist: findpython (==0.6.3)
Requires-Dist: flatbuffers (==25.2.10)
Requires-Dist: fsspec (==2025.7.0)
Requires-Dist: google-auth (==2.40.3)
Requires-Dist: googleapis-common-protos (==1.70.0)
Requires-Dist: grpcio (==1.74.0)
Requires-Dist: h11 (==0.16.0)
Requires-Dist: hf-xet (==1.1.9)
Requires-Dist: httpcore (==1.0.9)
Requires-Dist: httptools (==0.6.4)
Requires-Dist: httpx (==0.28.1)
Requires-Dist: huggingface-hub (==0.34.4)
Requires-Dist: humanfriendly (==10.0)
Requires-Dist: idna (==3.10)
Requires-Dist: importlib-metadata (==8.7.0)
Requires-Dist: importlib-resources (==6.5.2)
Requires-Dist: installer (==0.7.0)
Requires-Dist: jaraco-classes (==3.4.0)
Requires-Dist: jaraco-context (==6.0.1)
Requires-Dist: jaraco-functools (==4.3.0)
Requires-Dist: jsonpatch (==1.33)
Requires-Dist: jsonpointer (==3.0.0)
Requires-Dist: jsonschema (==4.25.1)
Requires-Dist: jsonschema-specifications (==2025.4.1)
Requires-Dist: keyring (==25.6.0)
Requires-Dist: kubernetes (==33.1.0)
Requires-Dist: langchain-chroma (==0.2.5)
Requires-Dist: langchain-community (==0.3.29)
Requires-Dist: langchain-core (==0.3.75)
Requires-Dist: langchain-ollama (==0.3.7)
Requires-Dist: langsmith (==0.4.21)
Requires-Dist: markdown-it-py (==4.0.0)
Requires-Dist: mdurl (==0.1.2)
Requires-Dist: mmh3 (==5.2.0)
Requires-Dist: more-itertools (==10.7.0)
Requires-Dist: mpmath (==1.3.0)
Requires-Dist: msgpack (==1.1.1)
Requires-Dist: numpy (==2.3.2)
Requires-Dist: oauthlib (==3.3.1)
Requires-Dist: ollama (==0.5.3)
Requires-Dist: onnxruntime (==1.22.1)
Requires-Dist: opentelemetry-api (==1.36.0)
Requires-Dist: opentelemetry-exporter-otlp-proto-common (==1.36.0)
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc (==1.36.0)
Requires-Dist: opentelemetry-proto (==1.36.0)
Requires-Dist: opentelemetry-sdk (==1.36.0)
Requires-Dist: opentelemetry-semantic-conventions (==0.57b0)
Requires-Dist: orjson (==3.11.3)
Requires-Dist: overrides (==7.7.0)
Requires-Dist: packaging (==25.0)
Requires-Dist: pbs-installer (==2025.8.28)
Requires-Dist: pkginfo (==1.12.1.2)
Requires-Dist: platformdirs (==4.4.0)
Requires-Dist: poetry (==2.1.4)
Requires-Dist: poetry-core (==2.1.3)
Requires-Dist: posthog (==5.4.0)
Requires-Dist: protobuf (==6.32.0)
Requires-Dist: pyasn1 (==0.6.1)
Requires-Dist: pyasn1-modules (==0.4.2)
Requires-Dist: pybase64 (==1.4.2)
Requires-Dist: pycparser (==2.22)
Requires-Dist: pydantic (==2.11.7)
Requires-Dist: pydantic-core (==2.33.2)
Requires-Dist: pygments (==2.19.2)
Requires-Dist: pypika (==0.48.9)
Requires-Dist: pyproject-hooks (==1.2.0)
Requires-Dist: python-daemon (>=3.1.2,<4.0.0)
Requires-Dist: python-dateutil (==2.9.0.post0)
Requires-Dist: python-dotenv (==1.1.1)
Requires-Dist: pyyaml (==6.0.2)
Requires-Dist: rapidfuzz (==3.14.0)
Requires-Dist: referencing (==0.36.2)
Requires-Dist: requests (==2.32.5)
Requires-Dist: requests-oauthlib (==2.0.0)
Requires-Dist: requests-toolbelt (==1.0.0)
Requires-Dist: rich (==14.1.0)
Requires-Dist: rpds-py (==0.27.1)
Requires-Dist: rsa (==4.9.1)
Requires-Dist: shellingham (==1.5.4)
Requires-Dist: six (==1.17.0)
Requires-Dist: sniffio (==1.3.1)
Requires-Dist: sympy (==1.14.0)
Requires-Dist: tenacity (==9.1.2)
Requires-Dist: tokenizers (==0.22.0)
Requires-Dist: tomlkit (==0.13.3)
Requires-Dist: tqdm (==4.67.1)
Requires-Dist: trove-classifiers (==2025.8.26.11)
Requires-Dist: typer (==0.16.1)
Requires-Dist: typing-extensions (==4.15.0)
Requires-Dist: typing-inspection (==0.4.1)
Requires-Dist: urllib3 (==2.5.0)
Requires-Dist: uvicorn (==0.35.0)
Requires-Dist: uvloop (==0.21.0)
Requires-Dist: virtualenv (==20.32.0)
Requires-Dist: watchfiles (==1.1.0)
Requires-Dist: websocket-client (==1.8.0)
Requires-Dist: websockets (==15.0.1)
Requires-Dist: xattr (==1.2.0)
Requires-Dist: zipp (==3.23.0)
Requires-Dist: zstandard (==0.24.0)
Description-Content-Type: text/markdown

# TBuddy - Terminal Assistant Powered by On-Device LLM

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Poetry](https://img.shields.io/badge/poetry-managed-orange.svg)](https://python-poetry.org/)
[![License](https://img.shields.io/badge/license-GPL%20v3-blue.svg)](LICENSE)

TBuddy is an intelligent terminal assistant that converts natural language queries into bash commands using on-device (<1B params) Large Language Models (LLMs). It provides both a command-line interface and a daemon service for seamless terminal command generation.

## 🚀 Features

- **Natural Language to Bash Commands**: Convert plain English descriptions into executable bash commands
- **On-Device LLM Integration**: Uses Ollama with extremely small sub 1Billion parameter local models for balancing privacy, speed, memory usage and accuracy
- **Semantic Example Selection**: Leverages vector embeddings to find relevant command examples from a pre-curated list
- **Dual Operation Modes**: 
  - One-off command generation
  - Background daemon service for persistent, faster availability
- **Rich Example Database**: Comprehensive collection of text-to-command examples (available with repo)
- **Safe Command Generation**: Focuses on standard, secure and safe bash commands

## 🏗️ Architecture

### Core Components

```
terminal-buddy/
├── src/terminal_buddy/
│ ├── main.py # CLI interface and server logic
│ └── utils/
│ ├── llm_functions.py # LLM integration with Ollama
│ ├── config.py # Configuration management
│ ├── prompts.py # System prompts and templates
│ └── example_selection.py # Vector-based Example Selection
├── data/examples/
│ └── text_2_command_examples.json # Training examples (included in the repo)
└── tests/ # Test suite
```

### Key Technologies

- **Ollama**: Local LLM inference engine
- **LangChain**: Vector embeddings and example selection
- **ChromaDB**: Vector database for semantic search
- **Typer**: Modern CLI framework
- **Pydantic**: Configuration and data validation

## 📋 Prerequisites

- Python 3.12 or higher
- [Ollama](https://ollama.ai/) installed and running
- Required Ollama models:
  - `qwen3:0.6b` (for command generation)
  - `nomic-embed-text` (for embeddings)

## 🛠️ Installation

### Step 1 - Install Package

#### Using pip installer (Recommended)

```bash
pip install terminal-buddy
```

#### Using Poetry (Build Yourself)

```bash
# Clone the repository
git clone <repository-url>
cd terminal-buddy

# Install dependencies
poetry install

# Install the package
poetry install --with dev
```

### Step 2 - Setup Ollama Models
```bash
# Pull required models
ollama pull qwen3:0.6b
ollama pull nomic-embed-text
```

## 🚀 Usage

TBuddy provides a CLI with multiple commands grouped under query, server, and config.

### Query Commands
##### Generate a command directly

`tb query "list all files in current directory"`

### Server Management

```bash
# Start the server in background mode (default)
tb server up

# Start the server in foreground mode
tb server up --no-daemonize

# Stop the server
tb server down

# Check server status
tb server status
```
### Configuration Management
```
# Show current configuration
tb config show

# Update LLM model
tb config set-llm-model qwen3:0.6b

# Update embeddings model
tb config set-embeddings-model nomic-embed-text

# Update examples file path
tb config set-examples-path ./data/examples/text_2_command_examples.json
```
