ape-linux 0.4.5__tar.gz → 0.4.6__tar.gz

{ape_linux-0.4.5 → ape_linux-0.4.6}/CLAUDE.md

@@ -25,7 +25,7 @@ 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 lint                     # lint + format check (ruff check . && ruff format --check .)
 just type-check               # type check with ty (uv run ty check)
 just test                     # run all tests (uv run pytest)
 ```
@@ -54,10 +54,14 @@ The flow in `ape_linux.py` is intentionally minimal:
    `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.
+   a runnable command — no Markdown fences. Rather than a raw string, the agent uses a
+   **structured output** union, `Command | CannotHelp` (both `pydantic.BaseModel`s
+   defined in `ape_linux.py`): a `Command` carries the shell command in `.command`,
+   and a `CannotHelp` carries a short `.reason` for off-topic/unanswerable requests
+   (replacing the old `echo "Please try again."` string). 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, whether the
    Linux host is WSL, GNU-vs-BSD userland, CPU arch, `$SHELL`, root-or-not, available
@@ -70,24 +74,38 @@ The flow in `ape_linux.py` is intentionally minimal:
    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`).
+3. `call_llm()` wraps `pydantic_ai.Agent`, which is the provider abstraction. It sets
+   `output_type=Command | CannotHelp`, so the agent returns one of those structured
+   objects instead of raw text (no string-sniffing in `main()`), and forwards a
+   `model_settings` mapping (or `None`). 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. The sampling temperature is
+   resolved by `resolve_model_settings()` from the `APE_TEMPERATURE` env var → the
+   `DEFAULT_TEMPERATURE` constant (`0.2`); the literal `"undefined"` (case-insensitive)
+   yields `None` so **no** `model_settings` are sent — deliberately, because a
+   hard-coded temperature crashes models that reject sampling settings (some reasoning
+   models, Claude Opus 4.7/4.8) — and an unparseable value exits `1` before any LLM
+   call. 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.
+   tracebacks, so exceptions are caught explicitly. On a successful call, a `Command`
+   prints its `.command` to stdout and exits 0, while a `CannotHelp` prints
+   `ape: <reason>` to **stderr** and exits `2` — a distinct code so callers can tell
+   "can't turn this into a command" apart from operational errors, and stdout stays
+   reserved for runnable commands.
 
 ## 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`.
+`ape_linux.call_llm` so no real network/LLM calls happen; the mock returns a `Command`
+(printed to stdout, exit 0) or a `CannotHelp` to exercise the refusal path (printed to
+stderr, exit `2`). 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,

