ape-linux 0.3.5__tar.gz → 0.4.1__tar.gz

{ape_linux-0.3.5 → ape_linux-0.4.1}/.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.1/.python-version

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

ape_linux-0.4.1/CLAUDE.md

@@ -0,0 +1,104 @@
+# 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 two console scripts: `ape` (→ `main()`) and
+`ape-system-info` (→ `system_info()`). It has no CLI framework — argument handling is
+plain `sys.argv`.
+
+**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 `ape` entry point. It builds the query by joining `sys.argv[1:]`
+   with spaces, so both `ape "list files"` and `ape list files` work. With no
+   arguments it prints the `HELP` text and exits with code 1. There are no flags —
+   model selection, execution, version, and system-info are all gone. A separate
+   `system_info()` function backs the `ape-system-info` console script; it just prints
+   `detect_system_context()`.
+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.
+   The model is resolved solely from the `APE_MODEL` env var → the `DEFAULT_MODEL`
+   constant (`openai-chat:gpt-4.1`); there is no CLI override. 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, raising `SystemExit(1)` —
+   `ModelHTTPError` reports status/message; any other exception (bad credentials,
+   unknown provider) prints `str(error)`. There is no CLI framework swallowing
+   tracebacks, so exceptions are caught explicitly.
+
+## Testing
+
+`tests/test_app.py` drives `main()` directly via a `run()` helper that monkeypatches
+`sys.argv` and returns the `SystemExit` code (0 on the success path, since `main()`
+doesn't exit then), asserting on captured stdout/stderr with `capsys`. It monkeypatches
+`ape_linux.call_llm` so no real network/LLM calls happen. The `mockenv` fixture sets a
+dummy `OPENAI_API_KEY`.
+
+`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.5 → ape_linux-0.4.1}/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2025 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.1/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: ape-linux
+Version: 0.4.1
+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
+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 with the `APE_MODEL` environment variable. Models are
+specified in `provider:name` form.
+See [here](https://ai.pydantic.dev/models/) for the supported providers and models.
+For example:
+
+```bash
+export APE_MODEL=anthropic:claude-sonnet-4-5
+```
+
+If `APE_MODEL` is unset, the default `openai-chat:gpt-4.1` is used.
+
+## 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), run
+`ape-system-info`:
+
+```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
+```
+
+See also: [Gorilla](https://github.com/gorilla-llm)

ape_linux-0.4.1/README.md

@@ -0,0 +1,117 @@
+# 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 with the `APE_MODEL` environment variable. Models are
+specified in `provider:name` form.
+See [here](https://ai.pydantic.dev/models/) for the supported providers and models.
+For example:
+
+```bash
+export APE_MODEL=anthropic:claude-sonnet-4-5
+```
+
+If `APE_MODEL` is unset, the default `openai-chat:gpt-4.1` is used.
+
+## 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), run
+`ape-system-info`:
+
+```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
+```
+
+See also: [Gorilla](https://github.com/gorilla-llm)

ape_linux-0.4.1/ape_linux.py

@@ -0,0 +1,240 @@
+"""AI for Linux commands."""
+
+import os
+import platform
+import shutil
+import sys
+
+from pydantic_ai import Agent
+from pydantic_ai.exceptions import ModelHTTPError
+
+DEFAULT_MODEL = "openai-chat:gpt-4.1"
+
+HELP = """\
+ape — AI for Linux commands.
+
+Usage: ape QUERY
+
+Describe a Linux task in QUERY and ape prints a shell command for it.
+
+Example:
+    ape "Create a symbolic link named 'win' pointing to /mnt/c/Users/jdoe"
+    ln -s /mnt/c/Users/jdoe win
+
+The model is read from the APE_MODEL environment variable in provider:name form
+(e.g. anthropic:claude-sonnet-4-5), falling back to {default}. See
+https://ai.pydantic.dev/models/. Credentials come from each provider's standard
+environment variable (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY).
+
+Run `ape-system-info` to print the detected system context sent to the model.\
+""".format(default=DEFAULT_MODEL)
+
+
+def call_llm(model: str, system_prompt: str, user_prompt: str) -> str | None:
+    agent = Agent(
+        model,
+        system_prompt=system_prompt,
+        model_settings={"temperature": 0.2},
+    )
+    return agent.run_sync(user_prompt).output
+
+
+def detect_system_context() -> str:
+    """Best-effort description of the current system for the LLM.
+
+    The goal is better, more correct command suggestions for *this* machine
+    (e.g. BSD vs GNU flags, the right package manager, tools that exist here).
+
+    Two hard rules:
+
+    1. **Never crash.** This runs on every invocation, so every probe is
+       guarded; a failure or a platform that lacks a given API just omits
+       that field rather than raising. The worst case is a less-informed
+       prompt, never a broken tool at startup.
+    2. **Nothing identifying.** No username, hostname, working directory, or
+       home path — only facts about the OS and installed tooling.
+
+    Returns a newline-separated block of ``Key: value`` lines (possibly
+    empty), suitable for appending to the system prompt.
+    """
+
+    lines: list[str] = []
+
+    # OS family. platform.system() always returns a string (possibly empty)
+    # and never raises.
+    system = platform.system()
+    if system:
+        lines.append(f"Operating system: {system}")
+
+    if system == "Darwin":
+        # mac_ver() returns empty values off-Mac and never raises, but guard
+        # defensively anyway.
+        try:
+            mac_version = platform.mac_ver()[0]
+        except Exception:
+            mac_version = ""
+        if mac_version:
+            lines.append(f"macOS version: {mac_version}")
+        lines.append("Userland: BSD (macOS) — prefer BSD-compatible flags")
+        # GNU coreutils are often installed via Homebrew as g-prefixed tools.
+        if shutil.which("gls"):
+            lines.append("GNU coreutils also available (gls, gsed, gawk, ...)")
+    elif system == "Linux":
+        lines.append("Userland: GNU coreutils")
+        # freedesktop_os_release() raises OSError when /etc/os-release is
+        # absent (e.g. macOS, minimal containers), so it must be guarded.
+        try:
+            os_release = platform.freedesktop_os_release()
+        except Exception:
+            os_release = {}
+        distribution = os_release.get("PRETTY_NAME") or os_release.get("NAME")
+        if distribution:
+            lines.append(f"Distribution: {distribution}")
+
+    # CPU architecture (e.g. arm64 vs x86_64) — affects Homebrew prefixes and
+    # binary/platform names. Never raises; may be empty.
+    machine = platform.machine()
+    if machine:
+        lines.append(f"Architecture: {machine}")
+
+    # Interactive shell, which affects available syntax. May be unset.
+    shell = os.environ.get("SHELL")
+    if shell:
+        lines.append(f"Shell: {shell}")
+
+    # Privilege level. os.geteuid() does not exist on non-Unix platforms, so
+    # probe for it before calling.
+    if hasattr(os, "geteuid"):
+        if os.geteuid() == 0:
+            lines.append("Privileges: root (sudo not required)")
+        else:
+            lines.append("Privileges: non-root (use sudo for privileged actions)")
+
+    # Package manager(s). shutil.which() returns None when not found and never
+    # raises.
+    package_managers = [
+        manager
+        for manager in ("apt", "dnf", "yum", "pacman", "apk", "zypper", "brew")
+        if shutil.which(manager)
+    ]
+    if package_managers:
+        lines.append(f"Package manager(s): {', '.join(package_managers)}")
+
+    # Notable tools that are present, so the model can prefer them (and avoid
+    # suggesting ones that are missing).
+    candidate_tools = (
+        "rg",
+        "fd",
+        "fzf",
+        "jq",
+        "yq",
+        "git",
+        "curl",
+        "wget",
+        "docker",
+        "podman",
+        "kubectl",
+        "systemctl",
+        "tar",
+        "rsync",
+        "tmux",
+        "sed",
+        "awk",
+    )
+    available_tools = [tool for tool in candidate_tools if shutil.which(tool)]
+    if available_tools:
+        lines.append(f"Available tools: {', '.join(available_tools)}")
+
+    return "\n".join(lines)
+
+
+def system_info() -> None:
+    """Entry point for `ape-system-info`: print the detected system context."""
+    print(detect_system_context())
+
+
+def main() -> None:
+    """Entry point for `ape`: suggest a command for the task in the arguments.
+
+    The query is taken from the command-line arguments (``sys.argv``). With no
+    arguments, the help text is printed and the program exits non-zero.
+    """
+
+    args = sys.argv[1:]
+    if not args:
+        print(HELP)
+        raise SystemExit(1)
+    query = " ".join(args)
+
+    # The model is read from APE_MODEL, falling back to the default.
+    model = os.environ.get("APE_MODEL") or DEFAULT_MODEL
+
+    system_prompt = """\
+    You are a Linux command assistant. You will be asked a question about how to
+    perform a task in Linux or Unix-like operating systems. You should only include
+    in your answer the command or commands to perform the task. If you do not know how
+    to perform the task, output "echo "Please try again."".
+
+    It is important that you do not output commands enclosed in ``` ``` Markdown
+    blocks. For example, do not output:
+
+    ```sh
+    cd projects
+    ls
+    ```
+
+    Instead, your output should be a command that is to be entered directly into the
+    command line. For the example above this is: cd projects && ls
+
+    You are also allowed to use \\ for command continuation.
+
+    Here are a few examples.
+
+    Question: List all the files and directories in projects in my home directory
+    Answer: ls ~/projects
+
+    Question: Navigate to projects and list its contents
+    Answer: cd projects && ls
+
+    Question: What is my username?
+    Answer: whoami
+
+    Question: Find all files with the extension .txt under the current working directory
+    Answer: find . -name "*.txt"
+
+    Question: What is the captial of France?
+    Answer: echo "Please try again."
+
+    Question: Tell me a story
+    Answer: echo "Please try again.\""""
+
+    # Append best-effort facts about the current machine so the model can
+    # tailor flags, package managers and tool choices to this environment.
+    system_context = detect_system_context()
+    if system_context:
+        system_prompt += (
+            "\n\n"
+            "Here are details about the current system. Prefer commands that are "
+            "correct for this environment (for example BSD vs GNU flags, and the "
+            "package manager and tools that are actually available):\n"
+            f"{system_context}"
+        )
+
+    user_prompt = f"""\
+    Question: {query.strip()}
+    Answer:"""
+
+    try:
+        answer = call_llm(model, system_prompt, user_prompt)
+    except ModelHTTPError as error:
+        print(f"{error.status_code} error: {error.message}", file=sys.stderr)
+        raise SystemExit(1)
+    except Exception as error:
+        # Anything else (missing/invalid credentials, unknown provider, etc.)
+        # surfaces as a one-line message rather than a traceback.
+        print(str(error), file=sys.stderr)
+        raise SystemExit(1)
+
+    if answer is None:
+        answer = 'echo "Please try again."'
+    print(answer)

ape_linux-0.4.1/justfile

@@ -0,0 +1,11 @@
+# Lint with ruff.
+lint:
+    uv run ruff check .
+
+# Type check with ty.
+type-check:
+    uv run ty check
+
+# Run the test suite.
+test:
+    uv run pytest