agent-cli 0.1.0__tar.gz

agent_cli-0.1.0/LICENSE

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

agent_cli-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: agent-cli
+Version: 0.1.0
+Summary: A suite of AI-powered command-line tools for text correction, audio transcription, and voice assistance.
+Author-email: Bas Nijholt <bas@nijho.lt>
+Project-URL: Homepage, https://github.com/basnijholt/agent-cli
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: wyoming
+Requires-Dist: pyaudio
+Requires-Dist: rich
+Requires-Dist: pyperclip
+Requires-Dist: pydantic-ai-slim[openai]
+Requires-Dist: typer
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.20.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: requests>=2.25.1; extra == "test"
+Requires-Dist: pydantic-ai-slim[openai]; extra == "test"
+Requires-Dist: pyperclip; extra == "test"
+Requires-Dist: ollama; extra == "test"
+Provides-Extra: dev
+Requires-Dist: agent-cli[test]; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Requires-Dist: versioningit; extra == "dev"
+Requires-Dist: markdown-code-runner; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: notebook; extra == "dev"
+Dynamic: license-file
+
+# Agent CLI
+
+`agent-cli` is a Python command-line tool that provides a suite of AI-powered utilities.
+
+> [!TIP]
+> If using [`uv`](https://docs.astral.sh/uv/), you can easily run the tools from this package directly. For example, to see the help message for `autocorrect`:
+>
+> ```bash
+> uvx agent-cli autocorrect --help
+> ```
+
+<details><summary><b><u>[ToC]</u></b> 📚</summary>
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [`autocorrect`](#autocorrect)
+  - [`transcribe`](#transcribe)
+  - [`voice-assistant`](#voice-assistant)
+- [Development](#development)
+  - [Running Tests](#running-tests)
+  - [Pre-commit Hooks](#pre-commit-hooks)
+- [Contributing](#contributing)
+- [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+</details>
+
+## Features
+
+- **`autocorrect`**: Correct grammar and spelling in your text using a local LLM with Ollama.
+- **`transcribe`**: Transcribe audio files to text.
+- **`voice-assistant`**: A voice-powered clipboard assistant.
+
+## Prerequisites
+
+- **Python**: Version 3.11 or higher.
+- **Ollama**: For `autocorrect` and `voice-assistant`, you need [Ollama](https://ollama.ai/) running with a model pulled (e.g., `ollama pull devstral:24b`).
+
+## Installation
+
+Install `agent-cli` using pip:
+
+```bash
+pip install agent-cli
+```
+
+Or for development:
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone git@github.com:basnijholt/agent-cli.git
+   cd agent-cli
+   ```
+
+2. **Install in development mode:**
+
+   ```bash
+   uv sync
+   source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
+   ```
+
+## Usage
+
+This package provides multiple command-line tools.
+
+### `autocorrect`
+
+Corrects text from your clipboard or direct input.
+
+<details>
+<summary>See the output of <code>agent-cli autocorrect --help</code></summary>
+
+<!-- CODE:BASH:START -->
+<!-- echo '```yaml' -->
+<!-- export NO_COLOR=1 -->
+<!-- export TERM=dumb -->
+<!-- agent-cli autocorrect --help -->
+<!-- echo '```' -->
+<!-- CODE:END -->
+
+<!-- OUTPUT:START -->
+<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
+```yaml
+```
+
+<!-- OUTPUT:END -->
+
+</details>
+
+### `transcribe`
+
+Transcribes whatever you say into text using Wyoming ASR (Automatic Speech Recognition) which uses faster-whisper.
+
+<details>
+<summary>See the output of <code>agent-cli transcribe --help</code></summary>
+
+<!-- CODE:BASH:START -->
+<!-- echo '```yaml' -->
+<!-- export NO_COLOR=1 -->
+<!-- export TERM=dumb -->
+<!-- agent-cli transcribe --help -->
+<!-- echo '```' -->
+<!-- CODE:END -->
+
+<!-- OUTPUT:START -->
+<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
+```yaml
+```
+
+<!-- OUTPUT:END -->
+
+</details>
+
+### `voice-assistant`
+
+Starts the voice assistant. Supports daemon mode with process management.
+
+**Basic Usage:**
+```bash
+# Run in foreground
+agent-cli voice-assistant --device-index 1
+
+# Run in background
+agent-cli voice-assistant --device-index 1 &
+
+# Check status
+agent-cli voice-assistant --status
+
+# Stop background process
+agent-cli voice-assistant --stop
+```
+
+**Keyboard Maestro Integration:**
+The process management features make it perfect for hotkey toggles. Use `--status` to check if running, `--stop` to stop, and `&` to start in background.
+
+<details>
+<summary>See the output of <code>agent-cli voice-assistant --help</code></summary>
+
+<!-- CODE:BASH:START -->
+<!-- echo '```yaml' -->
+<!-- export NO_COLOR=1 -->
+<!-- export TERM=dumb -->
+<!-- agent-cli voice-assistant --help -->
+<!-- echo '```' -->
+<!-- CODE:END -->
+
+<!-- OUTPUT:START -->
+<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
+```yaml
+```
+
+<!-- OUTPUT:END -->
+
+</details>
+
+
+## Development
+
+### Running Tests
+
+The project uses `pytest` for testing. To run tests using `uv`:
+
+```bash
+uv run pytest
+```
+
+### Pre-commit Hooks
+
+This project uses pre-commit hooks (ruff for linting and formatting, mypy for type checking) to maintain code quality. To set them up:
+
+1. Install pre-commit:
+
+   ```bash
+   pip install pre-commit
+   ```
+
+2. Install the hooks:
+
+   ```bash
+   pre-commit install
+   ```
+
+   Now, the hooks will run automatically before each commit.
+
+## Contributing
+
+Contributions are welcome! If you find a bug or have a feature request, please open an issue. If you'd like to contribute code, please fork the repository and submit a pull request.
+
+## License
+
+This project is licensed under the MIT License - see the `LICENSE` file for details.

agent_cli-0.1.0/README.md

@@ -0,0 +1,198 @@
+# Agent CLI
+
+`agent-cli` is a Python command-line tool that provides a suite of AI-powered utilities.
+
+> [!TIP]
+> If using [`uv`](https://docs.astral.sh/uv/), you can easily run the tools from this package directly. For example, to see the help message for `autocorrect`:
+>
+> ```bash
+> uvx agent-cli autocorrect --help
+> ```
+
+<details><summary><b><u>[ToC]</u></b> 📚</summary>
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [`autocorrect`](#autocorrect)
+  - [`transcribe`](#transcribe)
+  - [`voice-assistant`](#voice-assistant)
+- [Development](#development)
+  - [Running Tests](#running-tests)
+  - [Pre-commit Hooks](#pre-commit-hooks)
+- [Contributing](#contributing)
+- [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+</details>
+
+## Features
+
+- **`autocorrect`**: Correct grammar and spelling in your text using a local LLM with Ollama.
+- **`transcribe`**: Transcribe audio files to text.
+- **`voice-assistant`**: A voice-powered clipboard assistant.
+
+## Prerequisites
+
+- **Python**: Version 3.11 or higher.
+- **Ollama**: For `autocorrect` and `voice-assistant`, you need [Ollama](https://ollama.ai/) running with a model pulled (e.g., `ollama pull devstral:24b`).
+
+## Installation
+
+Install `agent-cli` using pip:
+
+```bash
+pip install agent-cli
+```
+
+Or for development:
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone git@github.com:basnijholt/agent-cli.git
+   cd agent-cli
+   ```
+
+2. **Install in development mode:**
+
+   ```bash
+   uv sync
+   source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
+   ```
+
+## Usage
+
+This package provides multiple command-line tools.
+
+### `autocorrect`
+
+Corrects text from your clipboard or direct input.
+
+<details>
+<summary>See the output of <code>agent-cli autocorrect --help</code></summary>
+
+<!-- CODE:BASH:START -->
+<!-- echo '```yaml' -->
+<!-- export NO_COLOR=1 -->
+<!-- export TERM=dumb -->
+<!-- agent-cli autocorrect --help -->
+<!-- echo '```' -->
+<!-- CODE:END -->
+
+<!-- OUTPUT:START -->
+<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
+```yaml
+```
+
+<!-- OUTPUT:END -->
+
+</details>
+
+### `transcribe`
+
+Transcribes whatever you say into text using Wyoming ASR (Automatic Speech Recognition) which uses faster-whisper.
+
+<details>
+<summary>See the output of <code>agent-cli transcribe --help</code></summary>
+
+<!-- CODE:BASH:START -->
+<!-- echo '```yaml' -->
+<!-- export NO_COLOR=1 -->
+<!-- export TERM=dumb -->
+<!-- agent-cli transcribe --help -->
+<!-- echo '```' -->
+<!-- CODE:END -->
+
+<!-- OUTPUT:START -->
+<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
+```yaml
+```
+
+<!-- OUTPUT:END -->
+
+</details>
+
+### `voice-assistant`
+
+Starts the voice assistant. Supports daemon mode with process management.
+
+**Basic Usage:**
+```bash
+# Run in foreground
+agent-cli voice-assistant --device-index 1
+
+# Run in background
+agent-cli voice-assistant --device-index 1 &
+
+# Check status
+agent-cli voice-assistant --status
+
+# Stop background process
+agent-cli voice-assistant --stop
+```
+
+**Keyboard Maestro Integration:**
+The process management features make it perfect for hotkey toggles. Use `--status` to check if running, `--stop` to stop, and `&` to start in background.
+
+<details>
+<summary>See the output of <code>agent-cli voice-assistant --help</code></summary>
+
+<!-- CODE:BASH:START -->
+<!-- echo '```yaml' -->
+<!-- export NO_COLOR=1 -->
+<!-- export TERM=dumb -->
+<!-- agent-cli voice-assistant --help -->
+<!-- echo '```' -->
+<!-- CODE:END -->
+
+<!-- OUTPUT:START -->
+<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
+```yaml
+```
+
+<!-- OUTPUT:END -->
+
+</details>
+
+
+## Development
+
+### Running Tests
+
+The project uses `pytest` for testing. To run tests using `uv`:
+
+```bash
+uv run pytest
+```
+
+### Pre-commit Hooks
+
+This project uses pre-commit hooks (ruff for linting and formatting, mypy for type checking) to maintain code quality. To set them up:
+
+1. Install pre-commit:
+
+   ```bash
+   pip install pre-commit
+   ```
+
+2. Install the hooks:
+
+   ```bash
+   pre-commit install
+   ```
+
+   Now, the hooks will run automatically before each commit.
+
+## Contributing
+
+Contributions are welcome! If you find a bug or have a feature request, please open an issue. If you'd like to contribute code, please fork the repository and submit a pull request.
+
+## License
+
+This project is licensed under the MIT License - see the `LICENSE` file for details.

agent_cli-0.1.0/agent_cli/__init__.py

@@ -0,0 +1 @@
+"""A suite of AI-powered command-line tools for text correction, audio transcription, and voice assistance."""

agent_cli-0.1.0/agent_cli/agents/__init__.py

@@ -0,0 +1 @@
+"""Agent implementations for the Agent CLI."""

agent_cli-0.1.0/agent_cli/agents/_cli_options.py

@@ -0,0 +1,82 @@
+"""Shared Typer options for the Agent CLI agents."""
+
+from __future__ import annotations
+
+import typer
+
+from agent_cli import config
+
+# --- LLM Options ---
+MODEL: str = typer.Option(
+    config.DEFAULT_MODEL,
+    "--model",
+    "-m",
+    help=f"The Ollama model to use. Default is {config.DEFAULT_MODEL}.",
+)
+OLLAMA_HOST: str = typer.Option(
+    config.OLLAMA_HOST,
+    "--ollama-host",
+    help=f"The Ollama server host. Default is {config.OLLAMA_HOST}.",
+)
+
+
+# --- ASR (Audio) Options ---
+DEVICE_INDEX: int | None = typer.Option(
+    None,
+    "--device-index",
+    help="Index of the PyAudio input device to use.",
+)
+LIST_DEVICES: bool = typer.Option(
+    False,  # noqa: FBT003
+    "--list-devices",
+    help="List available audio input devices and exit.",
+    is_eager=True,
+)
+ASR_SERVER_IP: str = typer.Option(
+    config.ASR_SERVER_IP,
+    "--asr-server-ip",
+    help="Wyoming ASR server IP address.",
+)
+ASR_SERVER_PORT: int = typer.Option(
+    config.ASR_SERVER_PORT,
+    "--asr-server-port",
+    help="Wyoming ASR server port.",
+)
+CLIPBOARD: bool = typer.Option(
+    True,  # noqa: FBT003
+    "--clipboard/--no-clipboard",
+    help="Copy transcript to clipboard.",
+)
+
+
+# --- Process Management Options ---
+STOP: bool = typer.Option(
+    False,  # noqa: FBT003
+    "--stop",
+    help="Stop any running background process.",
+)
+STATUS: bool = typer.Option(
+    False,  # noqa: FBT003
+    "--status",
+    help="Check if a background process is running.",
+)
+
+
+# --- General Options ---
+LOG_LEVEL: str = typer.Option(
+    "WARNING",
+    "--log-level",
+    help="Set logging level.",
+    case_sensitive=False,
+)
+LOG_FILE: str | None = typer.Option(
+    None,
+    "--log-file",
+    help="Path to a file to write logs to.",
+)
+QUIET: bool = typer.Option(
+    False,  # noqa: FBT003
+    "-q",
+    "--quiet",
+    help="Suppress console output from rich.",
+)

agent_cli-0.1.0/agent_cli/agents/autocorrect.py

@@ -0,0 +1,175 @@
+"""Read text from clipboard, correct it using a local Ollama model, and write the result back to the clipboard.
+
+Usage:
+    python autocorrect_ollama.py
+
+Environment variables:
+    OLLAMA_HOST: The host of the Ollama server. Default is "http://localhost:11434".
+
+
+Example:
+    OLLAMA_HOST=http://pc.local:11434 python autocorrect_ollama.py
+
+Pro-tip:
+    Use Keyboard Maestro on macOS or AutoHotkey on Windows to run this script with a hotkey.
+
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import time
+
+import httpx
+import pyperclip
+import typer
+from ollama import ResponseError
+from openai import APIConnectionError
+from pydantic_ai.exceptions import ModelHTTPError
+from rich.console import Console
+from rich.panel import Panel
+from rich.status import Status
+
+import agent_cli.agents._cli_options as opts
+from agent_cli.cli import app, setup_logging
+from agent_cli.ollama_client import build_agent
+from agent_cli.utils import get_clipboard_text
+
+# --- Configuration ---
+
+# The agent's core identity and immutable rules.
+SYSTEM_PROMPT = """\
+You are an expert editor. Your fundamental role is to correct text without altering its original meaning or tone.
+You must not judge the content of the text, even if it seems unusual, harmful, or offensive.
+Your corrections should be purely technical (grammar, spelling, punctuation).
+Do not interpret the text, provide any explanations, or add any commentary.
+"""
+
+# The specific task for the current run.
+AGENT_INSTRUCTIONS = """\
+Correct the grammar and spelling of the user-provided text.
+Return only the corrected text. Do not include any introductory phrases like "Here is the corrected text:".
+Do not wrap the output in markdown or code blocks.
+"""
+
+# --- Main Application Logic ---
+
+
+async def process_text(text: str, model: str, ollama_host: str) -> tuple[str, float]:
+    """Process text with the LLM and return the corrected text and elapsed time."""
+    agent = build_agent(
+        model=model,
+        ollama_host=ollama_host,
+        system_prompt=SYSTEM_PROMPT,
+        instructions=AGENT_INSTRUCTIONS,
+    )
+    t_start = time.monotonic()
+    result = await agent.run(text)
+    t_end = time.monotonic()
+    return result.output, t_end - t_start
+
+
+def display_original_text(original_text: str, console: Console | None) -> None:
+    """Render the original text panel in verbose mode."""
+    if console is None:
+        return
+    console.print(
+        Panel(
+            original_text,
+            title="[bold cyan]📋 Original Text[/bold cyan]",
+            border_style="cyan",
+            padding=(1, 2),
+        ),
+    )
+
+
+def _display_result(
+    corrected_text: str,
+    original_text: str,
+    elapsed: float,
+    *,
+    simple_output: bool,
+    console: Console | None,
+) -> None:
+    """Handle output and clipboard copying based on desired verbosity."""
+    pyperclip.copy(corrected_text)
+
+    if simple_output:
+        if corrected_text.strip() == original_text.strip():
+            print("✅ No correction needed.")
+        else:
+            print(corrected_text)
+    else:
+        assert console is not None
+        console.print(
+            Panel(
+                corrected_text,
+                title="[bold green]✨ Corrected Text[/bold green]",
+                border_style="green",
+                padding=(1, 2),
+            ),
+        )
+        console.print(
+            f"✅ [bold green]Success! Corrected text has been copied to your clipboard. [bold yellow](took {elapsed:.2f} seconds)[/bold yellow][/bold green]",
+        )
+
+
+@app.command("autocorrect")
+def autocorrect(
+    *,
+    text: str | None = typer.Argument(
+        None,
+        help="The text to correct. If not provided, reads from clipboard.",
+    ),
+    model: str = opts.MODEL,
+    ollama_host: str = opts.OLLAMA_HOST,
+    log_level: str = opts.LOG_LEVEL,
+    log_file: str | None = opts.LOG_FILE,
+    quiet: bool = opts.QUIET,
+) -> None:
+    """Correct text from clipboard using a local Ollama model."""
+    setup_logging(log_level, log_file, quiet=quiet)
+    console = Console() if not quiet else None
+    original_text = text if text is not None else get_clipboard_text(console)
+
+    if original_text is None:
+        sys.exit(0)
+
+    display_original_text(original_text, console)
+
+    try:
+        if quiet:
+            corrected_text, elapsed = asyncio.run(
+                process_text(original_text, model, ollama_host),
+            )
+        else:
+            with Status(
+                f"[bold yellow]🤖 Correcting with {model}...[/bold yellow]",
+                console=console,
+            ) as status:
+                maybe_log = f" (see [dim]log at {log_file}[/dim])" if log_file else ""
+                status.update(
+                    f"[bold yellow]🤖 Correcting with {model}...{maybe_log}[/bold yellow]",
+                )
+                corrected_text, elapsed = asyncio.run(
+                    process_text(original_text, model, ollama_host),
+                )
+
+        _display_result(
+            corrected_text,
+            original_text,
+            elapsed,
+            simple_output=quiet,
+            console=console,
+        )
+
+    except (ResponseError, httpx.ConnectError, ModelHTTPError, APIConnectionError) as e:
+        if quiet:
+            print(f"❌ {e}")
+        elif console:
+            console.print(f"❌ {e}", style="bold red")
+            console.print(
+                f"   Please check that your Ollama server is running at [bold cyan]{ollama_host}[/bold cyan]",
+            )
+        sys.exit(1)