askai-py 0.1.0__py3-none-any.whl

askai/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("askai-py")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = ["__version__"]

askai/__main__.py

@@ -0,0 +1,3 @@
+from askai.cli import run
+
+run()

askai/backends/__init__.py

@@ -0,0 +1,152 @@
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Protocol
+
+from askai.policy import AskaiPrompt
+
+
+@dataclass(frozen=True)
+class BackendRequest:
+    prompt: AskaiPrompt
+    model: str | None = None
+    max_lines: int | None = None
+
+
+@dataclass(frozen=True)
+class BackendResponse:
+    raw_output: str
+
+
+@dataclass(frozen=True)
+class BackendAvailability:
+    available: bool
+    executable: str | None = None
+    message: str | None = None
+
+
+class BackendAdapter(Protocol):
+    name: str
+
+    def check_availability(self) -> BackendAvailability: ...
+
+    def execute(self, request: BackendRequest) -> BackendResponse: ...
+
+
+class BackendError(Exception):
+    pass
+
+
+class BackendNotConfiguredError(BackendError):
+    def __init__(self) -> None:
+        super().__init__(
+            "Backend is not configured. Run `askai config set backend BACKEND`."
+        )
+
+
+class BackendExecutableNotFoundError(BackendError):
+    def __init__(
+        self,
+        backend: str,
+        *,
+        executable: str | None = None,
+        detail: str | None = None,
+    ) -> None:
+        target = (
+            f"Backend executable '{executable}' for backend '{backend}'"
+            if executable is not None
+            else f"Backend executable for backend '{backend}'"
+        )
+        detail_text = f": {detail}" if detail else ""
+        super().__init__(f"{target} is unavailable{detail_text}. Run `askai doctor`.")
+
+
+class BackendCredentialsNotFoundError(BackendError):
+    def __init__(self, backend: str, *, detail: str | None = None) -> None:
+        detail_text = f": {detail}" if detail else ""
+        super().__init__(
+            f"Backend '{backend}' credentials are missing or rejected{detail_text}."
+        )
+
+
+class BackendUnsupportedModelError(BackendError):
+    def __init__(self, backend: str, model: str | None = None) -> None:
+        if model is None:
+            message = f"Backend '{backend}' does not support model overrides."
+        else:
+            message = f"Backend '{backend}' does not support model override '{model}'."
+
+        super().__init__(message)
+
+
+class BackendTimeoutError(BackendError):
+    def __init__(self, backend: str) -> None:
+        super().__init__(f"Backend '{backend}' timed out.")
+
+
+class BackendInvocationError(BackendError):
+    def __init__(self, backend: str, detail: str | None = None) -> None:
+        detail_text = f": {detail}" if detail else ""
+        super().__init__(f"Backend '{backend}' invocation failed{detail_text}.")
+
+
+def build_backend_adapters() -> dict[str, BackendAdapter]:
+    from askai.backends.codex import CodexBackendAdapter
+    from askai.backends.groq import GroqBackendAdapter
+
+    codex_adapter = CodexBackendAdapter()
+    groq_adapter = GroqBackendAdapter()
+    return {
+        codex_adapter.name: codex_adapter,
+        groq_adapter.name: groq_adapter,
+    }
+
+
+BACKEND_ADAPTERS: dict[str, BackendAdapter] = build_backend_adapters()
+
+
+def resolve_backend_adapter(
+    backend: str | None,
+    *,
+    adapters: Mapping[str, BackendAdapter] | None = None,
+) -> BackendAdapter:
+    if backend is None:
+        raise BackendNotConfiguredError()
+
+    adapter_registry = BACKEND_ADAPTERS if adapters is None else adapters
+    adapter = adapter_registry.get(backend)
+    if adapter is None:
+        raise BackendInvocationError(backend, "no adapter is registered")
+
+    return adapter
+
+
+def check_backend_availability(
+    backend: str | None,
+    *,
+    adapters: Mapping[str, BackendAdapter] | None = None,
+) -> BackendAvailability:
+    adapter = resolve_backend_adapter(backend, adapters=adapters)
+    return adapter.check_availability()
+
+
+def execute_backend(
+    backend: str | None,
+    request: BackendRequest,
+    *,
+    adapters: Mapping[str, BackendAdapter] | None = None,
+) -> BackendResponse:
+    adapter = resolve_backend_adapter(backend, adapters=adapters)
+    availability = adapter.check_availability()
+    if not availability.available:
+        if availability.executable is not None:
+            raise BackendExecutableNotFoundError(
+                backend or adapter.name,
+                executable=availability.executable,
+                detail=availability.message,
+            )
+        raise BackendCredentialsNotFoundError(
+            backend or adapter.name,
+            detail=availability.message,
+        )
+
+    return adapter.execute(request)

askai/backends/codex.py

