Metadata-Version: 2.3
Name: terminal-buddy
Version: 0.1.1
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 per request)
- **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 retrieval
│       └── examples.json        # Command examples database
├── data/examples/
│   └── text_2_command_examples.json  # Training examples (not included in the repo, but this is where you'd place your own)
└── 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

### Using Poetry (Recommended)

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

# Install dependencies
poetry install

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

### Using pip

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

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .
```

### Setup Ollama Models

```bash
# Pull required models
ollama pull qwen3:0.6b
ollama pull nomic-embed-text
```

## 🚀 Usage

### Command Line Interface

TBuddy provides a simple CLI for generating commands:

```bash
# Basic usage
tb "list all files in current directory"

# Using the full command
tb query "show me disk usage"

# Start background service
tb serve
```

### Examples

```bash
# File operations
tb "create a new directory called projects"
# Output: mkdir projects

tb "list all hidden files"
# Output: ls -a

# System information
tb "check disk space"
# Output: df -h

tb "show running processes"
# Output: ps aux

# Text processing
tb "find all .txt files"
# Output: find . -name "*.txt"

tb "search for 'error' in log files"
# Output: grep -r "error" *.log
```

### Daemon Mode

For persistent availability, run TBuddy as a background service:

```bash
# Start the daemon
tb serve

# In another terminal, send queries
tb "check memory usage"
```

The daemon runs on `127.0.0.1:65432` and automatically handles multiple concurrent requests.

## ⚙️ Configuration

Configuration is managed through the `Config` class in `src/terminal_buddy/utils/config.py`:

```python
class Config(BaseModel):
    OLLAMA_MODEL_NAME: str = Field(default="qwen3:0.6b")
    OLLAMA_EMBEDDINGS_MODEL_NAME: str = Field(default="nomic-embed-text")
    EXAMPLES_JSON_PATH: str = Field(default="path/to/examples.json")
```

## 🔧 Development

### Project Structure

- **`main.py`**: Entry point with CLI commands and server logic
- **`utils/llm_functions.py`**: Core LLM integration using Ollama
- **`utils/example_selection.py`**: Vector-based example retrieval using LangChain
- **`utils/prompts.py`**: System prompts for command generation
- **`data/examples/`**: Training data with text-to-command mappings

### Adding New Examples

To improve command generation, add new examples to `data/examples/text_2_command_examples.json`:

```json
{
    "user_query": "Your natural language description",
    "command": "corresponding bash command"
}
```

### Running Tests

```bash
# Run tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=terminal_buddy
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Guidelines

- Follow PEP 8 style guidelines
- Add tests for new features
- Update documentation for API changes
- Use type hints for all functions

## 📊 Performance

- **Response Time**: ~1-3 seconds for command generation
- **Memory Usage**: ~2-4GB RAM (depending on model size)
- **Accuracy**: High accuracy for common terminal operations
- **Safety**: Focuses on standard, safe bash commands

## 🔒 Security

- **Local Processing**: All LLM operations run locally via Ollama
- **No Data Transmission**: No queries or responses are sent to external services
- **Safe Commands**: System prompts emphasize safe, standard bash commands
- **Input Validation**: All inputs are validated before processing

## 📝 License

This project is licensed under the GNU General Public License v3 - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Ollama](https://ollama.ai/) for local LLM inference
- [LangChain](https://langchain.com/) for vector operations and example selection
- [Typer](https://typer.tiangolo.com/) for the CLI framework
- [Pydantic](https://pydantic.dev/) for data validation

## 📞 Support

For questions, issues, or contributions:

- Open an issue on GitHub
- Check the [documentation](docs/)
- Review existing examples in `data/examples/`

---

**Made with ❤️ for the terminal community**

