aiscript 1.0.0__py3-none-any.whl

aiscript/__init__.py

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

aiscript/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m aiscript``."""
+
+import sys
+
+from aiscript.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

aiscript/builder.py

@@ -0,0 +1,66 @@
+"""Staleness check and build pipeline."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+from aiscript import llm, paths, reviewer
+from aiscript.config import Settings
+from aiscript.errors import AiscriptError
+
+
+def needs_build(name: str) -> bool:
+    """True if the function is missing or older than its prompt."""
+    fpath = paths.function_path(name)
+    if not fpath.exists():
+        return True
+    ppath = paths.prompt_path(name)
+    if not ppath.exists():
+        return False
+    return ppath.stat().st_mtime_ns > fpath.stat().st_mtime_ns
+
+
+def _read_intent(name: str) -> str:
+    ppath = paths.prompt_path(name)
+    try:
+        intent = ppath.read_text(encoding="utf-8").strip()
+    except FileNotFoundError:
+        raise AiscriptError(
+            f"No prompt for {name!r}. Run `aiscript {name}` to create it."
+        ) from None
+    if not intent:
+        raise AiscriptError(f"Prompt for {name!r} is empty: {ppath}")
+    return intent
+
+
+def build(name: str, settings: Settings) -> Path:
+    """Generate, review and atomically write the script for ``name``."""
+    intent = _read_intent(name)
+    gen = settings.generator
+    print(f"Generating {name!r} with {gen.name}/{gen.model}...", file=sys.stderr)
+    script = llm.generate_script(gen, name, intent)
+
+    shell = paths.shell_kind()
+    result = reviewer.review(script, shell, settings.reviewer)
+    if not reviewer.confirm(script, result):
+        raise AiscriptError("Script rejected; nothing saved.")
+
+    paths.ensure_dirs()
+    target = paths.function_path(name)
+    fd, tmp_name = tempfile.mkstemp(dir=paths.functions_dir(), prefix=f".{name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(script)
+        if not paths.is_windows():
+            os.chmod(tmp_name, 0o755)
+        os.replace(tmp_name, target)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp_name)
+        raise
+    print(f"Saved {target}", file=sys.stderr)
+    return target

aiscript/cli.py

