aiscript 1.3.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.3.0 → aiscript-1.5.0}/pyproject.toml

@@ -1,12 +1,13 @@
 [project]
 name = "aiscript"
-version = "1.3.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]
@@ -40,6 +45,9 @@ extend-exclude = [
     ".codex/skills",
 ]
 
+[tool.ruff.per-file-target-version]
+"src/aiscript/_shim/**" = "py38"
+
 [tool.ruff.lint]
 select = [
     "E",
@@ -60,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.3.0 → aiscript-1.5.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "aiscript"
-version = "1.3.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]
@@ -35,6 +41,9 @@ target-version = "py310"
 # Installed skills carry supporting code with their own style conventions.
 extend-exclude = [".agents/skills", ".claude/skills", ".cursor/skills", ".codex/skills"]
 
+# The shim runs on the system Python, which may be as old as 3.8.
+per-file-target-version = { "src/aiscript/_shim/**" = "py38" }
+
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B", "ANN"]
 
@@ -49,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.3.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.3.0"
+__version__ = "1.5.0"

aiscript-1.5.0/src/aiscript/_shim/aiscript/__init__.py

@@ -0,0 +1,181 @@
+"""Python shim for AI calls inside generated scripts (stdlib only, Python >= 3.8).
+
+``ask()`` runs ``aiscript --ask=TASK`` as a subprocess with the data on stdin.
+"""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import threading
+from typing import Any, Dict, List, Optional, Union
+
+_STDERR_LIMIT = 500
+
+
+class AskError(Exception):
+    """Base class of every failure of ``ask()``; ``exit_code`` is the aiscript exit code."""
+
+    exit_code = 1
+
+
+class AskUsageError(AskError):
+    exit_code = 2
+
+
+class AskConfigError(AskError):
+    exit_code = 3
+
+
+class AskInputError(AskError):
+    exit_code = 4
+
+
+class AskProviderError(AskError):
+    exit_code = 5
+
+
+class AskRateLimitError(AskError):
+    exit_code = 6
+
+
+class AskRefusalError(AskError):
+    exit_code = 7
+
+
+class AskOutputError(AskError):
+    exit_code = 8
+
+
+class AskCapError(AskError):
+    exit_code = 9
+
+
+class AskNotFoundError(AskError):
+    exit_code = 127
+
+
+EXIT_CODES = {
+    "AskUsageError": 2,
+    "AskConfigError": 3,
+    "AskInputError": 4,
+    "AskProviderError": 5,
+    "AskRateLimitError": 6,
+    "AskRefusalError": 7,
+    "AskOutputError": 8,
+    "AskCapError": 9,
+    "AskNotFoundError": 127,
+}
+
+
+def _shim_root() -> str:
+    return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def _child_env() -> Dict[str, str]:
+    """Environment for the real aiscript: this shim's directory is removed from PYTHONPATH."""
+    env = dict(os.environ)
+    root = os.path.normcase(_shim_root())
+    entries = [
+        e
+        for e in env.get("PYTHONPATH", "").split(os.pathsep)
+        if e and os.path.normcase(os.path.abspath(e)) != root
+    ]
+    if entries:
+        env["PYTHONPATH"] = os.pathsep.join(entries)
+    else:
+        env.pop("PYTHONPATH", None)
+    return env
+
+
+def _error_for(code: int, stderr: bytes) -> AskError:
+    detail = stderr.decode("utf-8", errors="replace").strip()
+    if len(detail) > _STDERR_LIMIT:
+        detail = detail[:_STDERR_LIMIT] + "..."
+    if code == 2 and "unrecognized arguments" in detail:
+        return AskUsageError(
+            "The aiscript on PATH is older than 1.4.0 and has no --ask; upgrade aiscript."
+        )
+    message = f"aiscript --ask failed (exit {code}): {detail}"
+    for name, known in EXIT_CODES.items():
+        if known == code:
+            return globals()[name](message)
+    error = AskError(message)
+    error.exit_code = code
+    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,
+    data_description: str,
+    schema: Optional[Dict[str, Any]] = None,
+) -> Union[str, Dict[str, Any]]:
+    """Run ``aiscript --ask`` and return its answer (a string, or a dict with a schema)."""
+    if not isinstance(task, str) or not task.strip():
+        raise AskUsageError("task must be a non-empty string")
+    if not isinstance(data_description, str) or not data_description.strip():
+        raise AskUsageError("data_description must be a non-empty string")
+    if not isinstance(data, str):
+        raise AskUsageError("data must be a str (decode bytes first)")
+    args = ["--ask=" + task, "--data-description=" + data_description]
+    if schema is not None:
+        try:
+            args.append("--schema=" + json.dumps(schema, separators=(",", ":")))
+        except (TypeError, ValueError) as exc:
+            raise AskUsageError(f"schema is not JSON serialisable: {exc}") from None
+    exe = shutil.which("aiscript")
+    if exe is None:
+        raise AskNotFoundError(
+            "aiscript was not found on PATH; install aiscript so that `aiscript` is on PATH."
+        )
+    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")
+    if out.endswith("\n"):
+        out = out[:-1]
+    if schema is None:
+        return out
+    try:
+        result = json.loads(out)
+    except ValueError:
+        raise AskOutputError("aiscript returned invalid JSON for the schema") from None
+    if not isinstance(result, dict):
+        raise AskOutputError("aiscript returned JSON that is not an object")
+    return result