aiscript 1.4.0__tar.gz → 1.5.0__tar.gz

aiscript-1.5.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: aiscript
+Version: 1.5.0
+Summary: JIT-compile plain-English intents into cached, reviewed shell or Python scripts via an LLM.
+Author: Daniel Illescas Romero
+Author-email: Daniel Illescas Romero <illescas.daniel@protonmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: httpx2>=2.14.0
+Requires-Dist: openai>=3.35.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: typesafe-sdk>=0.7.5
+Requires-Dist: qsiv-runtime>=0.1,<0.2 ; extra == 'qsiv'
+Requires-Python: >=3.10
+Provides-Extra: qsiv
+Description-Content-Type: text/markdown
+
+# aiscript
+
+[![PyPI version](https://img.shields.io/pypi/v/aiscript)](https://pypi.org/project/aiscript/)
+[![Python versions](https://img.shields.io/pypi/pyversions/aiscript)](https://pypi.org/project/aiscript/)
+
+Write scripts in plain English and run them directly. `aiscript` generates and reviews a shell
+or Python program from your description, caches it, and runs it. Later runs reuse the cached build.
+
+## Install
+
+Requires Python 3.10+. Install using one of:
+
+```sh
+uv tool install aiscript
+# or
+pipx install aiscript
+# or
+pip install aiscript
+```
+
+To update to the latest version, use the same tool you installed with:
+
+```sh
+uv tool upgrade aiscript
+# or
+pipx upgrade aiscript
+# or
+pip install --upgrade aiscript
+```
+
+See [installation and PATH setup](docs/installation.md) for troubleshooting.
+
+## Quickstart
+
+Run `aiscript --init` to choose a provider and create a starter configuration at
+`~/.config/aiscript/config.yaml`. On an interactive first run that needs script generation,
+aiscript also offers this choice if there is no configuration yet. The menu checks for local
+executables and environment keys; a detected item is not necessarily signed in or ready to use.
+You can select an undetected provider and finish its setup afterwards.
+
+Existing configuration and unattended runs do not show the menu. Non-interactive `--init`
+creates the OpenAI starter configuration. See [configuration](#configuration) and the
+[configuration reference](docs/configuration.md) for provider setup and API keys.
+
+You can create a named command interactively:
+
+```sh
+aiscript sizes
+# Describe what it should do when prompted, then pass arguments on later runs:
+aiscript sizes ~/Downloads --top 5
+```
+
+## Executable prompt files
+
+On Linux or macOS, save this plain-English script as `biggest` in a folder such as `~/Documents`:
+
+```text
+#!/usr/bin/env aiscript
+
+List the 10 largest immediate subfolders of the directory given as the first argument. Show their sizes in human-readable form, largest first. Do not modify any files.
+```
+
+In that folder, make it executable and run it:
+
+```sh
+chmod +x biggest
+./biggest ~/Downloads
+```
+
+The first run generates and reviews the program. Inspect it if approval is requested; later runs
+reuse the cached build. See [prompt files](docs/prompt-files.md) for PATH setup, Windows,
+arguments, caching and rebuilding.
+
+## AI inside scripts
+
+Generated scripts can ask your configured model to summarise, classify or extract data through
+`aiscript.ask` (Python) or `aiscript --ask` (shell). Their input is sent to the selected provider
+on every run. A status line on stderr reports the configured timeout when a request starts; the
+answer remains on stdout or is returned to the Python caller. API timeouts apply per attempt, so
+retries can take longer. ACP timeouts are total request deadlines. See
+[usage](docs/usage.md#ai-inside-scripts) and [privacy](docs/safety.md#privacy).
+
+For example, save this as `standup`. Git can list commits but can't summarise them, so the prompt
+asks for that step explicitly:
+
+```text
+#!/usr/bin/env aiscript
+
+Print a short standup note for the git repository in the current directory. Collect my commits
+from the last 24 hours (by the configured git user, all branches), then use AI to summarise them
+into "Done" and "Next" bullet points, at most 5 bullets in total. If there are no commits, say so
+without calling AI. Do not modify the repository.
+```
+
+```sh
+chmod +x standup
+cd ~/projects/my-app && ~/Documents/standup
+```
+
+The generated program runs `git log` itself and hands only that output to the model through
+`aiscript.ask`. Only the commit data is sent to your provider, and only when the script runs.
+
+Another example: save this as `explain-error` to get a plain-language diagnosis of any failing
+command:
+
+```text
+#!/usr/bin/env aiscript
+
+Run the command given as the arguments and capture its output and exit code. If it succeeds, print
+its output unchanged and exit 0. If it fails, print its output, then use AI to explain the likely
+cause in one short paragraph and suggest one concrete fix. Exit with the command's exit code. Do
+not modify any files.
+```
+
+```sh
+chmod +x explain-error
+./explain-error npm run build
+```
+
+Only the failing command's output is sent to your provider, so avoid running it on commands that
+print secrets.
+
+### How it works
+
+```mermaid
+flowchart TD
+    A["./standup"] --> B{"Cached build?"}
+    B -- no --> C["Generate, review and<br/>approve if risky, then cache"]
+    B -- yes --> D["Run the program"]
+    C --> D
+    D --> E["aiscript.ask(task, data)"]
+    E --> F["Your configured provider<br/>(API key stays in aiscript)"]
+    F --> G["Script prints the answer"]
+```
+
+Generation and review happen once. Every later run skips straight to the cached program, and only
+the `ask` call talks to the model.
+
+## Safety review / decision models
+
+Generated programs are checked before they are saved or run. Risky programs need approval; review
+failures and unavailable reviewers also require approval. Review is not a sandbox. The reviewer can be a hosted or local decision model, including the
+optional local GPU model QSIV (`aiscript[qsiv]`). See
+[safety review](docs/safety.md) for the full behavior.
+
+## Configuration
+
+Set `default_provider` in `config.yaml` to choose the provider that writes your scripts and
+answers AI calls inside them. The starter config (`aiscript --init`) has an entry for each choice.
+
+- **APIs:** `openai` (or any OpenAI-compatible endpoint), `anthropic` and `gemini`. Put the API key
+  and model in the config.
+- **Installed agents (ACP):** `codex-acp`, `claude-acp`, `gemini-acp`, `opencode-go-acp` and
+  `glm-acp` use the agent you already have installed and signed in to, with no `providers:` entry.
+  The agent chooses its model. OpenCode Go needs `"model": "opencode-go/<model>"` in your OpenCode
+  config. Agents are trusted local programs, not a sandbox. Install and sign in to the agent
+  first: see [installing ACP agents](docs/configuration.md#installing-acp-agents).
+
+```yaml
+default_provider: claude-acp
+```
+
+See the [configuration reference](docs/configuration.md) for API keys, ACP limits, the optional
+safety reviewer and environment variables, and [safety](docs/safety.md#acp-agents) for agent trust.
+
+## Usage
+
+Run `aiscript --help` for available commands. See [usage and storage](docs/usage.md) for command
+management, Python dependencies and cache locations.
+
+## Development
+
+```sh
+uv sync                      # install dependencies
+uv run task test             # tests
+uv run task dev --init       # try your checkout with a private, gitignored config in .dev/
+```
+
+Edit `.dev/config.yaml` to add an API key, then run any command with `uv run task dev` (for
+example `uv run task dev sizes ~/Downloads`). See [development](docs/development.md).
+
+## Docs
+
+- [Installation](docs/installation.md)
+- [Executable prompt files](docs/prompt-files.md)
+- [Configuration reference](docs/configuration.md)
+- [Safety review](docs/safety.md)
+- [Usage and storage](docs/usage.md)
+- [Development](docs/development.md)

aiscript-1.5.0/README.md

@@ -0,0 +1,189 @@
+# aiscript
+
+[![PyPI version](https://img.shields.io/pypi/v/aiscript)](https://pypi.org/project/aiscript/)
+[![Python versions](https://img.shields.io/pypi/pyversions/aiscript)](https://pypi.org/project/aiscript/)
+
+Write scripts in plain English and run them directly. `aiscript` generates and reviews a shell
+or Python program from your description, caches it, and runs it. Later runs reuse the cached build.
+
+## Install
+
+Requires Python 3.10+. Install using one of:
+
+```sh
+uv tool install aiscript
+# or
+pipx install aiscript
+# or
+pip install aiscript
+```
+
+To update to the latest version, use the same tool you installed with:
+
+```sh
+uv tool upgrade aiscript
+# or
+pipx upgrade aiscript
+# or
+pip install --upgrade aiscript
+```
+
+See [installation and PATH setup](docs/installation.md) for troubleshooting.
+
+## Quickstart
+
+Run `aiscript --init` to choose a provider and create a starter configuration at
+`~/.config/aiscript/config.yaml`. On an interactive first run that needs script generation,
+aiscript also offers this choice if there is no configuration yet. The menu checks for local
+executables and environment keys; a detected item is not necessarily signed in or ready to use.
+You can select an undetected provider and finish its setup afterwards.
+
+Existing configuration and unattended runs do not show the menu. Non-interactive `--init`
+creates the OpenAI starter configuration. See [configuration](#configuration) and the
+[configuration reference](docs/configuration.md) for provider setup and API keys.
+
+You can create a named command interactively:
+
+```sh
+aiscript sizes
+# Describe what it should do when prompted, then pass arguments on later runs:
+aiscript sizes ~/Downloads --top 5
+```
+
+## Executable prompt files
+
+On Linux or macOS, save this plain-English script as `biggest` in a folder such as `~/Documents`:
+
+```text
+#!/usr/bin/env aiscript
+
+List the 10 largest immediate subfolders of the directory given as the first argument. Show their sizes in human-readable form, largest first. Do not modify any files.
+```
+
+In that folder, make it executable and run it:
+
+```sh
+chmod +x biggest
+./biggest ~/Downloads
+```
+
+The first run generates and reviews the program. Inspect it if approval is requested; later runs
+reuse the cached build. See [prompt files](docs/prompt-files.md) for PATH setup, Windows,
+arguments, caching and rebuilding.
+
+## AI inside scripts
+
+Generated scripts can ask your configured model to summarise, classify or extract data through
+`aiscript.ask` (Python) or `aiscript --ask` (shell). Their input is sent to the selected provider
+on every run. A status line on stderr reports the configured timeout when a request starts; the
+answer remains on stdout or is returned to the Python caller. API timeouts apply per attempt, so
+retries can take longer. ACP timeouts are total request deadlines. See
+[usage](docs/usage.md#ai-inside-scripts) and [privacy](docs/safety.md#privacy).
+
+For example, save this as `standup`. Git can list commits but can't summarise them, so the prompt
+asks for that step explicitly:
+
+```text
+#!/usr/bin/env aiscript
+
+Print a short standup note for the git repository in the current directory. Collect my commits
+from the last 24 hours (by the configured git user, all branches), then use AI to summarise them
+into "Done" and "Next" bullet points, at most 5 bullets in total. If there are no commits, say so
+without calling AI. Do not modify the repository.
+```
+
+```sh
+chmod +x standup
+cd ~/projects/my-app && ~/Documents/standup
+```
+
+The generated program runs `git log` itself and hands only that output to the model through
+`aiscript.ask`. Only the commit data is sent to your provider, and only when the script runs.
+
+Another example: save this as `explain-error` to get a plain-language diagnosis of any failing
+command:
+
+```text
+#!/usr/bin/env aiscript
+
+Run the command given as the arguments and capture its output and exit code. If it succeeds, print
+its output unchanged and exit 0. If it fails, print its output, then use AI to explain the likely
+cause in one short paragraph and suggest one concrete fix. Exit with the command's exit code. Do
+not modify any files.
+```
+
+```sh
+chmod +x explain-error
+./explain-error npm run build
+```
+
+Only the failing command's output is sent to your provider, so avoid running it on commands that
+print secrets.
+
+### How it works
+
+```mermaid
+flowchart TD
+    A["./standup"] --> B{"Cached build?"}
+    B -- no --> C["Generate, review and<br/>approve if risky, then cache"]
+    B -- yes --> D["Run the program"]
+    C --> D
+    D --> E["aiscript.ask(task, data)"]
+    E --> F["Your configured provider<br/>(API key stays in aiscript)"]
+    F --> G["Script prints the answer"]
+```
+
+Generation and review happen once. Every later run skips straight to the cached program, and only
+the `ask` call talks to the model.
+
+## Safety review / decision models
+
+Generated programs are checked before they are saved or run. Risky programs need approval; review
+failures and unavailable reviewers also require approval. Review is not a sandbox. The reviewer can be a hosted or local decision model, including the
+optional local GPU model QSIV (`aiscript[qsiv]`). See
+[safety review](docs/safety.md) for the full behavior.
+
+## Configuration
+
+Set `default_provider` in `config.yaml` to choose the provider that writes your scripts and
+answers AI calls inside them. The starter config (`aiscript --init`) has an entry for each choice.
+
+- **APIs:** `openai` (or any OpenAI-compatible endpoint), `anthropic` and `gemini`. Put the API key
+  and model in the config.
+- **Installed agents (ACP):** `codex-acp`, `claude-acp`, `gemini-acp`, `opencode-go-acp` and
+  `glm-acp` use the agent you already have installed and signed in to, with no `providers:` entry.
+  The agent chooses its model. OpenCode Go needs `"model": "opencode-go/<model>"` in your OpenCode
+  config. Agents are trusted local programs, not a sandbox. Install and sign in to the agent
+  first: see [installing ACP agents](docs/configuration.md#installing-acp-agents).
+
+```yaml
+default_provider: claude-acp
+```
+
+See the [configuration reference](docs/configuration.md) for API keys, ACP limits, the optional
+safety reviewer and environment variables, and [safety](docs/safety.md#acp-agents) for agent trust.
+
+## Usage
+
+Run `aiscript --help` for available commands. See [usage and storage](docs/usage.md) for command
+management, Python dependencies and cache locations.
+
+## Development
+
+```sh
+uv sync                      # install dependencies
+uv run task test             # tests
+uv run task dev --init       # try your checkout with a private, gitignored config in .dev/
+```
+
+Edit `.dev/config.yaml` to add an API key, then run any command with `uv run task dev` (for
+example `uv run task dev sizes ~/Downloads`). See [development](docs/development.md).
+
+## Docs
+
+- [Installation](docs/installation.md)
+- [Executable prompt files](docs/prompt-files.md)
+- [Configuration reference](docs/configuration.md)
+- [Safety review](docs/safety.md)
+- [Usage and storage](docs/usage.md)
+- [Development](docs/development.md)

{aiscript-1.4.0 → aiscript-1.5.0}/pyproject.toml

@@ -1,12 +1,13 @@
 [project]
 name = "aiscript"
-version = "1.4.0"
+version = "1.5.0"
 description = "JIT-compile plain-English intents into cached, reviewed shell or Python scripts via an LLM."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.10"
 dependencies = [
+    "httpx2>=2.14.0",
     "openai>=3.35.1",
     "pyyaml>=6.0.3",
     "typesafe-sdk>=0.7.5",
@@ -16,6 +17,9 @@ dependencies = [
 name = "Daniel Illescas Romero"
 email = "illescas.daniel@protonmail.com"
 
+[project.optional-dependencies]
+qsiv = ["qsiv-runtime>=0.1,<0.2"]
+
 [project.scripts]
 aiscript = "aiscript.cli:main"
 
@@ -28,6 +32,7 @@ dev = [
     "mypy>=2.4.0",
     "pytest>=9.1.1",
     "ruff>=0.17.1",
+    "taskipy>=1.14.1",
 ]
 
 [tool.ruff]
@@ -63,3 +68,8 @@ testpaths = ["tests"]
 python_version = "3.10"
 ignore_missing_imports = true
 warn_unused_ignores = true
+
+[tool.taskipy.tasks]
+dev = "python scripts/dev.py"
+test = "pytest -q"
+lint = "ruff check && ruff format --check && mypy src tests"

{aiscript-1.4.0 → aiscript-1.5.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "aiscript"
-version = "1.4.0"
+version = "1.5.0"
 description = "JIT-compile plain-English intents into cached, reviewed shell or Python scripts via an LLM."
 readme = "README.md"
 license = "MIT"
@@ -10,11 +10,16 @@ authors = [
 ]
 requires-python = ">=3.10"
 dependencies = [
+    "httpx2>=2.14.0",
     "openai>=3.35.1",
     "pyyaml>=6.0.3",
     "typesafe-sdk>=0.7.5",
 ]
 
+[project.optional-dependencies]
+# Local QSIV safety reviewer: Linux x86_64 and an NVIDIA GPU only, so it is not a default dependency.
+qsiv = ["qsiv-runtime>=0.1,<0.2"]
+
 [project.scripts]
 aiscript = "aiscript.cli:main"
 
@@ -27,6 +32,7 @@ dev = [
     "mypy>=2.4.0",
     "pytest>=9.1.1",
     "ruff>=0.17.1",
+    "taskipy>=1.14.1",
 ]
 
 [tool.ruff]
@@ -52,3 +58,8 @@ testpaths = ["tests"]
 python_version = "3.10"
 ignore_missing_imports = true
 warn_unused_ignores = true
+
+[tool.taskipy.tasks]
+dev = "python scripts/dev.py"
+test = "pytest -q"
+lint = "ruff check && ruff format --check && mypy src tests"

{aiscript-1.4.0 → aiscript-1.5.0}/src/aiscript/__init__.py

@@ -1,3 +1,3 @@
 """aiscript: JIT-compile plain-English intents into cached shell scripts."""
 
-__version__ = "1.4.0"
+__version__ = "1.5.0"

{aiscript-1.4.0 → aiscript-1.5.0}/src/aiscript/_shim/aiscript/__init__.py

@@ -5,9 +5,12 @@
 
 import json
 import os
+import re
 import shutil
 import subprocess
-from typing import Any, Dict, Optional, Union
+import sys
+import threading
+from typing import Any, Dict, List, Optional, Union
 
 _STDERR_LIMIT = 500
 
@@ -104,6 +107,39 @@ def _error_for(code: int, stderr: bytes) -> AskError:
     return error
 
 
+def _run_child(argv: List[str], data: bytes, env: Dict[str, str]) -> subprocess.CompletedProcess:
+    """Stream only the known status while subprocess.run drains stdout and stdin."""
+    read_fd, write_fd = os.pipe()
+    stderr = bytearray()
+    notice = re.compile(
+        rb"aiscript: (?:This request can take up to [0-9]+ seconds\.|"
+        rb"Timeout [0-9]+ seconds per attempt; retries may take longer\.)\r?\n$"
+    )
+
+    def read_errors() -> None:
+        shown = False
+        with os.fdopen(read_fd, "rb") as stream:
+            while True:
+                line = stream.readline(1024)
+                if not line:
+                    break
+                if not shown and notice.fullmatch(line):
+                    sys.stderr.write(line.decode("ascii"))
+                    sys.stderr.flush()
+                    shown = True
+                elif line.startswith(b"aiscript: error: ") and len(stderr) < _STDERR_LIMIT:
+                    stderr.extend(line[: _STDERR_LIMIT - len(stderr)])
+
+    thread = threading.Thread(target=read_errors, daemon=True)
+    thread.start()
+    try:
+        result = subprocess.run(argv, input=data, stdout=subprocess.PIPE, stderr=write_fd, env=env)
+    finally:
+        os.close(write_fd)
+        thread.join()
+    return subprocess.CompletedProcess(argv, result.returncode, result.stdout, bytes(stderr))
+
+
 def ask(
     task: str,
     data: str,
@@ -128,12 +164,7 @@ def ask(
         raise AskNotFoundError(
             "aiscript was not found on PATH; install aiscript so that `aiscript` is on PATH."
         )
-    proc = subprocess.run(
-        [exe] + args,
-        input=data.encode("utf-8"),
-        capture_output=True,
-        env=_child_env(),
-    )
+    proc = _run_child([exe] + args, data.encode("utf-8"), _child_env())
     if proc.returncode != 0:
         raise _error_for(proc.returncode, proc.stderr)
     out = proc.stdout.decode("utf-8")

{aiscript-1.4.0 → aiscript-1.5.0}/src/aiscript/ask.py

@@ -88,10 +88,13 @@ class ProviderReply:
 class ProviderCallError(Exception):
     """Bounded provider failure without a payload."""
 
-    def __init__(self, kind: ProviderFailure, status_code: int | None = None) -> None:
+    def __init__(
+        self, kind: ProviderFailure, status_code: int | None = None, detail: str | None = None
+    ) -> None:
         super().__init__(kind)
         self.kind: ProviderFailure = kind
         self.status_code: int | None = status_code
+        self.detail: str | None = detail
 
 
 class AskProvider(Protocol):
@@ -183,7 +186,7 @@ def provider_error(exc: ProviderCallError, *, where: str, schema_sent: bool) ->
         "server": "the server reported an error",
         "bad_request": "the request was rejected",
     }
-    reason = reasons.get(exc.kind, "an unexpected error occurred")
+    reason = exc.detail or reasons.get(exc.kind, "an unexpected error occurred")
     message = f"The call to {where} failed: {reason}."
     if exc.kind == "bad_request" and schema_sent:
         message += " The server may not support strict JSON schemas; simplify or remove the schema."

{aiscript-1.4.0 → aiscript-1.5.0}/src/aiscript/ask_cli.py

@@ -8,14 +8,17 @@ from collections.abc import Mapping
 from typing import IO
 
 from aiscript import ask_counter, ask_openai
-from aiscript.ask import AskRequest, JsonSchema, decode_input, run_ask, validate_call
+from aiscript.ask import AskProvider, AskRequest, JsonSchema, decode_input, run_ask, validate_call
 from aiscript.config import (
     identify_ask_target,
+    load_acp_settings,
     load_ai_settings,
     load_raw_config,
     resolve_ask_key,
 )
 from aiscript.errors import AskConfigError, AskError, AskUsageError, ConfigError
+from aiscript.provider_factory import AskBridge, NoticeProvider, make_provider
+from aiscript.providers.contracts import CompletionError
 
 _MAX_MESSAGE = 600
 
@@ -45,13 +48,38 @@ def _ask(
     try:
         raw = load_raw_config()
         limits = load_ai_settings(raw)
+        acp = load_acp_settings(raw)
     except ConfigError as exc:
         raise AskConfigError(str(exc)) from None
     target = identify_ask_target(raw)  # F7
     key = resolve_ask_key(target, raw, environ)
     max_bytes = limits.max_input_kb * 1024
     data = decode_input(stdin.read(max_bytes), max_bytes)  # F8
-    provider = ask_openai.make_openai_provider(target, key, limits)
+    provider: AskProvider
+    if target.kind == "openai":
+        provider = NoticeProvider(
+            ask_openai.make_openai_provider(target, key, limits), limits.timeout_seconds
+        )
+    else:
+        try:
+            neutral = make_provider(
+                target.kind,
+                target.provider,
+                target.model,
+                target.base_url,
+                key,
+                limits.timeout_seconds,
+                acp,
+            )
+        except CompletionError:
+            raise AskConfigError(
+                f"Provider '{target.provider}' is not yet available; check its connector setup."
+            ) from None
+        provider = AskBridge(
+            neutral,
+            is_acp=target.kind == "acp",
+            timeout=acp.timeout_seconds if target.kind == "acp" else limits.timeout_seconds,
+        )
     result = run_ask(  # F13, then send (F9-F12)
         AskRequest(task, data, data_description, schema),
         limits=limits,