Metadata-Version: 2.4
Name: alan-terminal-ai
Version: 0.3.0
Summary: AI-powered terminal assistant that converts natural language to safe shell commands using Ollama
Author-email: Ankit Jaiswal <jaiswal.ankit2000@gmail.com>
Maintainer-email: Ankit Jaiswal <jaiswal.ankit2000@gmail.com>
Project-URL: Homepage, https://github.com/ankit0305/alan-terminal-ai
Project-URL: Repository, https://github.com/ankit0305/alan-terminal-ai.git
Project-URL: Bug-Tracker, https://github.com/ankit0305/alan-terminal-ai/issues
Project-URL: Documentation, https://github.com/ankit0305/alan-terminal-ai/blob/main/README.md
Project-URL: Changelog, https://github.com/ankit0305/alan-terminal-ai/releases
Keywords: terminal,ai,command-assistant,shell,ollama,llm,natural-language,developer-tools,devops
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Terminals
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: rich>=13.0.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: pydantic>=2.0.0
Requires-Dist: schedule>=1.2.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Provides-Extra: mcp
Requires-Dist: mcp>=0.1.0; extra == "mcp"
Provides-Extra: openrouter
Requires-Dist: requests>=2.31.0; extra == "openrouter"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.7.0; extra == "anthropic"
Provides-Extra: speech
Requires-Dist: faster-whisper>=0.10.0; extra == "speech"
Provides-Extra: stt
Requires-Dist: faster-whisper>=0.10.0; extra == "stt"
Requires-Dist: silero-vad>=5.0.0; extra == "stt"
Requires-Dist: sounddevice>=0.4.5; extra == "stt"
Requires-Dist: openwakeword>=0.5.0; extra == "stt"
Provides-Extra: all
Requires-Dist: mcp>=0.1.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.7.0; extra == "all"
Requires-Dist: faster-whisper>=0.10.0; extra == "all"
Requires-Dist: silero-vad>=5.0.0; extra == "all"
Requires-Dist: sounddevice>=0.4.5; extra == "all"
Requires-Dist: openwakeword>=0.5.0; extra == "all"

# 🖥️ Alan – AI Terminal Command Assistant

