terminal-sherpa 0.4.0__tar.gz

terminal_sherpa-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lucas Ford
+
+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.

terminal_sherpa-0.4.0/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: terminal-sherpa
+Version: 0.4.0
+Summary: AI-powered bash command generator
+Project-URL: Homepage, https://github.com/lcford2/terminal-sherpa
+Project-URL: Issues, https://github.com/lcford2/terminal-sherpa/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+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: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Utilities
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.7.0
+Requires-Dist: google-genai>=1.26.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: setuptools>=80.9.0
+Requires-Dist: toml>=0.10.0
+Requires-Dist: xai-sdk
+Dynamic: license-file
+
+# terminal-sherpa
+
+A lightweight AI chat interface for fellow terminal dwellers.
+
+Turn natural language into bash commands instantly.
+Stop googling syntax and start asking.
+
+[![PyPI - Version](https://img.shields.io/pypi/v/terminal-sherpa)](https://pypi.python.org/pypi/terminal-sherpa)
+[![GitHub License](https://img.shields.io/github/license/lcford2/terminal-sherpa)](https://github.com/lcford2/terminal-sherpa/blob/main/LICENSE)
+[![Python Versions](https://img.shields.io/pypi/pyversions/terminal-sherpa)](https://pypi.python.org/pypi/terminal-sherpa)
+[![Actions status](https://github.com/lcford2/terminal-sherpa/actions/workflows/main.yml/badge.svg)](https://github.com/lcford2/terminal-sherpa/actions)
+[![codecov](https://codecov.io/github/lcford2/terminal-sherpa/graph/badge.svg?token=2MXHNL3RHE)](https://codecov.io/github/lcford2/terminal-sherpa)
+
+## 🚀 Getting Started
+
+Get up and running:
+
+```bash
+# Install terminal-sherpa
+pip install terminal-sherpa # installs the `ask` CLI tool
+
+# Set your API key
+export ANTHROPIC_API_KEY="your-key-here"
+
+# Try it out
+ask "find all .py files modified in the last week"
+```
+
+**Example output:**
+
+```bash
+find . -name "*.py" -mtime -7
+```
+
+## ✨ Features
+
+- **Natural language to bash conversion** - Describe what you want, get the command
+- **Multiple AI provider support** - Choose between Anthropic (Claude), OpenAI (GPT), Google (Gemini), and xAI (Grok) models
+- **Flexible configuration system** - Set defaults, customize models, and manage API keys
+- **XDG-compliant config files** - Follows standard configuration file locations
+- **Verbose logging support** - Debug and understand what's happening under the hood
+
+## 📦 Installation
+
+### Requirements
+
+- Python 3.9+
+- API key for Anthropic, OpenAI, Google, or xAI
+
+### Install Methods
+
+**Using pip:**
+
+```bash
+pip install terminal-sherpa
+```
+
+**From source:**
+
+```bash
+git clone https://github.com/lcford2/terminal-sherpa.git
+cd terminal-sherpa
+uv sync
+uv run ask "your prompt here"
+```
+
+**Verify installation:**
+
+```bash
+ask --help
+```
+
+## 💡 Usage
+
+### Basic Syntax
+
+```bash
+ask "your natural language prompt"
+```
+
+### Command Options
+
+| Option                   | Description                | Example                                     |
+| ------------------------ | -------------------------- | ------------------------------------------- |
+| `--model provider:model` | Specify provider and model | `ask --model anthropic "list files"`        |
+|                          |                            | `ask --model anthropic:sonnet "list files"` |
+|                          |                            | `ask --model openai "list files"`           |
+|                          |                            | `ask --model gemini "list files"`           |
+|                          |                            | `ask --model gemini:pro "list files"`       |
+|                          |                            | `ask --model grok "list files"`             |
+| `--verbose`              | Enable verbose logging     | `ask --verbose "compress this folder"`      |
+
+### Practical Examples
+
+**File Operations:**
+
+```bash
+ask "find all files larger than 100MB"
+# Example output: find . -size +100M
+
+ask "create a backup of config.txt with timestamp"
+# Example output: cp config.txt config.txt.$(date +%Y%m%d_%H%M%S)
+```
+
+**Git Commands:**
+
+```bash
+ask "show git log for last 5 commits with one line each"
+# Example output: git log --oneline -5
+
+ask "delete all local branches that have been merged"
+# Example output: git branch --merged | grep -v "\*\|main\|master" | xargs -n 1 git branch -d
+```
+
+**System Administration:**
+
+```bash
+ask "check disk usage of current directory sorted by size"
+# Example output: du -sh * | sort -hr
+
+ask "find processes using port 8080"
+# Example output: lsof -i :8080
+```
+
+**Text Processing:**
+
+```bash
+ask "count lines in all Python files"
+# Example output: find . -name "*.py" -exec wc -l {} + | tail -1
+
+ask "replace all tabs with spaces in file.txt"
+# Example output: sed -i 's/\t/    /g' file.txt
+```
+
+**Network Operations:**
+
+```bash
+ask "download file from URL and save to downloads folder"
+# Example output: curl -o ~/Downloads/filename "https://example.com/file"
+
+ask "check if port 443 is open on example.com"
+# Example output: nc -zv example.com 443
+```
+
+## ⚙️ Configuration
+
+### Configuration File Locations
+
+Ask follows XDG Base Directory Specification:
+
+1. `$XDG_CONFIG_HOME/ask/config.toml`
+1. `~/.config/ask/config.toml` (if XDG_CONFIG_HOME not set)
+1. `~/.ask/config.toml` (fallback)
+
+### Environment Variables
+
+```bash
+export ANTHROPIC_API_KEY="your-anthropic-key"
+export OPENAI_API_KEY="your-openai-key"
+export GEMINI_API_KEY="your-gemini-key"
+export XAI_API_KEY="your-xai-key"
+```
+
+### Example Configuration File
+
+Create `~/.config/ask/config.toml`:
+
+```toml
+[ask]
+default_model = "anthropic"
+
+[anthropic]
+model = "claude-3-haiku-20240307"
+max_tokens = 512
+
+[anthropic.sonnet]
+model = "claude-sonnet-4-20250514"
+max_tokens = 1024
+
+[openai]
+model = "gpt-4o"
+max_tokens = 1024
+
+[gemini]
+model = "gemini-2.5-flash-lite-preview-06-17"
+max_tokens = 150
+
+[gemini.pro]
+model = "gemini-2.5-pro"
+max_tokens = 1024
+
+[grok]
+model = "grok-3-fast"
+max_tokens = 150
+temperature = 0.0
+```
+
+## 🤖 Supported Providers
+
+- Anthropic (Claude)
+- OpenAI (GPT)
+- Google (Gemini)
+- xAI (Grok)
+
+> **Note:** Get API keys from [Anthropic Console](https://console.anthropic.com/), [OpenAI Platform](https://platform.openai.com/), [Google AI Studio](https://aistudio.google.com/), or [xAI Console](https://x.ai/console)
+
+## 🛣️ Roadmap
+
+- [ ] Shell integration and auto-completion
+- [ ] Additional providers (Cohere, Mistral)
+- [ ] Local model support (Ollama, llama.cpp)
+
+## 🔧 Development
+
+### Setup
+
+```bash
+git clone https://github.com/lcford2/terminal-sherpa.git
+cd ask
+uv sync --all-groups
+uv run pre-commit install
+```
+
+### Testing
+
+```bash
+uv run python -m pytest
+```
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run pre-commit checks: `uv run pre-commit run --all-files`
+5. Run tests: `uv run task test`
+6. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Issues
+
+Found a bug or have a feature request? Please open an issue on [GitHub Issues](https://github.com/lcford2/ask/issues).

terminal_sherpa-0.4.0/README.md

@@ -0,0 +1,245 @@
+# terminal-sherpa
+
+A lightweight AI chat interface for fellow terminal dwellers.
+
+Turn natural language into bash commands instantly.
+Stop googling syntax and start asking.
+
+[![PyPI - Version](https://img.shields.io/pypi/v/terminal-sherpa)](https://pypi.python.org/pypi/terminal-sherpa)
+[![GitHub License](https://img.shields.io/github/license/lcford2/terminal-sherpa)](https://github.com/lcford2/terminal-sherpa/blob/main/LICENSE)
+[![Python Versions](https://img.shields.io/pypi/pyversions/terminal-sherpa)](https://pypi.python.org/pypi/terminal-sherpa)
+[![Actions status](https://github.com/lcford2/terminal-sherpa/actions/workflows/main.yml/badge.svg)](https://github.com/lcford2/terminal-sherpa/actions)
+[![codecov](https://codecov.io/github/lcford2/terminal-sherpa/graph/badge.svg?token=2MXHNL3RHE)](https://codecov.io/github/lcford2/terminal-sherpa)
+
+## 🚀 Getting Started
+
+Get up and running:
+
+```bash
+# Install terminal-sherpa
+pip install terminal-sherpa # installs the `ask` CLI tool
+
+# Set your API key
+export ANTHROPIC_API_KEY="your-key-here"
+
+# Try it out
+ask "find all .py files modified in the last week"
+```
+
+**Example output:**
+
+```bash
+find . -name "*.py" -mtime -7
+```
+
+## ✨ Features
+
+- **Natural language to bash conversion** - Describe what you want, get the command
+- **Multiple AI provider support** - Choose between Anthropic (Claude), OpenAI (GPT), Google (Gemini), and xAI (Grok) models
+- **Flexible configuration system** - Set defaults, customize models, and manage API keys
+- **XDG-compliant config files** - Follows standard configuration file locations
+- **Verbose logging support** - Debug and understand what's happening under the hood
+
+## 📦 Installation
+
+### Requirements
+
+- Python 3.9+
+- API key for Anthropic, OpenAI, Google, or xAI
+
+### Install Methods
+
+**Using pip:**
+
+```bash
+pip install terminal-sherpa
+```
+
+**From source:**
+
+```bash
+git clone https://github.com/lcford2/terminal-sherpa.git
+cd terminal-sherpa
+uv sync
+uv run ask "your prompt here"
+```
+
+**Verify installation:**
+
+```bash
+ask --help
+```
+
+## 💡 Usage
+
+### Basic Syntax
+
+```bash
+ask "your natural language prompt"
+```
+
+### Command Options
+
+| Option                   | Description                | Example                                     |
+| ------------------------ | -------------------------- | ------------------------------------------- |
+| `--model provider:model` | Specify provider and model | `ask --model anthropic "list files"`        |
+|                          |                            | `ask --model anthropic:sonnet "list files"` |
+|                          |                            | `ask --model openai "list files"`           |
+|                          |                            | `ask --model gemini "list files"`           |
+|                          |                            | `ask --model gemini:pro "list files"`       |
+|                          |                            | `ask --model grok "list files"`             |
+| `--verbose`              | Enable verbose logging     | `ask --verbose "compress this folder"`      |
+
+### Practical Examples
+
+**File Operations:**
+
+```bash
+ask "find all files larger than 100MB"
+# Example output: find . -size +100M
+
+ask "create a backup of config.txt with timestamp"
+# Example output: cp config.txt config.txt.$(date +%Y%m%d_%H%M%S)
+```
+
+**Git Commands:**
+
+```bash
+ask "show git log for last 5 commits with one line each"
+# Example output: git log --oneline -5
+
+ask "delete all local branches that have been merged"
+# Example output: git branch --merged | grep -v "\*\|main\|master" | xargs -n 1 git branch -d
+```
+
+**System Administration:**
+
+```bash
+ask "check disk usage of current directory sorted by size"
+# Example output: du -sh * | sort -hr
+
+ask "find processes using port 8080"
+# Example output: lsof -i :8080
+```
+
+**Text Processing:**
+
+```bash
+ask "count lines in all Python files"
+# Example output: find . -name "*.py" -exec wc -l {} + | tail -1
+
+ask "replace all tabs with spaces in file.txt"
+# Example output: sed -i 's/\t/    /g' file.txt
+```
+
+**Network Operations:**
+
+```bash
+ask "download file from URL and save to downloads folder"
+# Example output: curl -o ~/Downloads/filename "https://example.com/file"
+
+ask "check if port 443 is open on example.com"
+# Example output: nc -zv example.com 443
+```
+
+## ⚙️ Configuration
+
+### Configuration File Locations
+
+Ask follows XDG Base Directory Specification:
+
+1. `$XDG_CONFIG_HOME/ask/config.toml`
+1. `~/.config/ask/config.toml` (if XDG_CONFIG_HOME not set)
+1. `~/.ask/config.toml` (fallback)
+
+### Environment Variables
+
+```bash
+export ANTHROPIC_API_KEY="your-anthropic-key"
+export OPENAI_API_KEY="your-openai-key"
+export GEMINI_API_KEY="your-gemini-key"
+export XAI_API_KEY="your-xai-key"
+```
+
+### Example Configuration File
+
+Create `~/.config/ask/config.toml`:
+
+```toml
+[ask]
+default_model = "anthropic"
+
+[anthropic]
+model = "claude-3-haiku-20240307"
+max_tokens = 512
+
+[anthropic.sonnet]
+model = "claude-sonnet-4-20250514"
+max_tokens = 1024
+
+[openai]
+model = "gpt-4o"
+max_tokens = 1024
+
+[gemini]
+model = "gemini-2.5-flash-lite-preview-06-17"
+max_tokens = 150
+
+[gemini.pro]
+model = "gemini-2.5-pro"
+max_tokens = 1024
+
+[grok]
+model = "grok-3-fast"
+max_tokens = 150
+temperature = 0.0
+```
+
+## 🤖 Supported Providers
+
+- Anthropic (Claude)
+- OpenAI (GPT)
+- Google (Gemini)
+- xAI (Grok)
+
+> **Note:** Get API keys from [Anthropic Console](https://console.anthropic.com/), [OpenAI Platform](https://platform.openai.com/), [Google AI Studio](https://aistudio.google.com/), or [xAI Console](https://x.ai/console)
+
+## 🛣️ Roadmap
+
+- [ ] Shell integration and auto-completion
+- [ ] Additional providers (Cohere, Mistral)
+- [ ] Local model support (Ollama, llama.cpp)
+
+## 🔧 Development
+
+### Setup
+
+```bash
+git clone https://github.com/lcford2/terminal-sherpa.git
+cd ask
+uv sync --all-groups
+uv run pre-commit install
+```
+
+### Testing
+
+```bash
+uv run python -m pytest
+```
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run pre-commit checks: `uv run pre-commit run --all-files`
+5. Run tests: `uv run task test`
+6. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Issues
+
+Found a bug or have a feature request? Please open an issue on [GitHub Issues](https://github.com/lcford2/ask/issues).

terminal_sherpa-0.4.0/ask/config.py

@@ -0,0 +1,94 @@
+"""Configuration loading and management module."""
+
+import os
+from pathlib import Path
+from typing import Any
+
+import toml
+
+from ask.exceptions import ConfigurationError
+
+SYSTEM_PROMPT = (
+    "You are a bash command generator. Given a user request, "
+    "respond with ONLY the bash command that accomplishes the task. "
+    "Do not include explanations, comments, or any other text. "
+    "Just the command.",
+)
+
+
+def get_config_path() -> Path | None:
+    """Find config file using XDG standard."""
+    # Primary location: $XDG_CONFIG_HOME/ask/config.toml
+    xdg_config_home = os.environ.get("XDG_CONFIG_HOME")
+    if xdg_config_home:
+        primary_path = Path(xdg_config_home) / "ask" / "config.toml"
+    else:
+        primary_path = Path.home() / ".config" / "ask" / "config.toml"
+
+    if primary_path.exists():
+        return primary_path
+
+    # Fallback location: ~/.ask/config.toml
+    fallback_path = Path.home() / ".ask" / "config.toml"
+    if fallback_path.exists():
+        return fallback_path
+
+    return None
+
+
+def load_config() -> dict[str, Any]:
+    """Load configuration from TOML file."""
+    config_path = get_config_path()
+
+    if config_path is None:
+        return {}
+
+    try:
+        with open(config_path) as f:
+            return toml.load(f)
+    except Exception as e:
+        raise ConfigurationError(f"Failed to load config file {config_path}: {e}")
+
+
+def get_provider_config(
+    config: dict[str, Any], provider_spec: str
+) -> tuple[str, dict[str, Any]]:
+    """Parse provider:model syntax and return provider name and config."""
+    if ":" in provider_spec:
+        provider_name, model_name = provider_spec.split(":", 1)
+
+        # First try to get nested config (e.g., anthropic.haiku)
+        provider_section = config.get(provider_name, {})
+        if isinstance(provider_section, dict) and model_name in provider_section:
+            provider_config = provider_section[model_name]
+        else:
+            # Fall back to base provider config
+            provider_config = provider_section
+    else:
+        provider_name = provider_spec
+        provider_config = config.get(provider_name, {})
+
+    # Add global settings
+    global_config = config.get("ask", {})
+
+    # Merge global and provider-specific config
+    merged_config = {**global_config, **provider_config}
+
+    return provider_name, merged_config
+
+
+def get_default_model(config: dict[str, Any]) -> str | None:
+    """Get default model from configuration."""
+    global_config = config.get("ask", {})
+    return global_config.get("default_model")
+
+
+def get_default_provider() -> str | None:
+    """Determine fallback provider from environment variables."""
+    # Check for API keys in order of preference: claude -> openai
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        return "anthropic"
+    elif os.environ.get("OPENAI_API_KEY"):
+        return "openai"
+
+    return None

terminal_sherpa-0.4.0/ask/exceptions.py

@@ -0,0 +1,25 @@
+"""Custom exception classes for the ask CLI tool."""
+
+
+class ConfigurationError(Exception):
+    """Raised when there are configuration-related errors."""
+
+    pass
+
+
+class AuthenticationError(Exception):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class APIError(Exception):
+    """Raised when API requests fail."""
+
+    pass
+
+
+class RateLimitError(APIError):
+    """Raised when API rate limits are exceeded."""
+
+    pass