terminal-sherpa 0.1.0__py3-none-any.whl

terminal_sherpa-0.1.0.dist-info/METADATA

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: terminal-sherpa
+Version: 0.1.0
+Summary: AI-powered bash command generator
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic>=0.7.0
+Requires-Dist: black>=25.1.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pytest>=8.0.0
+Requires-Dist: pytest-cov>=4.0.0
+Requires-Dist: pytest-mock>=3.12.0
+Requires-Dist: ruff>=0.12.3
+Requires-Dist: toml>=0.10.0
+
+# ask
+
+A lightweight AI chat interface for fellow terminal dwellers.
+
+Turn natural language into bash commands instantly.
+Stop googling syntax and start asking.
+
+[![codecov](https://codecov.io/github/lcford2/ask/graph/badge.svg?token=2MXHNL3RHE)](https://codecov.io/github/lcford2/ask)
+
+## 🚀 Getting Started
+
+Get up and running:
+
+```bash
+# Install ask
+uv tool install ask
+
+# 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) and OpenAI (GPT) 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.13+
+- API key for Anthropic or OpenAI
+
+### Install Methods
+
+**Recommended (uv):**
+```bash
+uv tool install ask
+```
+
+**Using pip:**
+```bash
+pip install ask
+```
+
+**From source:**
+```bash
+git clone https://github.com/lcford2/ask.git
+cd ask
+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:claude-3-haiku "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"
+```
+
+### Example Configuration File
+Create `~/.config/ask/config.toml`:
+
+```toml
+[ask]
+default_model = "anthropic"
+
+[anthropic]
+api_key = "your-anthropic-key"
+model = "claude-3-haiku-20240307"
+max_tokens = 512
+
+[anthropic.sonnet]
+model = "claude-3-5-sonnet-20241022"
+max_tokens = 1024
+
+[openai]
+api_key = "your-openai-key"
+model = "gpt-4o"
+max_tokens = 1024
+```
+
+## 🤖 Supported Providers
+
+- Anthropic (Claude)
+- OpenAI (GPT)
+
+> **Note:** Get API keys from [Anthropic Console](https://console.anthropic.com/) or [OpenAI Platform](https://platform.openai.com/)
+
+## 🛣️ Roadmap
+
+### Near-term
+- [ ] Shell integration and auto-completion
+- [ ] Command history and favorites
+- [ ] Safety features (command preview/confirmation)
+- [ ] Output formatting options
+
+### Medium-term
+- [ ] Additional providers (Google, Cohere, Mistral)
+- [ ] Interactive mode for complex tasks
+- [ ] Plugin system for custom providers
+- [ ] Command validation and testing
+
+### Long-term
+- [ ] Local model support (Ollama, llama.cpp)
+- [ ] Learning from user preferences
+- [ ] Advanced safety and sandboxing
+- [ ] GUI and web interface options
+
+## 🔧 Development
+
+### Setup
+```bash
+git clone https://github.com/lcford2/ask.git
+cd ask
+uv sync
+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. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please see our [Contributing Guidelines](CONTRIBUTING.md) 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.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+ask/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ask/config.py,sha256=iHIiMKePia80Sno_XlARqa7pEyW3eZm_Bf5SlUMidiQ,2880
+ask/exceptions.py,sha256=0RLMSbw6j49BEhJN7C8MYaKpuhVeitsBhTGjZmaiHis,434
+ask/main.py,sha256=SJ084NXNvd-pO2hY8oFO__NFR1F07YxeOacBuv65crc,3867
+ask/providers/__init__.py,sha256=IINO0hNGarFpf62lCuVtIqMeAOC1CtR_wDWUL6_iWzI,1105
+ask/providers/anthropic.py,sha256=ZFlnQZaxPGHLYjAacapE-63LoSu43xYnZ30Ajmrmgw0,2703
+ask/providers/base.py,sha256=91ZbVORYWckSHNwNPiTmgfqQN0FLO9AgV6mptuAkIU0,769
+ask/providers/openai.py,sha256=R-UgVArtlpn8F4qkliQ7unNk11ekTPL0hFZCfubGYpg,3661
+test/conftest.py,sha256=V9ebLC-soz0hHocZLZAibzsVdvzZh4-elcTtKmZ2FyA,1363
+test/test_anthropic.py,sha256=S5OQ67qIZ4VO38eJwAAwJa4JBylJhKCtmcGjCWA8WLY,5687
+test/test_config.py,sha256=FrJ6bsZ6mK46e-8fQfkFGx9GgwHrNfnoI8211R0V9K8,5565
+test/test_exceptions.py,sha256=tw-spMitAdYj9uW_8TjnlyVKKXFC06FR3610WGR-494,1754
+test/test_main.py,sha256=3gZ83nVHMSEmgHSF2UJoELfK028a4vgxLpIk2P1cH1Y,7745
+test/test_openai.py,sha256=3dDwlxnKGwl5aJcKHyNgrwrciJBZ96a51fHuxr-V8FA,8633
+test/test_providers.py,sha256=SejQvCZSEQ5RAfVTCtPZ-39fXnfV17n4gaSxjiHA5UM,2140
+terminal_sherpa-0.1.0.dist-info/METADATA,sha256=hh4NTZNv3yisUjLUcsJxlOBHUiK70l0u82CQIxJrjJI,5610
+terminal_sherpa-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+terminal_sherpa-0.1.0.dist-info/entry_points.txt,sha256=LxG9-J__nMGmeEIi47WVGYC1LLJo1GaADH21hfxEK70,38
+terminal_sherpa-0.1.0.dist-info/top_level.txt,sha256=Y7k5b2NSCkKiA_XPU-4fT_GYangD6JVDug5xwfXvmuQ,9
+terminal_sherpa-0.1.0.dist-info/RECORD,,

terminal_sherpa-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

terminal_sherpa-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ask = ask.main:main

terminal_sherpa-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+ask
+test

test/conftest.py

@@ -0,0 +1,58 @@
+"""Pytest configuration and fixtures."""
+
+import os
+import tempfile
+from collections.abc import Generator
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+
+@pytest.fixture
+def temp_config_dir() -> Generator[Path, None, None]:
+    """Create a temporary directory for config files."""
+    with tempfile.TemporaryDirectory() as temp_dir:
+        yield Path(temp_dir)
+
+
+@pytest.fixture
+def test_resources_dir() -> Path:
+    """Return path to test resources directory."""
+    return Path(__file__).parent / "test_resources"
+
+
+@pytest.fixture
+def mock_env_vars():
+    """Mock environment variables for testing."""
+    with patch.dict(os.environ, {}, clear=True):
+        yield
+
+
+@pytest.fixture
+def mock_anthropic_key():
+    """Mock Anthropic API key in environment."""
+    with patch.dict(
+        os.environ, {"ANTHROPIC_API_KEY": "test-anthropic-key"}, clear=True
+    ):
+        yield
+
+
+@pytest.fixture
+def mock_openai_key():
+    """Mock OpenAI API key in environment."""
+    with patch.dict(os.environ, {"OPENAI_API_KEY": "test-openai-key"}, clear=True):
+        yield
+
+
+@pytest.fixture
+def mock_both_keys():
+    """Mock both API keys in environment."""
+    with patch.dict(
+        os.environ,
+        {
+            "ANTHROPIC_API_KEY": "test-anthropic-key",
+            "OPENAI_API_KEY": "test-openai-key",
+        },
+    ):
+        yield

test/test_anthropic.py

@@ -0,0 +1,173 @@
+"""Tests for Anthropic provider."""
+
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from ask.config import SYSTEM_PROMPT
+from ask.exceptions import APIError, AuthenticationError, RateLimitError
+from ask.providers.anthropic import AnthropicProvider
+
+
+def test_anthropic_provider_init():
+    """Test provider initialization."""
+    config = {"model_name": "claude-3-haiku-20240307"}
+    provider = AnthropicProvider(config)
+
+    assert provider.config == config
+    assert provider.client is None
+
+
+def test_validate_config_success(mock_anthropic_key):
+    """Test successful config validation."""
+    config = {"api_key_env": "ANTHROPIC_API_KEY"}
+    provider = AnthropicProvider(config)
+
+    with patch("anthropic.Anthropic") as mock_anthropic:
+        mock_client = MagicMock()
+        mock_anthropic.return_value = mock_client
+
+        provider.validate_config()
+
+        assert provider.client == mock_client
+        mock_anthropic.assert_called_once_with(api_key="test-anthropic-key")
+
+
+def test_validate_config_missing_key(mock_env_vars):
+    """Test missing API key error."""
+    config = {"api_key_env": "ANTHROPIC_API_KEY"}
+    provider = AnthropicProvider(config)
+
+    with pytest.raises(
+        AuthenticationError, match="ANTHROPIC_API_KEY environment variable is required"
+    ):
+        provider.validate_config()
+
+
+def test_validate_config_custom_env():
+    """Test custom environment variable."""
+    config = {"api_key_env": "CUSTOM_ANTHROPIC_KEY"}
+    provider = AnthropicProvider(config)
+
+    with patch.dict(os.environ, {"CUSTOM_ANTHROPIC_KEY": "custom-key"}):
+        with patch("anthropic.Anthropic") as mock_anthropic:
+            mock_client = MagicMock()
+            mock_anthropic.return_value = mock_client
+
+            provider.validate_config()
+
+            mock_anthropic.assert_called_once_with(api_key="custom-key")
+
+
+def test_get_default_config():
+    """Test default configuration values."""
+    default_config = AnthropicProvider.get_default_config()
+
+    assert default_config["model_name"] == "claude-3-haiku-20240307"
+    assert default_config["max_tokens"] == 150
+    assert default_config["api_key_env"] == "ANTHROPIC_API_KEY"
+    assert default_config["temperature"] == 0.0
+    assert default_config["system_prompt"] == SYSTEM_PROMPT
+
+
+def test_get_bash_command_success(mock_anthropic_key):
+    """Test successful command generation."""
+    config = {"model_name": "claude-3-haiku-20240307", "max_tokens": 150}
+    provider = AnthropicProvider(config)
+
+    mock_response = MagicMock()
+    mock_response.content = [MagicMock(text="ls -la")]
+
+    with patch("anthropic.Anthropic") as mock_anthropic:
+        mock_client = MagicMock()
+        mock_client.messages.create.return_value = mock_response
+        mock_anthropic.return_value = mock_client
+
+        result = provider.get_bash_command("list files")
+
+        assert result == "ls -la"
+        mock_client.messages.create.assert_called_once_with(
+            model="claude-3-haiku-20240307",
+            max_tokens=150,
+            temperature=0.0,
+            system=SYSTEM_PROMPT,
+            messages=[{"role": "user", "content": "list files"}],
+        )
+
+
+def test_get_bash_command_auto_validate(mock_anthropic_key):
+    """Test auto-validation behavior."""
+    config = {}
+    provider = AnthropicProvider(config)
+
+    mock_response = MagicMock()
+    mock_response.content = [MagicMock(text="ls -la")]
+
+    with patch("anthropic.Anthropic") as mock_anthropic:
+        mock_client = MagicMock()
+        mock_client.messages.create.return_value = mock_response
+        mock_anthropic.return_value = mock_client
+
+        # Client should be None initially
+        assert provider.client is None
+
+        result = provider.get_bash_command("list files")
+
+        # Client should be set after auto-validation
+        assert provider.client is not None
+        assert result == "ls -la"
+
+
+def test_handle_api_error_auth():
+    """Test authentication error mapping."""
+    provider = AnthropicProvider({})
+
+    with pytest.raises(AuthenticationError, match="Invalid API key"):
+        provider._handle_api_error(Exception("authentication failed"))
+
+
+def test_handle_api_error_rate_limit():
+    """Test rate limit error mapping."""
+    provider = AnthropicProvider({})
+
+    with pytest.raises(RateLimitError, match="API rate limit exceeded"):
+        provider._handle_api_error(Exception("rate limit exceeded"))
+
+
+def test_handle_api_error_generic():
+    """Test generic API error mapping."""
+    provider = AnthropicProvider({})
+
+    with pytest.raises(APIError, match="API request failed"):
+        provider._handle_api_error(Exception("unexpected error"))
+
+
+def test_config_parameter_usage(mock_anthropic_key):
+    """Test configuration parameter usage."""
+    config = {
+        "model_name": "claude-3-5-sonnet-20241022",
+        "max_tokens": 1024,
+        "temperature": 0.5,
+        "system_prompt": "Custom system prompt",
+    }
+    provider = AnthropicProvider(config)
+
+    mock_response = MagicMock()
+    mock_response.content = [MagicMock(text="custom response")]
+
+    with patch("anthropic.Anthropic") as mock_anthropic:
+        mock_client = MagicMock()
+        mock_client.messages.create.return_value = mock_response
+        mock_anthropic.return_value = mock_client
+
+        result = provider.get_bash_command("test prompt")
+
+        assert result == "custom response"
+        mock_client.messages.create.assert_called_once_with(
+            model="claude-3-5-sonnet-20241022",
+            max_tokens=1024,
+            temperature=0.5,
+            system="Custom system prompt",
+            messages=[{"role": "user", "content": "test prompt"}],
+        )

test/test_config.py

@@ -0,0 +1,164 @@
+"""Tests for the configuration system."""
+
+import os
+from unittest.mock import patch
+
+import pytest
+
+from ask.config import (
+    get_config_path,
+    get_default_model,
+    get_default_provider,
+    get_provider_config,
+    load_config,
+)
+from ask.exceptions import ConfigurationError
+
+
+def test_get_config_path_xdg_config_home(temp_config_dir):
+    """Test XDG_CONFIG_HOME path resolution."""
+    config_file = temp_config_dir / "ask" / "config.toml"
+    config_file.parent.mkdir(parents=True)
+    config_file.touch()
+
+    with patch.dict(os.environ, {"XDG_CONFIG_HOME": str(temp_config_dir)}):
+        assert get_config_path() == config_file
+
+
+def test_get_config_path_default_xdg(temp_config_dir):
+    """Test default ~/.config path."""
+    config_file = temp_config_dir / ".config" / "ask" / "config.toml"
+    config_file.parent.mkdir(parents=True)
+    config_file.touch()
+
+    with patch.dict(os.environ, {}, clear=True):
+        with patch("pathlib.Path.home", return_value=temp_config_dir):
+            assert get_config_path() == config_file
+
+
+def test_get_config_path_fallback(temp_config_dir):
+    """Test ~/.ask fallback path."""
+    config_file = temp_config_dir / ".ask" / "config.toml"
+    config_file.parent.mkdir(parents=True)
+    config_file.touch()
+
+    with patch.dict(os.environ, {}, clear=True):
+        with patch("pathlib.Path.home", return_value=temp_config_dir):
+            assert get_config_path() == config_file
+
+
+def test_get_config_path_none(temp_config_dir):
+    """Test when no config file exists."""
+    with patch.dict(os.environ, {}, clear=True):
+        with patch("pathlib.Path.home", return_value=temp_config_dir):
+            assert get_config_path() is None
+
+
+def test_load_config_valid(test_resources_dir):
+    """Test loading valid TOML config."""
+    config_file = test_resources_dir / "valid_config.toml"
+
+    with patch("ask.config.get_config_path", return_value=config_file):
+        config = load_config()
+        assert config["ask"]["default_model"] == "anthropic"
+        assert config["anthropic"]["model_name"] == "claude-3-haiku-20240307"
+
+
+def test_load_config_invalid(test_resources_dir):
+    """Test loading invalid TOML syntax."""
+    config_file = test_resources_dir / "invalid_config.toml"
+
+    with patch("ask.config.get_config_path", return_value=config_file):
+        with pytest.raises(ConfigurationError, match="Failed to load config file"):
+            load_config()
+
+
+def test_load_config_not_found():
+    """Test when config file doesn't exist."""
+    with patch("ask.config.get_config_path", return_value=None):
+        config = load_config()
+        assert config == {}
+
+
+def test_load_config_permission_error(temp_config_dir):
+    """Test permission errors."""
+    config_file = temp_config_dir / "config.toml"
+    config_file.touch()
+
+    with patch("ask.config.get_config_path", return_value=config_file):
+        with patch("builtins.open", side_effect=PermissionError("Access denied")):
+            with pytest.raises(ConfigurationError, match="Failed to load config file"):
+                load_config()
+
+
+def test_get_provider_config_simple():
+    """Test simple provider name parsing."""
+    config = {"anthropic": {"model_name": "claude-3-haiku-20240307"}}
+
+    provider_name, provider_config = get_provider_config(config, "anthropic")
+    assert provider_name == "anthropic"
+    assert provider_config["model_name"] == "claude-3-haiku-20240307"
+
+
+def test_get_provider_config_with_model():
+    """Test provider:model syntax."""
+    config = {
+        "anthropic": {
+            "model_name": "claude-3-haiku-20240307",
+            "sonnet": {"model_name": "claude-3-5-sonnet-20241022"},
+        }
+    }
+
+    provider_name, provider_config = get_provider_config(config, "anthropic:sonnet")
+    assert provider_name == "anthropic"
+    assert provider_config["model_name"] == "claude-3-5-sonnet-20241022"
+
+
+def test_get_provider_config_nested():
+    """Test nested provider configuration."""
+    config = {
+        "anthropic": {
+            "base_setting": "base_value",
+            "sonnet": {"model_name": "claude-3-5-sonnet-20241022", "max_tokens": 1024},
+        }
+    }
+
+    provider_name, provider_config = get_provider_config(config, "anthropic:sonnet")
+    assert provider_name == "anthropic"
+    assert provider_config["model_name"] == "claude-3-5-sonnet-20241022"
+    assert provider_config["max_tokens"] == 1024
+
+
+def test_get_provider_config_global_merge():
+    """Test global config merging."""
+    config = {
+        "ask": {"global_setting": "global_value", "temperature": 0.1},
+        "anthropic": {"model_name": "claude-3-haiku-20240307", "temperature": 0.0},
+    }
+
+    provider_name, provider_config = get_provider_config(config, "anthropic")
+    assert provider_name == "anthropic"
+    assert provider_config["global_setting"] == "global_value"
+    assert provider_config["temperature"] == 0.0  # Provider-specific overrides global
+
+
+def test_get_default_model():
+    """Test default model retrieval."""
+    config = {"ask": {"default_model": "anthropic:sonnet"}}
+
+    assert get_default_model(config) == "anthropic:sonnet"
+
+
+def test_get_default_provider_anthropic(mock_anthropic_key):
+    """Test Anthropic as default provider."""
+    assert get_default_provider() == "anthropic"
+
+
+def test_get_default_provider_openai(mock_openai_key):
+    """Test OpenAI as default provider."""
+    assert get_default_provider() == "openai"
+
+
+def test_get_default_provider_none(mock_env_vars):
+    """Test when no API keys available."""
+    assert get_default_provider() is None