Alan turns natural-language requests into safe, executable shell commands. It runs
locally against [Ollama](https://ollama.ai/) by default and falls back to cloud LLM
providers (OpenRouter, OpenAI, Anthropic) when an API key is configured.

```bash
alan please list all Python files
```

---

## 🚀 Features

- **Natural language → shell commands** (e.g. `alan please list directory files` → `ls`)
- **Multiple LLM backends** — local Ollama first, with OpenRouter / OpenAI / Anthropic fallback
- **Safety checks** — refuses dangerous commands (e.g. `rm -rf /`) and confirms before executing
- **Smart command tracking** — learns from accepted/rejected suggestions and scores confidence
- **Command statistics** via `alan stats`
- **Cross-platform** — detects macOS, Linux (apt/yum/dnf/pacman/zypper), and Windows
- **Clipboard support** via `alan copy`
- Additional modules included in the package: MCP server, speech-to-text / wake-word,
  daemon mode, plugins, and domain personas (DevOps, sysadmin, data scientist, developer)

---

## 📦 Requirements

- **Python 3.8+**
- For local inference: [Ollama](https://ollama.ai/) installed and running, with at least
  one model pulled (default `qwen2.5:0.5b`):
  ```bash
  brew install ollama        # or see https://ollama.ai for other platforms
  ollama serve
  ollama pull qwen2.5:0.5b
  ```
- **OR** a cloud provider API key (no Ollama required):
  set one of `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, or `ANTHROPIC_API_KEY`.

Core Python dependencies (`rich`, `colorama`, `pydantic`, `schedule`, `requests`) are
installed automatically by `pip`.

---

## 📥 Install (users)

```bash
pip install alan-terminal-ai
```

Optional provider/feature extras:

```bash
pip install "alan-terminal-ai[openrouter]"   # OpenRouter
pip install "alan-terminal-ai[openai]"       # OpenAI
pip install "alan-terminal-ai[anthropic]"    # Anthropic
pip install "alan-terminal-ai[mcp]"          # MCP server
pip install "alan-terminal-ai[stt]"          # speech-to-text + wake word
pip install "alan-terminal-ai[all]"          # everything optional
```

Verify the install:

```bash
alan --version
alan status        # shows which LLM backend is active
```

---

## 🛠️ Development setup (contributors)

If you want to work on Alan itself:

```bash
# 1. Clone
git clone https://github.com/ankit0305/alan-terminal-ai.git
cd alan-terminal-ai

# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 3. Editable install with dev tools
pip install -e ".[dev]"

# 4. (Recommended) install git hooks
pre-commit install
```

### Running tests

```bash
pytest
```

Tests live in `alanterminalai/tests/`. The default `pytest` config (in `pyproject.toml`)
runs with coverage enabled.

### Linting & formatting

The repo is configured for `black`, `isort`, `flake8`, and `mypy` (line length 100):

```bash
black .
isort .
flake8
mypy alanterminalai
```

These also run automatically via `pre-commit` if you installed the hooks.

---

## 💡 Usage

```bash
alan please [your request]
```

### Examples

```bash
alan please list all Python files
alan please find files modified today
alan please count lines in all py files
alan please show disk usage
alan please check running processes
```

For each request Alan suggests a command, runs safety checks, shows confidence based on
your history, and asks for confirmation before executing.

---

## 📜 Commands

```bash
alan please [request]   # Get and run a command suggestion
alan copy               # Copy the last command/output to clipboard
alan stats              # Show command tracking statistics
alan status             # Show available and active LLM backends
alan --help             # Show help
alan --version          # Show version
```

---

## 🔀 LLM backend selection

Alan tries backends in this order:

1. **Ollama** (local, default model `qwen2.5:0.5b`) — used if Ollama is running.
2. **Cloud fallback** — if Ollama is unavailable, Alan uses the first configured cloud
   provider. Set one of:
   ```bash
   export OPENROUTER_API_KEY=...
   export OPENAI_API_KEY=...
   export ANTHROPIC_API_KEY=...
   ```

Run `alan status` to see which backends are available and which one is active.

---

## 🧠 Smart Learning & Tracking

Alan tracks command preferences to improve future suggestions:

- **Acceptance/rejection tracking** — learns which commands you accept or reject
- **Confidence scoring** — shows confidence levels based on your history
- **Similar command suggestions** — surfaces previously accepted similar commands
- **Usage statistics** — most-used command types and success rates

View your statistics with `alan stats`. History is stored in `command_history.json`.

---

## 🧩 Configuration

Create `~/.alan_config.json` to customize behavior:

```json
{
  "tracking": {
    "enabled": true,
    "show_confidence": true,
    "show_similar_commands": true
  },
  "display": {
    "show_system_info": true,
    "use_emojis": true,
    "verbose_output": false
  },
  "safety": {
    "enable_safety_checks": true,
    "prompt_for_dangerous_commands": true
  }
}
```

---

## ⚠️ Safety

Alan will:

- Reject known-dangerous commands (e.g. `rm -rf /`)
- Display the suggested command first
- Ask for confirmation before running anything

You can review and modify the command before it runs.

---

## 📚 Documentation

Additional documentation lives in the [`docs/`](docs/) folder:

- [`TERMINAL_USAGE_EXAMPLES.md`](docs/TERMINAL_USAGE_EXAMPLES.md) — real-world CLI usage examples
- [`TESTING.md`](docs/TESTING.md) — testing guide
- [`PUBLISHING_GUIDE.md`](docs/PUBLISHING_GUIDE.md) / [`QUICK_PUBLISH.md`](docs/QUICK_PUBLISH.md) — releasing to PyPI
- [`IMPLEMENTATION.md`](docs/IMPLEMENTATION.md) — feature implementation notes

---

## 🤝 Contributing

Contributions are welcome. Fork the repo, create a feature branch, run the tests and
linters (`pytest`, `pre-commit run --all-files`), and open a pull request against `main`.

- **Issues:** https://github.com/ankit0305/alan-terminal-ai/issues
- **Repository:** https://github.com/ankit0305/alan-terminal-ai

---

## 📄 License

See [LICENSE](LICENSE).