@@ -0,0 +1,156 @@
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from askai.backends import (
+    BackendAvailability,
+    BackendExecutableNotFoundError,
+    BackendInvocationError,
+    BackendRequest,
+    BackendResponse,
+    BackendTimeoutError,
+)
+
+CODEX_BACKEND_NAME = "codex"
+CODEX_EXECUTABLE = "codex"
+CODEX_TIMEOUT_SECONDS = 60
+
+
+class CodexBackendAdapter:
+    name = CODEX_BACKEND_NAME
+
+    def __init__(
+        self,
+        *,
+        executable: str = CODEX_EXECUTABLE,
+        timeout_seconds: int = CODEX_TIMEOUT_SECONDS,
+    ) -> None:
+        self.executable = executable
+        self.timeout_seconds = timeout_seconds
+
+    def check_availability(self) -> BackendAvailability:
+        executable_path = shutil.which(self.executable)
+        if executable_path is None:
+            return BackendAvailability(
+                available=False,
+                executable=self.executable,
+                message=f"{self.executable} executable not found on PATH",
+            )
+
+        return BackendAvailability(available=True, executable=executable_path)
+
+    def execute(self, request: BackendRequest) -> BackendResponse:
+        availability = self.check_availability()
+        if not availability.available:
+            raise BackendExecutableNotFoundError(
+                self.name,
+                executable=availability.executable,
+                detail=availability.message,
+            )
+
+        executable_path = availability.executable or self.executable
+        with tempfile.TemporaryDirectory(prefix="askai-codex-") as temp_dir:
+            answer_path = Path(temp_dir) / "answer.txt"
+            command = build_codex_command(
+                executable_path,
+                work_dir=temp_dir,
+                answer_path=answer_path,
+                model=request.model,
+            )
+            run_codex_command(
+                command,
+                prompt=request.prompt.render_for_single_prompt(),
+                work_dir=temp_dir,
+                timeout_seconds=self.timeout_seconds,
+            )
+
+            return BackendResponse(raw_output=read_codex_answer(answer_path))
+
+
+def build_codex_command(
+    executable: str,
+    *,
+    work_dir: str,
+    answer_path: Path,
+    model: str | None,
+) -> list[str]:
+    command = [
+        executable,
+        "exec",
+        "--cd",
+        work_dir,
+        "--skip-git-repo-check",
+        "--ephemeral",
+        "--ignore-rules",
+        "--ignore-user-config",
+        "--sandbox",
+        "read-only",
+        "--color",
+        "never",
+    ]
+
+    if model is not None:
+        command.extend(["--model", model])
+
+    command.extend(["--output-last-message", str(answer_path), "-"])
+    return command
+
+
+def run_codex_command(
+    command: list[str],
+    *,
+    prompt: str,
+    work_dir: str,
+    timeout_seconds: int,
+) -> None:
+    try:
+        completed_process = subprocess.run(
+            command,
+            input=prompt,
+            capture_output=True,
+            text=True,
+            shell=False,
+            cwd=work_dir,
+            timeout=timeout_seconds,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as error:
+        raise BackendTimeoutError(CODEX_BACKEND_NAME) from error
+    except OSError as error:
+        raise BackendInvocationError(CODEX_BACKEND_NAME, str(error)) from error
+
+    if completed_process.returncode != 0:
+        detail = summarize_process_failure(
+            completed_process.stderr,
+            completed_process.stdout,
+        )
+        raise BackendInvocationError(CODEX_BACKEND_NAME, detail)
+
+
+def summarize_process_failure(stderr: str, stdout: str) -> str:
+    for output in (stderr, stdout):
+        detail = first_non_empty_line(output)
+        if detail:
+            return detail
+
+    return "process exited with no diagnostic output"
+
+
+def first_non_empty_line(value: str) -> str | None:
+    for line in value.splitlines():
+        detail = line.strip()
+        if detail:
+            return detail
+
+    return None
+
+
+def read_codex_answer(answer_path: Path) -> str:
+    try:
+        return answer_path.read_text(encoding="utf-8")
+    except OSError as error:
+        raise BackendInvocationError(
+            CODEX_BACKEND_NAME,
+            f"could not read final answer file: {error}",
+        ) from error

askai/backends/groq.py

@@ -0,0 +1,237 @@
+import json
+import os
+import ssl
+import urllib.error
+import urllib.request
+from typing import Any, cast
+
+from askai import __version__
+from askai.backends import (
+    BackendAvailability,
+    BackendCredentialsNotFoundError,
+    BackendError,
+    BackendInvocationError,
+    BackendRequest,
+    BackendResponse,
+    BackendTimeoutError,
+)
+from askai.policy import AskaiPrompt
+
+GROQ_BACKEND_NAME = "groq"
+GROQ_API_KEY_ENV = "GROQ_API_KEY"
+GROQ_ENDPOINT = "https://api.groq.com/openai/v1/chat/completions"
+GROQ_DEFAULT_MODEL = "llama-3.1-8b-instant"
+GROQ_TIMEOUT_SECONDS = 30
+GROQ_TEMPERATURE = 0.2
+GROQ_TOKENS_PER_LINE = 32
+GROQ_FALLBACK_MAX_LINES = 6
+ASKAI_CA_BUNDLE_ENV = "ASKAI_CA_BUNDLE"
+
+
+class GroqBackendAdapter:
+    name = GROQ_BACKEND_NAME
+
+    def __init__(
+        self,
+        *,
+        endpoint: str = GROQ_ENDPOINT,
+        timeout_seconds: int = GROQ_TIMEOUT_SECONDS,
+    ) -> None:
+        self.endpoint = endpoint
+        self.timeout_seconds = timeout_seconds
+
+    def check_availability(self) -> BackendAvailability:
+        if not os.environ.get(GROQ_API_KEY_ENV):
+            return BackendAvailability(
+                available=False,
+                message=f"{GROQ_API_KEY_ENV} environment variable is not set",
+            )
+
+        return BackendAvailability(available=True)
+
+    def execute(self, request: BackendRequest) -> BackendResponse:
+        api_key = os.environ.get(GROQ_API_KEY_ENV)
+        if not api_key:
+            raise BackendCredentialsNotFoundError(
+                GROQ_BACKEND_NAME,
+                detail=f"{GROQ_API_KEY_ENV} environment variable is not set",
+            )
+
+        model = request.model if request.model is not None else GROQ_DEFAULT_MODEL
+        max_tokens = estimate_max_tokens(request.max_lines)
+        payload = build_groq_payload(
+            prompt=request.prompt,
+            model=model,
+            max_tokens=max_tokens,
+        )
+
+        response_body = send_groq_request(
+            self.endpoint,
+            api_key=api_key,
+            payload=payload,
+            timeout_seconds=self.timeout_seconds,
+        )
+
+        return BackendResponse(raw_output=extract_groq_answer(response_body))
+
+
+def estimate_max_tokens(max_lines: int | None) -> int:
+    effective_lines = max_lines if max_lines is not None else GROQ_FALLBACK_MAX_LINES
+    return effective_lines * GROQ_TOKENS_PER_LINE
+
+
+def build_groq_payload(
+    *,
+    prompt: AskaiPrompt,
+    model: str,
+    max_tokens: int,
+) -> dict[str, Any]:
+    return {
+        "model": model,
+        "messages": [
+            {"role": "system", "content": prompt.system},
+            {"role": "user", "content": prompt.user},
+        ],
+        "max_tokens": max_tokens,
+        "temperature": GROQ_TEMPERATURE,
+    }
+
+
+def build_ssl_context() -> ssl.SSLContext | None:
+    ca_bundle = os.environ.get(ASKAI_CA_BUNDLE_ENV)
+    if not ca_bundle:
+        return None
+
+    context = ssl.create_default_context()
+    context.load_verify_locations(cafile=ca_bundle)
+    return context
+
+
+def send_groq_request(
+    endpoint: str,
+    *,
+    api_key: str,
+    payload: dict[str, Any],
+    timeout_seconds: int,
+) -> dict[str, Any]:
+    body = json.dumps(payload).encode("utf-8")
+    request = urllib.request.Request(
+        endpoint,
+        data=body,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": f"askai/{__version__}",
+        },
+        method="POST",
+    )
+
+    ssl_context = build_ssl_context()
+
+    try:
+        with urllib.request.urlopen(
+            request, timeout=timeout_seconds, context=ssl_context
+        ) as response:
+            response_text = response.read().decode("utf-8")
+    except urllib.error.HTTPError as error:
+        error_text = error.read().decode("utf-8", errors="replace")
+        raise map_groq_http_error(error.code, error_text) from error
+    except TimeoutError as error:
+        raise BackendTimeoutError(GROQ_BACKEND_NAME) from error
+    except urllib.error.URLError as error:
+        if isinstance(error.reason, TimeoutError):
+            raise BackendTimeoutError(GROQ_BACKEND_NAME) from error
+        raise BackendInvocationError(
+            GROQ_BACKEND_NAME,
+            str(error.reason),
+        ) from error
+
+    try:
+        response_data: Any = json.loads(response_text)
+    except json.JSONDecodeError as error:
+        raise BackendInvocationError(
+            GROQ_BACKEND_NAME,
+            f"could not parse response: {error}",
+        ) from error
+
+    if not isinstance(response_data, dict):
+        raise BackendInvocationError(
+            GROQ_BACKEND_NAME,
+            "response was not a JSON object",
+        )
+
+    return cast(dict[str, Any], response_data)
+
+
+def map_groq_http_error(status: int, body: str) -> BackendError:
+    detail = extract_groq_error_message(body)
+
+    if status in (401, 403):
+        return BackendCredentialsNotFoundError(
+            GROQ_BACKEND_NAME,
+            detail="API key was rejected by Groq",
+        )
+    if status == 429:
+        return BackendInvocationError(
+            GROQ_BACKEND_NAME,
+            detail="rate limit reached, retry shortly",
+        )
+    if detail:
+        return BackendInvocationError(
+            GROQ_BACKEND_NAME,
+            detail=f"HTTP {status}: {detail}",
+        )
+    return BackendInvocationError(GROQ_BACKEND_NAME, detail=f"HTTP {status}")
+
+
+def extract_groq_error_message(body: str) -> str | None:
+    try:
+        data = json.loads(body)
+    except json.JSONDecodeError:
+        return None
+
+    error = data.get("error")
+    if isinstance(error, dict):
+        message = error.get("message")
+        if isinstance(message, str):
+            return message
+
+    return None
+
+
+def extract_groq_answer(response_body: dict[str, Any]) -> str:
+    choices = response_body.get("choices")
+    if not isinstance(choices, list) or not choices:
+        raise BackendInvocationError(
+            GROQ_BACKEND_NAME,
+            "response contained no choices",
+        )
+
+    first_choice = choices[0]
+    if not isinstance(first_choice, dict):
+        raise BackendInvocationError(
+            GROQ_BACKEND_NAME,
+            "malformed response choice",
+        )
+
+    if first_choice.get("finish_reason") == "length":
+        raise BackendInvocationError(
+            GROQ_BACKEND_NAME,
+            "response hit token limit before completing",
+        )
+
+    message = first_choice.get("message")
+    if not isinstance(message, dict):
+        raise BackendInvocationError(
+            GROQ_BACKEND_NAME,
+            "malformed response message",
+        )
+
+    content = message.get("content")
+    if not isinstance(content, str):
+        raise BackendInvocationError(
+            GROQ_BACKEND_NAME,
+            "response had no text content",
+        )
+
+    return content