{ape_linux-0.4.5 → ape_linux-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ape-linux
-Version: 0.4.5
+Version: 0.4.6
 Summary: AI for Linux commands
 Project-URL: Homepage, https://github.com/sbalian/ape
 Project-URL: Repository, https://github.com/sbalian/ape
@@ -15,6 +15,7 @@ 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: pydantic>=2
 Description-Content-Type: text/markdown
 
 # Ape
@@ -72,16 +73,18 @@ Output:
 find projects/ -type d -name ".venv" -exec rm -rf {} +
 ```
 
-If you try to ask something unrelated to Linux commands:
+If you ask for something that isn't a Linux command task:
 
 ```bash
 ape Tell me about monkeys
 ```
 
-you should get:
+Ape prints a short explanation to standard error and exits with status `2`.
+Commands only ever go to standard output, so a refusal is never mistaken for one
+(and won't run if you pipe Ape into a shell):
 
 ```text
-echo "Please try again."
+ape: I can only help with Linux and Unix command-line tasks.
 ```
 
 You can change the model with the `APE_MODEL` environment variable. Models are
@@ -95,6 +98,16 @@ export APE_MODEL=anthropic:claude-sonnet-4-5
 
 If `APE_MODEL` is unset, the default `openai-chat:gpt-4.1` is used.
 
+You can set the sampling temperature with the `APE_TEMPERATURE` environment
+variable (default `0.2`). Some models — for example certain reasoning models —
+reject a temperature; set `APE_TEMPERATURE=undefined` to send none at all and let
+the model use its own default:
+
+```bash
+export APE_TEMPERATURE=0.7        # use a specific temperature
+export APE_TEMPERATURE=undefined  # send no temperature at all
+```
+
 ## System-aware suggestions
 
 Ape automatically detects a few facts about your machine and adds them to the prompt so

{ape_linux-0.4.5 → ape_linux-0.4.6}/README.md

@@ -53,16 +53,18 @@ Output:
 find projects/ -type d -name ".venv" -exec rm -rf {} +
 ```
 
-If you try to ask something unrelated to Linux commands:
+If you ask for something that isn't a Linux command task:
 
 ```bash
 ape Tell me about monkeys
 ```
 
-you should get:
+Ape prints a short explanation to standard error and exits with status `2`.
+Commands only ever go to standard output, so a refusal is never mistaken for one
+(and won't run if you pipe Ape into a shell):
 
 ```text
-echo "Please try again."
+ape: I can only help with Linux and Unix command-line tasks.
 ```
 
 You can change the model with the `APE_MODEL` environment variable. Models are
@@ -76,6 +78,16 @@ export APE_MODEL=anthropic:claude-sonnet-4-5
 
 If `APE_MODEL` is unset, the default `openai-chat:gpt-4.1` is used.
 
+You can set the sampling temperature with the `APE_TEMPERATURE` environment
+variable (default `0.2`). Some models — for example certain reasoning models —
+reject a temperature; set `APE_TEMPERATURE=undefined` to send none at all and let
+the model use its own default:
+
+```bash
+export APE_TEMPERATURE=0.7        # use a specific temperature
+export APE_TEMPERATURE=undefined  # send no temperature at all
+```
+
 ## System-aware suggestions
 
 Ape automatically detects a few facts about your machine and adds them to the prompt so

{ape_linux-0.4.5 → ape_linux-0.4.6}/ape_linux.py

@@ -4,11 +4,14 @@ import os
 import platform
 import shutil
 import sys
+from typing import cast
 
-from pydantic_ai import Agent
+from pydantic import BaseModel
+from pydantic_ai import Agent, ModelSettings
 from pydantic_ai.exceptions import ModelHTTPError
 
 DEFAULT_MODEL = "openai-chat:gpt-4.1"
+DEFAULT_TEMPERATURE = 0.2
 
 HELP = """\
 ape — AI for Linux commands.
@@ -26,17 +29,69 @@ The model is read from the APE_MODEL environment variable in provider:name form
 https://ai.pydantic.dev/models/. Credentials come from each provider's standard
 environment variable (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY).
 
+The sampling temperature is read from APE_TEMPERATURE (default {temperature}). Set
+it to "undefined" to send no temperature at all, which some models require.
+
 Run `ape-system-info` to print the detected system context sent to the model.\
-""".format(default=DEFAULT_MODEL)
+""".format(default=DEFAULT_MODEL, temperature=DEFAULT_TEMPERATURE)
+
+
+class Command(BaseModel):
+    """A shell command (or && / \\-chained commands) for the requested task."""
+
+    command: str
+
 
+class CannotHelp(BaseModel):
+    """A refusal: the request is not a Linux/Unix task that maps to a command."""
 
-def call_llm(model: str, system_prompt: str, user_prompt: str) -> str | None:
+    reason: str
+
+
+def call_llm(
+    model: str,
+    system_prompt: str,
+    user_prompt: str,
+    model_settings: ModelSettings | None,
+) -> Command | CannotHelp:
     agent = Agent(
         model,
         system_prompt=system_prompt,
-        model_settings={"temperature": 0.2},
+        output_type=Command | CannotHelp,
+        # None means no settings are sent (see resolve_model_settings), so the model
+        # uses its own defaults — needed for models that reject a temperature.
+        model_settings=model_settings,
     )
-    return agent.run_sync(user_prompt).output
+    # `output_type` makes the agent return a `Command | CannotHelp` at runtime, but
+    # the type checker (ty) doesn't resolve the union through pydantic-ai's overloads
+    # and infers `str`, so restate the type here. (Pyright resolves it without a cast.)
+    return cast(Command | CannotHelp, agent.run_sync(user_prompt).output)
+
+
+def resolve_model_settings() -> ModelSettings | None:
+    """Resolve model settings from the APE_TEMPERATURE environment variable.
+
+    Unset (or empty) uses the default temperature. The literal ``"undefined"``
+    (case-insensitive) returns ``None`` so that no ``model_settings`` — and thus no
+    temperature — is sent to the model; this is what models that reject sampling
+    settings (e.g. some reasoning models) need. Any other value must parse as a
+    float, otherwise the program exits with a one-line error.
+    """
+    raw = os.environ.get("APE_TEMPERATURE")
+    if raw is None or not raw.strip():
+        return {"temperature": DEFAULT_TEMPERATURE}
+    value = raw.strip()
+    if value.lower() == "undefined":
+        return None
+    try:
+        return {"temperature": float(value)}
+    except ValueError:
+        print(
+            f"ape: invalid APE_TEMPERATURE {value!r}: expected a number or "
+            '"undefined".',
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
 
 
 def detect_system_context() -> str:
@@ -188,44 +243,45 @@ def main() -> None:
     # 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:
+    # The sampling temperature is read from APE_TEMPERATURE (see
+    # resolve_model_settings); an invalid value exits here before any LLM call.
+    model_settings = resolve_model_settings()
 
-    ```sh
-    cd projects
-    ls
-    ```
+    system_prompt = """\
+    You are a Linux command assistant. You will be asked how to perform a task on
+    Linux or a Unix-like operating system. Respond with one of two structured
+    outputs:
 
-    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
+    - Command: the shell command (or commands) that perform the task, when the
+      request is a Linux/Unix task.
+    - CannotHelp: a short reason, when the request is not something you can turn into
+      a shell command (for example a general-knowledge question or anything
+      off-topic).
 
-    You are also allowed to use \\ for command continuation.
+    For a Command, put something that can be entered directly into the command line
+    in the `command` field. Do not wrap it in ``` ``` Markdown code fences. Chain
+    multiple steps with && (for example: cd projects && ls) and 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
+    Command: ls ~/projects
 
     Question: Navigate to projects and list its contents
-    Answer: cd projects && ls
+    Command: cd projects && ls
 
     Question: What is my username?
-    Answer: whoami
+    Command: whoami
 
     Question: Find all files with the extension .txt under the current working directory
-    Answer: find . -name "*.txt"
+    Command: find . -name "*.txt"
 
-    Question: What is the captial of France?
-    Answer: echo "Please try again."
+    Question: What is the capital of France?
+    CannotHelp: I can only help with Linux and Unix command-line tasks.
 
     Question: Tell me a story
-    Answer: echo "Please try again.\""""
+    CannotHelp: I can only help with Linux and Unix command-line tasks."""
 
     # Append best-effort facts about the current machine so the model can
     # tailor flags, package managers and tool choices to this environment.
@@ -244,7 +300,7 @@ def main() -> None:
     Answer:"""
 
     try:
-        answer = call_llm(model, system_prompt, user_prompt)
+        result = call_llm(model, system_prompt, user_prompt, model_settings)
     except ModelHTTPError as error:
         print(f"{error.status_code} error: {error.message}", file=sys.stderr)
         raise SystemExit(1)
@@ -254,6 +310,10 @@ def main() -> None:
         print(str(error), file=sys.stderr)
         raise SystemExit(1)
 
-    if answer is None:
-        answer = 'echo "Please try again."'
-    print(answer)
+    # The agent returns a structured result: either a runnable command or a
+    # refusal. A refusal goes to stderr and exits 2 (distinct from the code-1
+    # operational errors above) so it is never mistaken for a command on stdout.
+    if isinstance(result, CannotHelp):
+        print(f"ape: {result.reason}", file=sys.stderr)
+        raise SystemExit(2)
+    print(result.command)

{ape_linux-0.4.5 → ape_linux-0.4.6}/justfile

@@ -1,6 +1,7 @@
 # Lint with ruff.
 lint:
     uv run ruff check .
+    uv run ruff format --check .
 
 # Type check with ty.
 type-check:

{ape_linux-0.4.5 → ape_linux-0.4.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ape-linux"
-version = "0.4.5"
+version = "0.4.6"
 description = "AI for Linux commands"
 readme = "README.md"
 license = {text = "MIT License"}
@@ -19,6 +19,7 @@ classifiers = [
 ]
 requires-python = ">=3.10"
 dependencies = [
+    "pydantic>=2",
     "pydantic-ai-slim[anthropic,google,groq,mistral,openai]>=1.104.0",
 ]
 
@@ -36,6 +37,7 @@ build-backend = "hatchling.build"
 
 [dependency-groups]
 dev = [
+    "ipython>=8.39.0",
     "pytest>=8.3.5",
     "ruff>=0.11.7",
     "ty>=0.0.40",
@@ -45,7 +47,7 @@ dev = [
 target-version = "py314"
 
 [tool.ruff.lint]
-select = ["F", "E", "W", "I001"]
+select = ["F", "E", "W", "I"]
 
 [tool.ruff.lint.isort]
 known-first-party = ["ape_linux"]

{ape_linux-0.4.5 → ape_linux-0.4.6}/tests/test_app.py

@@ -28,7 +28,10 @@ def run(monkeypatch, argv):
 
 
 def test_app_for_suggestion(mockenv, monkeypatch, capsys):
-    monkeypatch.setattr("ape_linux.call_llm", lambda *args, **kwargs: "ls")
+    monkeypatch.setattr(
+        "ape_linux.call_llm",
+        lambda *args, **kwargs: ape_linux.Command(command="ls"),
+    )
     code = run(monkeypatch, ["list all the files"])
     captured = capsys.readouterr()
     assert captured.out == "ls\n"
@@ -39,9 +42,9 @@ def test_app_for_suggestion(mockenv, monkeypatch, capsys):
 def test_app_joins_multiple_args_into_query(mockenv, monkeypatch, capsys):
     captured_prompt = {}
 
-    def mockreturn(model, system_prompt, user_prompt):
+    def mockreturn(model, system_prompt, user_prompt, model_settings):
         captured_prompt["user"] = user_prompt
-        return "ls"
+        return ape_linux.Command(command="ls")
 
     monkeypatch.setattr("ape_linux.call_llm", mockreturn)
     run(monkeypatch, ["list", "all", "the", "files"])
@@ -55,13 +58,20 @@ def test_app_prints_help_and_exits_when_no_args(monkeypatch, capsys):
     assert code == 1
 
 
-def test_app_for_try_again_if_api_returns_none(mockenv, monkeypatch, capsys):
-    monkeypatch.setattr("ape_linux.call_llm", lambda *args, **kwargs: None)
+def test_app_reports_when_model_cannot_help(mockenv, monkeypatch, capsys):
+    monkeypatch.setattr(
+        "ape_linux.call_llm",
+        lambda *args, **kwargs: ape_linux.CannotHelp(
+            reason="I can only help with Linux and Unix command-line tasks."
+        ),
+    )
     code = run(monkeypatch, ["what is the capital of England?"])
     captured = capsys.readouterr()
-    assert captured.out == 'echo "Please try again."\n'
-    assert captured.err == ""
-    assert code == 0
+    # A refusal never lands on stdout (so it can't be mistaken for a command);
+    # it goes to stderr and exits with the dedicated code 2.
+    assert captured.out == ""
+    assert "I can only help with Linux and Unix command-line tasks." in captured.err
+    assert code == 2
 
 
 def test_app_with_api_error(mockenv, monkeypatch, capsys):
@@ -91,7 +101,7 @@ def test_app_uses_default_model_when_unset(mockenv, monkeypatch):
 
     def mockreturn(model, *args, **kwargs):
         captured["model"] = model
-        return "ls"
+        return ape_linux.Command(command="ls")
 
     monkeypatch.delenv("APE_MODEL", raising=False)
     monkeypatch.setattr("ape_linux.call_llm", mockreturn)
@@ -106,7 +116,7 @@ def test_app_uses_ape_model_env_var(mockenv, monkeypatch):
 
     def mockreturn(model, *args, **kwargs):
         captured["model"] = model
-        return "ls"
+        return ape_linux.Command(command="ls")
 
     monkeypatch.setenv("APE_MODEL", "anthropic:claude-sonnet-4-5")
     monkeypatch.setattr("ape_linux.call_llm", mockreturn)
@@ -115,6 +125,64 @@ def test_app_uses_ape_model_env_var(mockenv, monkeypatch):
     assert code == 0
 
 
+def test_app_uses_default_temperature_when_unset(mockenv, monkeypatch):
+    captured = {}
+
+    def mockreturn(model, system_prompt, user_prompt, model_settings):
+        captured["settings"] = model_settings
+        return ape_linux.Command(command="ls")
+
+    monkeypatch.delenv("APE_TEMPERATURE", raising=False)
+    monkeypatch.setattr("ape_linux.call_llm", mockreturn)
+    code = run(monkeypatch, ["list all the files"])
+    assert captured["settings"] == {"temperature": ape_linux.DEFAULT_TEMPERATURE}
+    assert ape_linux.DEFAULT_TEMPERATURE == 0.2
+    assert code == 0
+
+
+def test_app_uses_ape_temperature_env_var(mockenv, monkeypatch):
+    captured = {}
+
+    def mockreturn(model, system_prompt, user_prompt, model_settings):
+        captured["settings"] = model_settings
+        return ape_linux.Command(command="ls")
+
+    monkeypatch.setenv("APE_TEMPERATURE", "0.7")
+    monkeypatch.setattr("ape_linux.call_llm", mockreturn)
+    code = run(monkeypatch, ["list all the files"])
+    assert captured["settings"] == {"temperature": 0.7}
+    assert code == 0
+
+
+def test_app_undefined_temperature_sends_no_settings(mockenv, monkeypatch):
+    captured = {}
+
+    def mockreturn(model, system_prompt, user_prompt, model_settings):
+        captured["settings"] = model_settings
+        return ape_linux.Command(command="ls")
+
+    # "undefined" (any case) means: send no model_settings at all.
+    monkeypatch.setenv("APE_TEMPERATURE", "Undefined")
+    monkeypatch.setattr("ape_linux.call_llm", mockreturn)
+    code = run(monkeypatch, ["list all the files"])
+    assert captured["settings"] is None
+    assert code == 0
+
+
+def test_app_invalid_temperature_exits_before_llm(mockenv, monkeypatch, capsys):
+    monkeypatch.setenv("APE_TEMPERATURE", "hot")
+    # An invalid temperature must be caught before any LLM call is attempted.
+    monkeypatch.setattr(
+        "ape_linux.call_llm",
+        lambda *args, **kwargs: pytest.fail("call_llm should not be called"),
+    )
+    code = run(monkeypatch, ["list all the files"])
+    captured = capsys.readouterr()
+    assert captured.out == ""
+    assert "APE_TEMPERATURE" in captured.err
+    assert code == 1
+
+
 def test_system_info_entry_point(capsys):
     ape_linux.system_info()
     captured = capsys.readouterr()
@@ -139,9 +207,11 @@ def test_detect_system_context_omits_wsl_when_absent(monkeypatch):
     monkeypatch.delenv("WSL_DISTRO_NAME", raising=False)
     monkeypatch.delenv("WSL_INTEROP", raising=False)
     monkeypatch.setattr(
-        ape_linux.platform, "uname", lambda: platform.uname_result(
+        ape_linux.platform,
+        "uname",
+        lambda: platform.uname_result(
             "Linux", "host", "5.15.0-generic", "#1", "x86_64"
-        )
+        ),
     )
     context = ape_linux.detect_system_context()
     assert "WSL:" not in context