@@ -0,0 +1,163 @@
+"""Command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+
+from aiscript import __version__, builder, paths
+from aiscript.config import load_settings
+from aiscript.errors import AiscriptError
+from aiscript.init_cmd import run_init
+from aiscript.listing import list_commands
+from aiscript.runner import run_script
+
+_HELP = """\
+usage: aiscript NAME [args...]       run a command (created/built on first use)
+       aiscript --init               create config dir and config.yaml template
+       aiscript --list               list commands
+       aiscript --edit NAME          edit a command's prompt (rebuilds on next run)
+       aiscript --rebuild NAME       regenerate a command's script (does not run it)
+       aiscript --remove NAME        delete a command's prompt and script
+       aiscript --help | --version
+
+Everything after NAME is passed untouched to the generated script.
+"""
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="aiscript", add_help=False)
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--init", action="store_true")
+    group.add_argument("--list", action="store_true")
+    group.add_argument("--edit", metavar="NAME")
+    group.add_argument("--rebuild", metavar="NAME")
+    group.add_argument("--remove", metavar="NAME")
+    group.add_argument("--help", "-h", action="store_true")
+    group.add_argument("--version", action="store_true")
+    return parser
+
+
+def _err(msg: str) -> None:
+    print(msg, file=sys.stderr)
+
+
+def _editor_command() -> list[str]:
+    for var in ("VISUAL", "EDITOR"):
+        value = os.environ.get(var, "").strip()
+        if value:
+            return shlex.split(value, posix=not paths.is_windows())
+    if paths.is_windows():
+        return ["notepad"]
+    for candidate in ("nano", "vi"):
+        if shutil.which(candidate):
+            return [candidate]
+    raise AiscriptError("No editor found; set $VISUAL or $EDITOR.")
+
+
+def _edit(name: str) -> int:
+    paths.validate_command_name(name)
+    ppath = paths.prompt_path(name)
+    if not ppath.exists():
+        raise AiscriptError(f"No prompt for {name!r}. Run `aiscript {name}` to create it.")
+    before = ppath.stat().st_mtime_ns
+    cmd = [*_editor_command(), str(ppath)]
+    try:
+        proc = subprocess.run(cmd)
+    except OSError as exc:
+        raise AiscriptError(f"Could not launch editor {cmd[0]!r}: {exc}") from exc
+    if proc.returncode != 0:
+        _err(f"aiscript: editor exited with status {proc.returncode}")
+    if ppath.stat().st_mtime_ns != before:
+        _err(f"Prompt for {name!r} changed; it will be rebuilt on next run.")
+    else:
+        _err(f"Prompt for {name!r} unchanged.")
+    return 0
+
+
+def _rebuild(name: str) -> int:
+    paths.validate_command_name(name)
+    paths.ensure_dirs()
+    if not paths.prompt_path(name).exists():
+        raise AiscriptError(f"No prompt for {name!r}. Run `aiscript {name}` to create it.")
+    # build() replaces the cached script atomically, so a failed or rejected
+    # rebuild keeps the previous version.
+    print(builder.build(name, load_settings()))
+    return 0
+
+
+def _remove(name: str) -> int:
+    paths.validate_command_name(name)
+    targets = [p for p in (paths.prompt_path(name), paths.function_path(name)) if p.exists()]
+    if not targets:
+        raise AiscriptError(f"No command named {name!r}.")
+    for path in targets:
+        try:
+            path.unlink()
+        except OSError as exc:
+            raise AiscriptError(f"Could not remove {path}: {exc}") from exc
+        _err(f"Removed {path}")
+    return 0
+
+
+def _run_command(name: str, args: list[str]) -> int:
+    paths.validate_command_name(name)
+    paths.ensure_dirs()
+    ppath = paths.prompt_path(name)
+    if not ppath.exists():
+        sys.stderr.write(f"Command not found. What should '{name}' do? ")
+        sys.stderr.flush()
+        try:
+            answer = input("").strip()
+        except EOFError:
+            answer = ""
+        if not answer:
+            _err("")
+            raise AiscriptError("No description given; nothing saved.")
+        ppath.write_text(answer + "\n", encoding="utf-8")
+    if builder.needs_build(name):
+        builder.build(name, load_settings())
+    return run_script(paths.function_path(name), args)
+
+
+def _dispatch(argv: list[str]) -> int:
+    if not argv:
+        sys.stderr.write(_HELP)
+        return 2
+    if argv[0].startswith("-"):
+        try:
+            ns = _build_parser().parse_args(argv)
+        except SystemExit:
+            return 2
+        if ns.help:
+            sys.stderr.write(_HELP)
+            return 0
+        if ns.version:
+            print(f"aiscript {__version__}")
+            return 0
+        if ns.init:
+            return run_init()
+        if ns.list:
+            return list_commands()
+        if ns.edit is not None:
+            return _edit(ns.edit)
+        if ns.remove is not None:
+            return _remove(ns.remove)
+        return _rebuild(ns.rebuild)
+    return _run_command(argv[0], argv[1:])
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    try:
+        return _dispatch(args)
+    except AiscriptError as exc:
+        _err(f"aiscript: error: {exc}")
+        return exc.exit_code
+    except KeyboardInterrupt:
+        _err("")
+        return 130

aiscript/config.py

@@ -0,0 +1,268 @@
+"""config.yaml + environment loader."""
+
+from __future__ import annotations
+
+import os
+import re
+import stat
+import sys
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlparse
+
+from aiscript.errors import ConfigError
+from aiscript.paths import config_path, is_windows, legacy_secrets_path
+
+
+@dataclass(frozen=True)
+class ProviderConfig:
+    name: str
+    api_key: str | None
+    base_url: str | None
+    model: str
+    kind: str = "openai"  # "openai" (OpenAI-compatible) or "jev" (TypeSafe System One; Ollaya too)
+    api: str = "chat"  # for kind "openai": "responses" or "chat" (completions)
+    reasoning_effort: str | None = None  # sent only when set
+    temperature: float | None = None  # sent only when set (GPT-6 rejects it unless effort=none)
+
+
+@dataclass(frozen=True)
+class Settings:
+    generator: ProviderConfig
+    reviewer: ProviderConfig | None
+
+
+DEFAULT_PROVIDER = "openai"
+DEFAULT_MODEL = "gpt-6-luna"
+JEV_DEFAULT_MODEL = "jev-latest"
+OLLAYA_DEFAULT_MODEL = "jevk5:4b"
+OLLAYA_DEFAULT_URL = "http://localhost:11435"
+_KINDS = {"openai", "jev", "ollaya"}
+_APIS = {"responses", "chat"}
+_OPENAI_HOSTS = {"api.openai.com"}
+_JEV_NAMES = {"jev", "typesafe"}
+_OLLAYA_NAMES = {"ollaya"}
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+def load_raw_config() -> dict[str, Any]:
+    """Return parsed config.yaml ({} if missing); ConfigError on invalid YAML.
+
+    Falls back to the legacy secrets.yaml (with a one-time stderr warning) when config.yaml
+    does not exist. The old file is never moved automatically.
+    """
+    path = config_path()
+    if not path.is_file():
+        legacy = legacy_secrets_path()
+        if not legacy.is_file():
+            return {}
+        print(
+            f"aiscript: warning: secrets.yaml is deprecated; rename it: mv {legacy} {path}",
+            file=sys.stderr,
+        )
+        path = legacy
+    if not is_windows():
+        try:
+            mode = path.stat().st_mode
+        except OSError:
+            mode = 0
+        if mode & (stat.S_IRWXG | stat.S_IRWXO):
+            print(
+                f"aiscript: warning: {path} is accessible by other users; run: chmod 600 {path}",
+                file=sys.stderr,
+            )
+    import yaml  # deferred: cached runs never read the config
+
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"Invalid YAML in {path}: {exc}") from exc
+    except OSError as exc:
+        raise ConfigError(f"Cannot read {path}: {exc}") from exc
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path} must contain a YAML mapping at the top level.")
+    return data
+
+
+def _clean(value: object) -> str | None:
+    """Return a stripped non-empty string, or None."""
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def is_local(base_url: str | None) -> bool:
+    if not base_url:
+        return False
+    try:
+        host = urlparse(base_url).hostname
+    except ValueError:
+        return False
+    return (host or "").lower() in _LOCAL_HOSTS
+
+
+def _is_official_openai(base_url: str | None) -> bool:
+    if not base_url:
+        return True
+    try:
+        return (urlparse(base_url).hostname or "").lower() in _OPENAI_HOSTS
+    except ValueError:
+        return False
+
+
+def _env_key_name(provider: str) -> str:
+    return re.sub(r"[^A-Za-z0-9]", "_", provider).upper() + "_API_KEY"
+
+
+def _ollaya_base_url() -> str:
+    """$OLLAYA_HOST (``host:port`` or a URL) or the local default."""
+    host = _clean(os.environ.get("OLLAYA_HOST"))
+    if host is None:
+        return OLLAYA_DEFAULT_URL
+    return host if "://" in host else f"http://{host}"
+
+
+def _resolve_provider(
+    name: str, raw: dict[str, Any], *, generator: bool, fallback_model: str | None = None
+) -> ProviderConfig:
+    path = config_path()
+    providers = raw.get("providers")
+    if providers is None:
+        providers = {}
+    if not isinstance(providers, dict):
+        raise ConfigError(f"'providers' in {path} must be a mapping.")
+    if providers and name not in providers:
+        known = ", ".join(sorted(str(k) for k in providers))
+        raise ConfigError(
+            f"Provider '{name}' is not defined in {path} (known providers: {known}). "
+            "Edit the file or run `aiscript --init`."
+        )
+    entry = providers.get(name) or {}
+    if not isinstance(entry, dict):
+        raise ConfigError(f"Provider '{name}' in {path} must be a mapping.")
+
+    default_kind = (
+        "jev"
+        if name.lower() in _JEV_NAMES
+        else "ollaya"
+        if name.lower() in _OLLAYA_NAMES
+        else "openai"
+    )
+    kind = (_clean(entry.get("kind")) or default_kind).lower()
+    if kind not in _KINDS:
+        raise ConfigError(
+            f"Provider '{name}' in {path} has unknown kind '{kind}' "
+            "(expected: openai, jev, ollaya)."
+        )
+    # Ollaya speaks the Jev wire protocol: only its defaults differ, so it becomes kind "jev".
+    ollaya = kind == "ollaya"
+    if ollaya:
+        kind = "jev"
+
+    base_url = _clean(entry.get("base_url")) or _clean(entry.get("endpoint"))
+    if base_url is None and ollaya:
+        base_url = _ollaya_base_url()
+    if base_url is None and generator:
+        base_url = _clean(os.environ.get("OPENAI_BASE_URL"))
+
+    api_key = _clean(entry.get("api_key"))
+    if api_key is not None and api_key.endswith("..."):
+        api_key = None  # placeholder from the template
+    if api_key is None:
+        api_key = _clean(os.environ.get(_env_key_name(name)))
+    if api_key is None and ollaya:
+        api_key = _clean(os.environ.get("OLLAYA_API_KEY")) or "not-needed"  # auth is optional
+    if api_key is None and kind == "jev":
+        api_key = _clean(os.environ.get("TYPESAFE_API_KEY"))
+    # A local server never gets the global OpenAI key: it would be sent to it in the clear.
+    if api_key is None and generator and kind == "openai" and not is_local(base_url):
+        api_key = _clean(os.environ.get("OPENAI_API_KEY"))
+    if api_key is None and is_local(base_url):
+        api_key = "not-needed"
+    if api_key is None:
+        if not generator:
+            hint = f" (or comment out `reviewer_provider: {name}` to use only the static review)"
+        else:
+            hint = ""
+        env_names = _env_key_name(name)
+        if kind == "jev":
+            env_names += " or TYPESAFE_API_KEY"
+        elif generator:
+            env_names += " or OPENAI_API_KEY"
+        raise ConfigError(
+            f"No API key for provider '{name}'. Set `api_key` for it in {path} "
+            "(run `aiscript --init` to create the file, or edit "
+            f"~/.config/aiscript/config.yaml), or export {env_names}{hint}."
+        )
+
+    if base_url and base_url.lower().startswith("http://") and not is_local(base_url):
+        print(
+            f"aiscript: warning: provider '{name}' uses plain http:// ({base_url}); "
+            "its API key and your scripts travel unencrypted.",
+            file=sys.stderr,
+        )
+
+    model = _clean(entry.get("model"))
+    if model is None and generator:
+        model = _clean(os.environ.get("AISCRIPT_MODEL"))
+    if model is None and ollaya:
+        model = OLLAYA_DEFAULT_MODEL
+    if model is None and kind == "jev":
+        model = JEV_DEFAULT_MODEL
+    if model is None:
+        model = fallback_model or DEFAULT_MODEL
+
+    # OpenAI's own endpoint gets the Responses API; other OpenAI-compatible servers
+    # (Ollama, vLLM, ...) often only implement Chat Completions.
+    api = (_clean(entry.get("api")) or "").lower() or (
+        "responses" if _is_official_openai(base_url) else "chat"
+    )
+    if api not in _APIS:
+        raise ConfigError(
+            f"Provider '{name}' in {path} has unknown api '{api}' (expected: responses, chat)."
+        )
+    reasoning_effort = _clean(entry.get("reasoning_effort"))
+    temperature = entry.get("temperature")
+    if temperature is not None:
+        try:
+            temperature = float(temperature)
+        except (TypeError, ValueError):
+            raise ConfigError(
+                f"Provider '{name}' in {path}: temperature must be a number."
+            ) from None
+    return ProviderConfig(
+        name=name,
+        api_key=api_key,
+        base_url=base_url,
+        model=model,
+        kind=kind,
+        api=api,
+        reasoning_effort=reasoning_effort,
+        temperature=temperature,
+    )
+
+
+def load_settings() -> Settings:
+    """Resolve generator/reviewer providers; raise ConfigError with actionable text."""
+    raw = load_raw_config()
+    gen_name = (
+        _clean(os.environ.get("AISCRIPT_PROVIDER"))
+        or _clean(raw.get("default_provider"))
+        or DEFAULT_PROVIDER
+    )
+    generator = _resolve_provider(gen_name, raw, generator=True)
+    if generator.kind == "jev":
+        raise ConfigError(
+            f"Provider '{gen_name}' is a Jev-style (TypeSafe/Ollaya) classifier and cannot "
+            "generate scripts. "
+            "Use it as `reviewer_provider` and pick a chat model for `default_provider`."
+        )
+
+    reviewer = None
+    rev_name = _clean(raw.get("reviewer_provider"))
+    if rev_name:
+        reviewer = _resolve_provider(rev_name, raw, generator=False, fallback_model=generator.model)
+    return Settings(generator=generator, reviewer=reviewer)

aiscript/errors.py

@@ -0,0 +1,11 @@
+"""Exception types."""
+
+
+class AiscriptError(Exception):
+    """Base error; the CLI prints it and exits with ``exit_code``."""
+
+    exit_code: int = 1
+
+
+class ConfigError(AiscriptError):
+    """Invalid or missing configuration."""

aiscript/init_cmd.py

@@ -0,0 +1,108 @@
+"""`aiscript --init`: create config dirs, config.yaml, and .gitignore protection."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from aiscript.paths import (
+    aiscript_home,
+    config_path,
+    ensure_dirs,
+    functions_dir,
+    is_windows,
+    legacy_secrets_path,
+    prompts_dir,
+)
+
+CONFIG_TEMPLATE = """\
+# aiscript config. Contains API keys: keep it private (chmod 600) and out of git.
+# Keys can also come from the environment: OPENAI_API_KEY, TYPESAFE_API_KEY, <PROVIDER>_API_KEY.
+
+# Provider that writes the scripts (override with $AISCRIPT_PROVIDER).
+default_provider: openai
+
+# Decision model that reviews scripts on top of the built-in static scan.
+# Use `ollaya` for a local, keyless review; comment out to use only the static scan.
+reviewer_provider: jev
+
+providers:
+  # OpenAI (or any OpenAI-compatible API). API key: https://platform.openai.com/api-keys
+  openai:
+    api_key: "..."
+    model: "gpt-6-luna"
+    # reasoning_effort: low    # none | low | medium | high | xhigh | max (model-dependent)
+
+  # Jev (TypeSafe AI) safety reviewer. API key: https://console.typesafe.ai/keys
+  jev:
+    api_key: "..."
+
+  # Uses Ollaya for a local decision model (https://ollaya.dev), model example: jevk5:4b
+  # ollaya:
+  #   model: "jevk5:4b"
+
+  # Uses Ollama for a local LLM to create the scripts (set `default_provider: ollama`)
+  # ollama:
+  #   base_url: "http://localhost:11434/v1"
+  #   model: "qwen3"
+"""
+
+# secrets.yaml stays listed so files from before the rename remain ignored.
+_IGNORE_LINES = ("config.yaml", "secrets.yaml", "functions/")
+
+
+def ensure_gitignore(home: Path) -> bool:
+    """Append config.yaml, secrets.yaml, functions/ to home/.gitignore if home is a git repo."""
+    if not (home / ".git").exists():
+        return False
+    gi = home / ".gitignore"
+    existing = gi.read_text(encoding="utf-8") if gi.exists() else ""
+    present = {line.strip() for line in existing.splitlines()}
+    missing = [line for line in _IGNORE_LINES if line not in present]
+    if not missing:
+        return False
+    prefix = "" if not existing or existing.endswith("\n") else "\n"
+    gi.write_text(existing + prefix + "\n".join(missing) + "\n", encoding="utf-8")
+    return True
+
+
+def run_init() -> int:
+    def say(msg: str) -> None:
+        print(msg, file=sys.stderr)
+
+    home = aiscript_home()
+    ensure_dirs()
+    say(f"Config directory: {home}")
+    say(f"  prompts:   {prompts_dir()}")
+    say(f"  functions: {functions_dir()}")
+
+    path = config_path()
+    legacy = legacy_secrets_path()
+    if not path.exists() and legacy.is_file():
+        # Old layout: don't create a second file that would shadow the user's keys.
+        say(f"Found legacy {legacy}; rename it: mv {legacy} {path}")
+        path = legacy
+    else:
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+        try:
+            fd = os.open(path, flags, 0o600)
+        except FileExistsError:
+            say(f"Config file already exists (left untouched): {path}")
+        else:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(CONFIG_TEMPLATE)
+            say(f"Created config file: {path}")
+    if not is_windows():
+        os.chmod(path, 0o600)
+
+    if ensure_gitignore(home):
+        say(f"Updated {home / '.gitignore'} (config.yaml, secrets.yaml, functions/)")
+
+    say("")
+    say("Next steps:")
+    say(f"  1. Put your OpenAI and Jev API keys in {path}")
+    say("     (or export OPENAI_API_KEY and TYPESAFE_API_KEY).")
+    say("     For a local, keyless review, use the `ollaya` provider (https://ollaya.dev).")
+    say("  2. Create your first command:  aiscript <name>")
+    return 0