askai/cli.py

@@ -0,0 +1,332 @@
+import sys
+from collections.abc import Sequence
+from typing import Annotated, Never
+
+import typer
+
+from askai import __version__
+from askai.backends import (
+    BACKEND_ADAPTERS,
+    BackendAvailability,
+    BackendError,
+    BackendRequest,
+    check_backend_availability,
+    execute_backend,
+)
+from askai.config import (
+    MAX_ANSWER_LINES,
+    ConfigError,
+    get_effective_config,
+    set_backend,
+    set_max_lines,
+    set_model,
+    validate_backend,
+    validate_max_lines,
+    validate_model,
+)
+from askai.policy import build_prompt, normalize_output
+
+EXIT_RUNTIME_ERROR = 1
+EXIT_USAGE_ERROR = 2
+
+app = typer.Typer(
+    help="Ask one-shot, stateless questions to an LLM from the terminal.",
+    invoke_without_command=True,
+    no_args_is_help=False,
+)
+config_app = typer.Typer(help="Inspect and update local askai configuration.")
+config_set_app = typer.Typer(help="Set local askai configuration values.")
+
+app.add_typer(config_app, name="config")
+config_app.add_typer(config_set_app, name="set")
+
+ROOT_PASSTHROUGH_ARGS = {
+    "--help",
+    "-h",
+    "--version",
+    "--install-completion",
+    "--show-completion",
+    "config",
+    "doctor",
+}
+
+
+def _fail(message: str, code: int = EXIT_RUNTIME_ERROR) -> Never:
+    typer.echo(f"Error: {message}", err=True)
+    raise typer.Exit(code)
+
+
+def _validate_max_lines(value: int, name: str) -> None:
+    try:
+        validate_max_lines(value)
+    except ConfigError:
+        _fail(
+            f"{name} must be between 1 and {MAX_ANSWER_LINES}.",
+            EXIT_USAGE_ERROR,
+        )
+
+
+def _fail_config_error(error: ConfigError, code: int = EXIT_RUNTIME_ERROR) -> Never:
+    _fail(str(error), code)
+
+
+def _fail_backend_error(error: BackendError) -> Never:
+    _fail(str(error), EXIT_RUNTIME_ERROR)
+
+
+def _validate_backend_option(backend: str | None) -> None:
+    if backend is None:
+        return
+
+    try:
+        validate_backend(backend)
+    except ConfigError as error:
+        _fail_config_error(error)
+
+
+def _validate_model_option(model: str | None) -> None:
+    if model is None:
+        return
+
+    try:
+        validate_model(model)
+    except ConfigError:
+        _fail("--model cannot be empty.", EXIT_USAGE_ERROR)
+
+
+def _validate_runtime_overrides(
+    *,
+    backend: str | None,
+    model: str | None,
+    max_lines: int | None,
+) -> None:
+    _validate_backend_option(backend)
+    _validate_model_option(model)
+
+    if max_lines is not None:
+        _validate_max_lines(max_lines, "--max-lines")
+
+
+def build_typer_args(argv: Sequence[str]) -> list[str]:
+    args = list(argv)
+    if args and args[0] in ROOT_PASSTHROUGH_ARGS:
+        return args
+
+    return ["query", *args]
+
+
+@app.callback()
+def main(
+    backend: Annotated[
+        str | None,
+        typer.Option("--backend", help="Override the configured backend."),
+    ] = None,
+    model: Annotated[
+        str | None,
+        typer.Option("--model", help="Override the configured model."),
+    ] = None,
+    max_lines: Annotated[
+        int | None,
+        typer.Option("--max-lines", help="Override the maximum answer lines."),
+    ] = None,
+    show_version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            help="Print the installed askai version.",
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    del backend, model, max_lines
+
+    if show_version:
+        typer.echo(f"askai {__version__}")
+        raise typer.Exit()
+
+
+@app.command("query", hidden=True)
+def query(
+    question: Annotated[str, typer.Argument(help="One-shot question to ask.")],
+    backend: Annotated[
+        str | None,
+        typer.Option("--backend", help="Override the configured backend."),
+    ] = None,
+    model: Annotated[
+        str | None,
+        typer.Option("--model", help="Override the configured model."),
+    ] = None,
+    max_lines: Annotated[
+        int | None,
+        typer.Option("--max-lines", help="Override the maximum answer lines."),
+    ] = None,
+) -> None:
+    question = question.strip()
+    if not question:
+        _fail("The question cannot be empty.", EXIT_USAGE_ERROR)
+
+    _validate_runtime_overrides(
+        backend=backend,
+        model=model,
+        max_lines=max_lines,
+    )
+
+    try:
+        _effective_config = get_effective_config(
+            backend=backend,
+            model=model,
+            max_lines=max_lines,
+        )
+    except ConfigError as error:
+        _fail_config_error(error)
+
+    prompt = build_prompt(question, max_lines=_effective_config.max_lines)
+    request = BackendRequest(
+        prompt=prompt,
+        model=_effective_config.model,
+        max_lines=_effective_config.max_lines,
+    )
+
+    try:
+        response = execute_backend(
+            _effective_config.backend,
+            request,
+            adapters=BACKEND_ADAPTERS,
+        )
+    except BackendError as error:
+        _fail_backend_error(error)
+
+    answer = normalize_output(response.raw_output, _effective_config.max_lines)
+    if answer:
+        typer.echo(answer)
+
+
+def _format_backend_availability_status(
+    availability: BackendAvailability | None,
+) -> str:
+    if availability is None:
+        return "not checked"
+
+    if availability.available:
+        return availability.executable or "available"
+
+    if availability.executable:
+        return f"{availability.executable} unavailable"
+
+    return "unavailable"
+
+
+def _format_backend_availability_problem(
+    availability: BackendAvailability,
+) -> str:
+    if availability.message:
+        return f"backend is unavailable: {availability.message}"
+
+    return "backend is unavailable"
+
+
+@config_app.command("show")
+def config_show() -> None:
+    try:
+        effective_config = get_effective_config()
+    except ConfigError as error:
+        _fail_config_error(error)
+
+    typer.echo(f"config file: {effective_config.config_path}")
+    typer.echo(f"backend: {effective_config.backend or 'not configured'}")
+    typer.echo(f"model: {effective_config.model or 'backend default'}")
+    typer.echo(f"max lines: {effective_config.max_lines}")
+
+
+@config_set_app.command("backend")
+def config_set_backend(
+    backend: Annotated[str, typer.Argument(help="Backend name to use by default.")],
+) -> None:
+    backend = backend.strip()
+    if not backend:
+        _fail("backend cannot be empty.", EXIT_USAGE_ERROR)
+
+    try:
+        config_path = set_backend(backend)
+    except ConfigError as error:
+        _fail_config_error(error)
+
+    typer.echo(f"backend set to '{backend}'")
+    typer.echo(f"config file: {config_path}")
+    typer.echo("run `askai doctor` after configuring a backend")
+
+
+@config_set_app.command("model")
+def config_set_model(
+    model: Annotated[str, typer.Argument(help="Model name to use by default.")],
+) -> None:
+    model = model.strip()
+    if not model:
+        _fail("model cannot be empty.", EXIT_USAGE_ERROR)
+
+    try:
+        config_path = set_model(model)
+    except ConfigError as error:
+        _fail_config_error(error)
+
+    typer.echo(f"model set to '{model}'")
+    typer.echo(f"config file: {config_path}")
+    typer.echo("run `askai doctor` after configuring a model")
+
+
+@config_set_app.command("max-lines")
+def config_set_max_lines(
+    max_lines: Annotated[int, typer.Argument(help="Maximum answer lines.")],
+) -> None:
+    _validate_max_lines(max_lines, "max-lines")
+
+    try:
+        config_path = set_max_lines(max_lines)
+    except ConfigError as error:
+        _fail_config_error(error)
+
+    typer.echo(f"max lines set to {max_lines}")
+    typer.echo(f"config file: {config_path}")
+
+
+@app.command()
+def doctor() -> None:
+    try:
+        effective_config = get_effective_config()
+    except ConfigError as error:
+        _fail_config_error(error)
+
+    backend_availability: BackendAvailability | None = None
+    setup_problem: str | None = None
+    try:
+        backend_availability = check_backend_availability(
+            effective_config.backend,
+            adapters=BACKEND_ADAPTERS,
+        )
+    except BackendError as error:
+        setup_problem = str(error)
+
+    if backend_availability is not None and not backend_availability.available:
+        setup_problem = _format_backend_availability_problem(backend_availability)
+
+    typer.echo(f"askai version: {__version__}")
+    typer.echo(f"config file: {effective_config.config_path}")
+    typer.echo(f"backend: {effective_config.backend or 'not configured'}")
+    typer.echo(
+        f"backend availability: {_format_backend_availability_status(backend_availability)}"
+    )
+    typer.echo(f"model: {effective_config.model or 'backend default'}")
+    typer.echo(f"max lines: {effective_config.max_lines}")
+
+    if setup_problem is not None:
+        typer.echo(f"setup problem: {setup_problem}")
+        raise typer.Exit(EXIT_RUNTIME_ERROR)
+
+
+def run(argv: Sequence[str] | None = None) -> None:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args:
+        typer.echo("Error: A question is required.", err=True)
+        raise SystemExit(EXIT_USAGE_ERROR)
+
+    app(args=build_typer_args(args), prog_name="askai")

askai/config.py

@@ -0,0 +1,234 @@
+import json
+import os
+import tomllib
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any
+
+from platformdirs import user_config_dir
+
+APP_NAME = "askai"
+CONFIG_FILENAME = "config.toml"
+CONFIG_FILE_ENV = "ASKAI_CONFIG_FILE"
+
+DEFAULT_BACKEND = "groq"
+DEFAULT_MODEL: str | None = None
+DEFAULT_MAX_LINES = 6
+MAX_ANSWER_LINES = 20
+KNOWN_BACKENDS = ("codex", "groq")
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class UserConfig:
+    backend: str | None = None
+    model: str | None = None
+    max_lines: int | None = None
+
+
+@dataclass(frozen=True)
+class EffectiveConfig:
+    config_path: Path
+    backend: str | None
+    model: str | None
+    max_lines: int
+
+
+def get_config_path(config_path: Path | None = None) -> Path:
+    if config_path is not None:
+        return config_path
+
+    env_config_path = os.environ.get(CONFIG_FILE_ENV)
+    if env_config_path:
+        return Path(env_config_path).expanduser()
+
+    return Path(user_config_dir(APP_NAME)) / CONFIG_FILENAME
+
+
+def load_user_config(config_path: Path | None = None) -> UserConfig:
+    path = get_config_path(config_path)
+    if not path.exists():
+        return UserConfig()
+
+    try:
+        raw_config = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as error:
+        raise ConfigError(f"Invalid config file {path}: {error}") from error
+    except OSError as error:
+        raise ConfigError(f"Could not read config file {path}: {error}") from error
+
+    return parse_user_config(raw_config, path)
+
+
+def get_effective_config(
+    *,
+    backend: str | None = None,
+    model: str | None = None,
+    max_lines: int | None = None,
+    config_path: Path | None = None,
+) -> EffectiveConfig:
+    path = get_config_path(config_path)
+    user_config = load_user_config(path)
+
+    effective_backend = (
+        validate_backend(backend)
+        if backend is not None
+        else user_config.backend or DEFAULT_BACKEND
+    )
+    effective_model = (
+        validate_model(model)
+        if model is not None
+        else user_config.model or DEFAULT_MODEL
+    )
+    effective_max_lines = (
+        validate_max_lines(max_lines)
+        if max_lines is not None
+        else user_config.max_lines or DEFAULT_MAX_LINES
+    )
+
+    return EffectiveConfig(
+        config_path=path,
+        backend=effective_backend,
+        model=effective_model,
+        max_lines=effective_max_lines,
+    )
+
+
+def set_backend(backend: str, config_path: Path | None = None) -> Path:
+    validated_backend = validate_backend(backend)
+    user_config = load_user_config(config_path)
+    return write_user_config(
+        replace(user_config, backend=validated_backend), config_path
+    )
+
+
+def set_model(model: str, config_path: Path | None = None) -> Path:
+    validated_model = validate_model(model)
+    user_config = load_user_config(config_path)
+    return write_user_config(replace(user_config, model=validated_model), config_path)
+
+
+def set_max_lines(max_lines: int, config_path: Path | None = None) -> Path:
+    validated_max_lines = validate_max_lines(max_lines)
+    user_config = load_user_config(config_path)
+    return write_user_config(
+        replace(user_config, max_lines=validated_max_lines),
+        config_path,
+    )
+
+
+def write_user_config(
+    user_config: UserConfig,
+    config_path: Path | None = None,
+) -> Path:
+    path = get_config_path(config_path)
+
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(format_user_config(user_config), encoding="utf-8")
+    except OSError as error:
+        raise ConfigError(f"Could not write config file {path}: {error}") from error
+
+    return path
+
+
+def parse_user_config(raw_config: dict[str, Any], path: Path) -> UserConfig:
+    backend = parse_backend(raw_config, path)
+    model = parse_model(raw_config, path)
+    max_lines = parse_max_lines(raw_config, path)
+
+    return UserConfig(backend=backend, model=model, max_lines=max_lines)
+
+
+def parse_backend(raw_config: dict[str, Any], path: Path) -> str | None:
+    value = raw_config.get("backend")
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ConfigError(f"Invalid config file {path}: backend must be a string.")
+
+    try:
+        return validate_backend(value)
+    except ConfigError as error:
+        raise ConfigError(f"Invalid config file {path}: {error}") from error
+
+
+def parse_model(raw_config: dict[str, Any], path: Path) -> str | None:
+    value = raw_config.get("model")
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ConfigError(f"Invalid config file {path}: model must be a string.")
+
+    try:
+        return validate_model(value)
+    except ConfigError as error:
+        raise ConfigError(f"Invalid config file {path}: {error}") from error
+
+
+def parse_max_lines(raw_config: dict[str, Any], path: Path) -> int | None:
+    value = raw_config.get("max_lines")
+    if value is None:
+        return None
+    if type(value) is not int:
+        raise ConfigError(f"Invalid config file {path}: max_lines must be an integer.")
+
+    try:
+        return validate_max_lines(value)
+    except ConfigError as error:
+        raise ConfigError(f"Invalid config file {path}: {error}") from error
+
+
+def format_user_config(user_config: UserConfig) -> str:
+    lines: list[str] = []
+
+    if user_config.backend is not None:
+        lines.append(f"backend = {json.dumps(user_config.backend)}")
+    if user_config.model is not None:
+        lines.append(f"model = {json.dumps(user_config.model)}")
+    if user_config.max_lines is not None:
+        lines.append(f"max_lines = {user_config.max_lines}")
+
+    if not lines:
+        return ""
+
+    return "\n".join(lines) + "\n"
+
+
+def validate_backend(backend: str) -> str:
+    value = backend.strip()
+    if not value:
+        raise ConfigError("backend cannot be empty.")
+    if not is_supported_backend(value):
+        raise ConfigError(
+            f"Unsupported backend '{value}'. Supported backends: "
+            f"{supported_backends_text()}.",
+        )
+
+    return value
+
+
+def validate_model(model: str) -> str:
+    value = model.strip()
+    if not value:
+        raise ConfigError("model cannot be empty.")
+
+    return value
+
+
+def validate_max_lines(max_lines: int) -> int:
+    if max_lines <= 0 or max_lines > MAX_ANSWER_LINES:
+        raise ConfigError(f"max_lines must be between 1 and {MAX_ANSWER_LINES}.")
+
+    return max_lines
+
+
+def is_supported_backend(backend: str) -> bool:
+    return backend in KNOWN_BACKENDS
+
+
+def supported_backends_text() -> str:
+    return ", ".join(KNOWN_BACKENDS)

askai/policy.py

@@ -0,0 +1,81 @@
+import re
+from dataclasses import dataclass
+
+ANSI_ESCAPE_PATTERN = re.compile(
+    r"\x1b(?:"
+    r"[@-Z\\-_]"
+    r"|\[[0-?]*[ -/]*[@-~]"
+    r"|\][^\x07]*(?:\x07|\x1b\\)"
+    r")"
+)
+
+
+@dataclass(frozen=True)
+class AskaiPrompt:
+    system: str
+    user: str
+
+    def render_for_single_prompt(self) -> str:
+        return f"{self.system}\n\nUser question:\n{self.user}"
+
+
+def build_prompt(question: str, *, max_lines: int) -> AskaiPrompt:
+    return AskaiPrompt(
+        system=build_system_prompt(max_lines),
+        user=question,
+    )
+
+
+def build_system_prompt(max_lines: int) -> str:
+    return "\n".join(
+        [
+            "You are askai, a terminal-first one-shot AI assistant for engineers.",
+            f"Answer in at most {max_lines} lines.",
+            "Fit the complete answer within the line limit; do not trail off.",
+            "Answer directly. Do not include preambles like 'Sure' or 'Certainly'.",
+            "Use plain text by default. Avoid Markdown unless it improves clarity.",
+            "Prefer immediately useful commands, flags, or examples when relevant.",
+            "Keep explanations concise and terminal-friendly.",
+            "If you are unsure, say so briefly instead of guessing.",
+            "Do not ask follow-up questions and do not assume conversation history.",
+        ]
+    )
+
+
+def normalize_output(raw_output: str, max_lines: int) -> str:
+    lines = [line.rstrip() for line in strip_ansi(raw_output).splitlines()]
+    lines = trim_blank_edges(lines)
+    lines = collapse_blank_lines(lines)
+
+    return "\n".join(lines[:max_lines])
+
+
+def strip_ansi(value: str) -> str:
+    return ANSI_ESCAPE_PATTERN.sub("", value)
+
+
+def trim_blank_edges(lines: list[str]) -> list[str]:
+    start = 0
+    end = len(lines)
+
+    while start < end and not lines[start].strip():
+        start += 1
+    while end > start and not lines[end - 1].strip():
+        end -= 1
+
+    return lines[start:end]
+
+
+def collapse_blank_lines(lines: list[str]) -> list[str]:
+    collapsed_lines: list[str] = []
+    previous_line_was_blank = False
+
+    for line in lines:
+        line_is_blank = not line.strip()
+        if line_is_blank and previous_line_was_blank:
+            continue
+
+        collapsed_lines.append("" if line_is_blank else line)
+        previous_line_was_blank = line_is_blank
+
+    return collapsed_lines

askai_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: askai-py
+Version: 0.1.0
+Summary: CLI for one-shot, stateless questions to an LLM.
+Author: Peconi Federico
+Author-email: Peconi Federico <fpswe@tuta.io>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: platformdirs>=4.9.6
+Requires-Dist: typer>=0.24.1
+Requires-Python: >=3.12
+Project-URL: Homepage, https://codeberg.org/peconif/askai
+Project-URL: Repository, https://codeberg.org/peconif/askai
+Project-URL: Issues, https://codeberg.org/peconif/askai/issues
+Project-URL: GitHub Mirror, https://github.com/arbiter1elegantiae/askai
+Description-Content-Type: text/markdown
+
+# Askai
+
+> Development happens on [Codeberg](https://codeberg.org/peconif/askai).
+> GitHub is a read-only mirror for discovery — please open issues and pull requests on Codeberg.
+
+CLI for one-shot, stateless questions to an LLM.
+
+Meant for engineers living inside terminals, `askai` aims to fill those small information gaps that typically pop up while working, such as:
+- commands syntax / flag names;
+- tiny code examples;
+- quick conceptual clarifications.
+Instead of wasting time switching to a browser or a dedicated AI app, simply:
+```bash
+askai "What does set -euo pipefail do?"
+```
+will return a concise, fluff-free answer from your favorite model, minimizing distractions and speeding up your workflow.
+
+## Installation
+
+Install with [`pipx`](https://pypa.github.io/pipx/) (recommended):
+
+```bash
+pipx install askai-py
+```
+
+Or with [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install askai-py
+```
+
+Then set your Groq API key (Groq is the default backend):
+
+```bash
+export GROQ_API_KEY="your-key"
+askai "How to rename a branch in Git?"
+```
+
+## Backends
+
+askai supports two backends:
+
+- **`groq`** (default) — API adapter calling Groq's OpenAI-compatible endpoint. Requires `GROQ_API_KEY`.
+- **`codex`** — CLI adapter wrapping the Codex CLI. Requires a local Codex installation.
+
+Switch backend:
+
+```bash
+askai config set backend codex
+askai doctor
+```
+
+### Adding a Backend
+
+Contributions for new backends are welcome. To add one, you need to:
+
+1. Implement the `BackendAdapter` protocol in `src/askai/backends/`
+2. Register it in `build_backend_adapters()` (`src/askai/backends/__init__.py`)
+3. Add the backend name to `KNOWN_BACKENDS` (`src/askai/config.py`)
+4. Add tests under `tests/`
+5. Document it in `docs/CLI_CONTRACT.md`
+
+## Corporate VPN / Proxy (Self-Signed Certificates)
+
+If you are behind a corporate VPN or intercepting proxy, set `ASKAI_CA_BUNDLE` to your company's CA certificate so askai trusts the TLS connection:
+
+```bash
+export ASKAI_CA_BUNDLE=/path/to/company-ca.pem
+askai "List Tmux useful commands"
+```
+
+This adds your CA as a trust root alongside the system defaults, so normal HTTPS still works.

askai_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+askai/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+askai/__init__.py,sha256=GQHazRM8263wjb41pUlMaiZMEWksYe8Pl_liIetbYgo,187
+askai/__main__.py,sha256=GP9PbQQzJ1Fo1qNIZnx7CvjqsefL6APsE9zofZ8v9ZA,33
+askai/backends/__init__.py,sha256=wkeDDT9YnIestW2zLUtUrUSJrmJKhkU6Yr2z3LGjHBs,4394
+askai/backends/codex.py,sha256=0KF2cyjI9F_fYc3JFsbix_nqfmoVU_BvAc5ZgeChBBU,4303
+askai/backends/groq.py,sha256=cie4wE53-IoyZNGNEFGdt5_p1hb76JECNV6g0Xy1S3c,6837
+askai/cli.py,sha256=TRes7doKWCE_CgEX3JPqcSorJ70YcK5q2RrZQ2tp-7w,9014
+askai/commands/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+askai/config.py,sha256=ocp1MSQJ7ReGuUV02RIsupShN9csS-TKseK03c3xMGg,6617
+askai/policy.py,sha256=qqnaR5Fo0LSkV9QZzZjIJUjUhG_O2XeIpZwnRvRt7Yw,2341
+askai/utils/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+askai_py-0.1.0.dist-info/licenses/LICENSE,sha256=dTtuA-ZNd-s3702n3IN-V2uhjyuLMeTn11AmQ3U3Q0E,1072
+askai_py-0.1.0.dist-info/WHEEL,sha256=uOqnPWqgFlbov4NeTCercq7cBQ2UN7xh5fiW55lOnAg,81
+askai_py-0.1.0.dist-info/entry_points.txt,sha256=MeWR8FjjBNOzxf2AAXrHjVbwHX-6qqjQLH8nC_joDhs,41
+askai_py-0.1.0.dist-info/METADATA,sha256=zVBMxC3IoBKB2rj4eqmT1v8fF0wVuDf4qGlm4wA8UF4,2752
+askai_py-0.1.0.dist-info/RECORD,,

askai_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.26
+Root-Is-Purelib: true
+Tag: py3-none-any

askai_py-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+askai = askai.cli:run
+

askai_py-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peconi Federico
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.