askai-py 0.1.0__tar.gz

askai_py-0.1.0/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.

askai_py-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,72 @@
+# 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/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "askai-py"
+version = "0.1.0"
+description = "CLI for one-shot, stateless questions to an LLM."
+authors = [
+    {name = "Peconi Federico", email = "fpswe@tuta.io"},
+]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "platformdirs>=4.9.6",
+    "typer>=0.24.1",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+
+[project.urls]
+Homepage = "https://codeberg.org/peconif/askai"
+Repository = "https://codeberg.org/peconif/askai"
+Issues = "https://codeberg.org/peconif/askai/issues"
+"GitHub Mirror" = "https://github.com/arbiter1elegantiae/askai"
+
+[project.scripts]
+askai = "askai.cli:run"
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "askai"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "ruff>=0.15.11",
+    "ty>=0.0.32",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP", "B"]
+
+[tool.ty.environment]
+python-version = "3.12"
+root = ["./src"]
+
+[tool.ty.src]
+include = ["src", "tests"]
+[tool.ty.terminal]
+output-format = "concise"

askai_py-0.1.0/src/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_py-0.1.0/src/askai/__main__.py

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

askai_py-0.1.0/src/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_py-0.1.0/src/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