ape-linux 0.3.4__tar.gz → 0.4.0__tar.gz

{ape_linux-0.3.4 → ape_linux-0.4.0}/.github/workflows/tests.yaml

@@ -20,10 +20,12 @@ jobs:
         run: curl -LsSf https://astral.sh/uv/install.sh | sh
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
+      - name: Set up just
+        uses: extractions/setup-just@v3
       - name: Run type check
-        run: uv run pyright .
+        run: just type-check
       - name: Run tests
-        run: uv run pytest
+        run: just test
 
   lint:
     name: Lint
@@ -35,5 +37,7 @@ jobs:
         run: curl -LsSf https://astral.sh/uv/install.sh | sh
       - name: Set up Python 3.13
         run: uv python install 3.13
+      - name: Set up just
+        uses: extractions/setup-just@v3
       - name: Ruff
-        run: uv run ruff check .
+        run: just lint

ape_linux-0.4.0/.python-version

@@ -0,0 +1 @@
+3.14

ape_linux-0.4.0/CLAUDE.md

@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+> **Keep this file current.** Whenever you make a change that affects anything
+> described here — behavior, commands, architecture, conventions, defaults, file
+> layout — update the relevant section of CLAUDE.md (and `README.md` where it
+> overlaps) in the same change, so the docs never drift from the code.
+
+## Overview
+
+Ape (`ape-linux` on PyPI) is a CLI that turns a natural-language description of a
+Linux task into a shell command using an LLM. The entire implementation lives in a
+single module, `ape_linux.py`, exposing a Typer app as the `ape` console script.
+
+**Single-file rule:** all of Ape's implementation must stay in `ape_linux.py` — do
+not split it into additional modules/packages. New behavior is added as functions in
+this one file.
+
+## Commands
+
+This project uses [`uv`](https://docs.astral.sh/uv/) for everything, with
+[`just`](https://github.com/casey/just) wrapping the CI-relevant tasks.
+
+```bash
+just lint                     # lint (uv run ruff check .)
+just type-check               # type check with ty (uv run ty check)
+just test                     # run all tests (uv run pytest)
+```
+
+The `justfile` recipes are the single source of truth for lint, type-check, and test:
+both local dev and CI (`.github/workflows/tests.yaml`) invoke them, so the two can't
+drift. CI installs `just` via the `extractions/setup-just` action. Other useful
+commands:
+
+```bash
+uv sync                       # install deps + dev group into .venv
+uv run pytest tests/test_app.py::test_app_for_version   # run a single test
+uv run ruff format .          # format
+uv run ape "list all files"   # run the CLI locally
+uv build                      # build the wheel/sdist
+```
+
+## Architecture
+
+The flow in `ape_linux.py` is intentionally minimal:
+
+1. `main()` is the single Typer command. It takes the `query` argument plus
+   `--model/-m`, `--execute/-e`, `--system-info/-s`, and `--version/-v` options.
+   `--system-info` is an eager flag (like `--version`) whose callback prints
+   `detect_system_context()` and exits before the LLM is called, so it works without a
+   `query`.
+2. A hard-coded `system_prompt` (with few-shot examples) constrains the model to emit
+   **only** a runnable command — no Markdown fences — or `echo "Please try again."`
+   for anything off-topic. This prompt is the core product behavior; changes to it
+   directly change what the tool outputs. `main()` then appends a system-context block
+   (see below) so suggestions match the current machine.
+2a. `detect_system_context()` returns a best-effort, newline-separated `Key: value`
+   block describing the current machine (OS family + macOS/distro version, GNU-vs-BSD
+   userland, CPU arch, `$SHELL`, root-or-not, available package managers, and a probed
+   list of common tools). Two invariants: it **never raises** (every probe is guarded,
+   so an unavailable API or missing file just omits that field instead of crashing at
+   startup), and it **never includes identifying info** (no username, hostname, working
+   directory, or home path). Everything is stdlib (`platform`, `os`, `shutil.which`) and
+   stat-based — no subprocesses — to keep startup fast. Notable guards:
+   `platform.freedesktop_os_release()` raises `OSError` on macOS/minimal containers, and
+   `os.geteuid()` is absent on non-Unix platforms (`hasattr` check).
+3. `call_llm()` wraps `pydantic_ai.Agent`, which is the provider abstraction. Models
+   are passed through verbatim in `provider:name` form (e.g. `anthropic:claude-sonnet-4-5`),
+   so Ape supports any provider Pydantic AI supports without provider-specific code.
+   `--model` defaults to `None`; `main()` resolves the model as `--model` (if given)
+   → `APE_MODEL` env var → the `DEFAULT_MODEL` constant (`openai-chat:gpt-4.1`).
+   Credentials come from each provider's standard env var (e.g. `OPENAI_API_KEY`,
+   `ANTHROPIC_API_KEY`).
+4. Errors are flattened to one-line stderr messages with exit code 1 —
+   `ModelHTTPError` reports status/message; any other exception (bad credentials,
+   unknown provider) prints `str(error)`. Tracebacks are suppressed via
+   `pretty_exceptions_enable=False` on the Typer app.
+5. With `--execute`, the suggested command is run via `subprocess.check_call(..., shell=True)`.
+
+## Testing
+
+`tests/test_app.py` uses `typer.testing.CliRunner` and monkeypatches
+`ape_linux.call_llm` so no real network/LLM calls happen. The `mockenv` fixture sets a
+dummy `OPENAI_API_KEY`. Note `test_app_for_suggestion_with_execute` mocks the LLM to
+return `ls` and actually executes it (harmless, but be aware when adding execute-path
+tests — avoid destructive mocked commands).
+
+`detect_system_context()` is covered by tests that assert it returns a string without
+crashing, reports the OS, and — importantly — excludes the current username, hostname,
+working directory, and home path. These run against the real host (no mocking), so keep
+them platform-agnostic; the username check skips the `root` collision with the privilege
+line.
+
+## Conventions
+
+- Ruff targets `py314`; lint rules are `F, E, W, I001` (pyflakes, pycodestyle, import
+  sorting). `ape_linux` is the known first-party package for import ordering.
+- The published package requires Python >=3.10; CI matrixes 3.10–3.13, while local dev
+  uses 3.14 (`.python-version`).
+- Version is read at runtime from package metadata (`importlib.metadata.version`), so
+  the single source of truth is `pyproject.toml`'s `version`. Publishing is tag-driven
+  (`.github/workflows/publish.yaml`).

{ape_linux-0.3.4 → ape_linux-0.4.0}/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2024 Seto Balian
+Copyright 2026 Seto Balian
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to

ape_linux-0.4.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: ape-linux
+Version: 0.4.0
+Summary: AI for Linux commands
+Project-URL: Homepage, https://github.com/sbalian/ape
+Project-URL: Repository, https://github.com/sbalian/ape
+Author-email: Seto Balian <seto.balian@gmail.com>
+Maintainer-email: Seto Balian <seto.balian@gmail.com>
+License: MIT License
+License-File: LICENSE
+Keywords: ai,anthropic,linux,llm,openai,pydantic-ai
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Requires-Dist: pydantic-ai-slim[anthropic,google,groq,mistral,openai]>=1.104.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: typer>=0.15.2
+Description-Content-Type: text/markdown
+
+# Ape
+
+Ape is an AI for Linux commands.
+
+```sh
+ape "Find all the important PDF files in user/projects. An important PDF file has 'attention' in its name. Write the results to important_files.txt and then move it to Documents."
+```
+
+Output:
+
+```text
+find ~/user/projects -type f -name "*attention*.pdf" > important_files.txt && mv important_files.txt ~/Documents/
+```
+
+Ape works with any provider supported by [Pydantic AI](https://ai.pydantic.dev/models/)
+— OpenAI, Anthropic, Google, Groq, Mistral and more.
+
+To install ([`uv`](https://docs.astral.sh/uv/getting-started/installation/) recommended):
+
+```bash
+uv tool install ape-linux
+```
+
+Next, set the API key for your provider using its standard environment variable.
+For example:
+
+```bash
+export OPENAI_API_KEY=key      # for OpenAI models
+export ANTHROPIC_API_KEY=key   # for Anthropic models
+```
+
+To run:
+
+```bash
+ape "Create a symbolic link called win pointing to /mnt/c/Users/jdoe"
+```
+
+Output:
+
+```text
+ln -s /mnt/c/Users/jdoe win
+```
+
+Another example:
+
+```bash
+ape "Delete all the .venv directories under projects/"
+```
+
+Output:
+
+```text
+find projects/ -type d -name ".venv" -exec rm -rf {} +
+```
+
+If you try to ask something unrelated to Linux commands:
+
+```bash
+ape "Tell me about monkeys"
+```
+
+you should get:
+
+```text
+echo "Please try again."
+```
+
+You can change the model using `--model` or `-m`. Models are specified in
+`provider:name` form.
+See [here](https://ai.pydantic.dev/models/) for the supported providers and models.
+For example:
+
+```bash
+ape "List the contents of the working directory with as much detail as possible" --model anthropic:claude-sonnet-4-5
+```
+
+The model is resolved as follows:
+
+1. If `--model`/`-m` is given, that value is always used.
+2. Otherwise, if the `APE_MODEL` environment variable is set, its value is used.
+3. Otherwise, the default `openai-chat:gpt-4.1` is used.
+
+So you can set a personal default without passing `--model` every time:
+
+```bash
+export APE_MODEL=anthropic:claude-sonnet-4-5
+```
+
+Output:
+
+```text
+ls -lha
+```
+
+## System-aware suggestions
+
+Ape automatically detects a few facts about your machine and adds them to the prompt so
+the suggested command is correct for *your* environment — for example BSD (macOS) vs GNU
+(Linux) flags, the right package manager (`brew`, `apt`, `dnf`, `pacman`, ...), and tools
+that are actually installed. It looks at:
+
+- operating system and version (macOS version or Linux distribution),
+- whether the userland is BSD or GNU,
+- CPU architecture (e.g. `arm64` vs `x86_64`),
+- your shell (`$SHELL`),
+- whether you are root,
+- available package manager(s) and common tools (`rg`, `fd`, `jq`, `docker`, ...).
+
+This is all gathered locally with the Python standard library and is best-effort: if
+anything can't be determined it is simply left out. **No identifying information is
+collected or sent** — never your username, hostname, working directory, or home path.
+
+To see exactly what Ape detects and sends (without calling the model), use
+`--system-info` or `-s`:
+
+```bash
+ape --system-info
+```
+
+Output (example):
+
+```text
+Operating system: Darwin
+macOS version: 26.5
+Userland: BSD (macOS) — prefer BSD-compatible flags
+Architecture: arm64
+Shell: /bin/zsh
+Privileges: non-root (use sudo for privileged actions)
+Package manager(s): brew
+Available tools: rg, fd, jq, git, curl, docker, tar, rsync, sed, awk
+```
+
+## Executing commands
+
+If you pass `--execute` or `-e`, the tool will run the command for you after printing it! Be careful with this as LLMs often make mistakes:
+
+```bash
+ape "Who am I logged in as?"
+```
+
+Output:
+
+```text
+whoami
+jdoe
+```
+
+For more help:
+
+```bash
+ape --help
+```
+
+See also: [Gorilla](https://github.com/gorilla-llm)

ape_linux-0.4.0/README.md

@@ -0,0 +1,154 @@
+# Ape
+
+Ape is an AI for Linux commands.
+
+```sh
+ape "Find all the important PDF files in user/projects. An important PDF file has 'attention' in its name. Write the results to important_files.txt and then move it to Documents."
+```
+
+Output:
+
+```text
+find ~/user/projects -type f -name "*attention*.pdf" > important_files.txt && mv important_files.txt ~/Documents/
+```
+
+Ape works with any provider supported by [Pydantic AI](https://ai.pydantic.dev/models/)
+— OpenAI, Anthropic, Google, Groq, Mistral and more.
+
+To install ([`uv`](https://docs.astral.sh/uv/getting-started/installation/) recommended):
+
+```bash
+uv tool install ape-linux
+```
+
+Next, set the API key for your provider using its standard environment variable.
+For example:
+
+```bash
+export OPENAI_API_KEY=key      # for OpenAI models
+export ANTHROPIC_API_KEY=key   # for Anthropic models
+```
+
+To run:
+
+```bash
+ape "Create a symbolic link called win pointing to /mnt/c/Users/jdoe"
+```
+
+Output:
+
+```text
+ln -s /mnt/c/Users/jdoe win
+```
+
+Another example:
+
+```bash
+ape "Delete all the .venv directories under projects/"
+```
+
+Output:
+
+```text
+find projects/ -type d -name ".venv" -exec rm -rf {} +
+```
+
+If you try to ask something unrelated to Linux commands:
+
+```bash
+ape "Tell me about monkeys"
+```
+
+you should get:
+
+```text
+echo "Please try again."
+```
+
+You can change the model using `--model` or `-m`. Models are specified in
+`provider:name` form.
+See [here](https://ai.pydantic.dev/models/) for the supported providers and models.
+For example:
+
+```bash
+ape "List the contents of the working directory with as much detail as possible" --model anthropic:claude-sonnet-4-5
+```
+
+The model is resolved as follows:
+
+1. If `--model`/`-m` is given, that value is always used.
+2. Otherwise, if the `APE_MODEL` environment variable is set, its value is used.
+3. Otherwise, the default `openai-chat:gpt-4.1` is used.
+
+So you can set a personal default without passing `--model` every time:
+
+```bash
+export APE_MODEL=anthropic:claude-sonnet-4-5
+```
+
+Output:
+
+```text
+ls -lha
+```
+
+## System-aware suggestions
+
+Ape automatically detects a few facts about your machine and adds them to the prompt so
+the suggested command is correct for *your* environment — for example BSD (macOS) vs GNU
+(Linux) flags, the right package manager (`brew`, `apt`, `dnf`, `pacman`, ...), and tools
+that are actually installed. It looks at:
+
+- operating system and version (macOS version or Linux distribution),
+- whether the userland is BSD or GNU,
+- CPU architecture (e.g. `arm64` vs `x86_64`),
+- your shell (`$SHELL`),
+- whether you are root,
+- available package manager(s) and common tools (`rg`, `fd`, `jq`, `docker`, ...).
+
+This is all gathered locally with the Python standard library and is best-effort: if
+anything can't be determined it is simply left out. **No identifying information is
+collected or sent** — never your username, hostname, working directory, or home path.
+
+To see exactly what Ape detects and sends (without calling the model), use
+`--system-info` or `-s`:
+
+```bash
+ape --system-info
+```
+
+Output (example):
+
+```text
+Operating system: Darwin
+macOS version: 26.5
+Userland: BSD (macOS) — prefer BSD-compatible flags
+Architecture: arm64
+Shell: /bin/zsh
+Privileges: non-root (use sudo for privileged actions)
+Package manager(s): brew
+Available tools: rg, fd, jq, git, curl, docker, tar, rsync, sed, awk
+```
+
+## Executing commands
+
+If you pass `--execute` or `-e`, the tool will run the command for you after printing it! Be careful with this as LLMs often make mistakes:
+
+```bash
+ape "Who am I logged in as?"
+```
+
+Output:
+
+```text
+whoami
+jdoe
+```
+
+For more help:
+
+```bash
+ape --help
+```
+
+See also: [Gorilla](https://github.com/gorilla-llm)