askllm-cli 0.1.0__tar.gz → 0.1.2__tar.gz

askllm_cli-0.1.2/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: askllm-cli
+Version: 0.1.2
+Summary: Lightweight OpenAI-compatible terminal REPL
+Author: AskLLM
+License: MIT
+Keywords: llm,repl,cli,openai,terminal,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: prompt_toolkit>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# AskLLM
+
+A lightweight, cross-platform Python REPL for chatting with LLMs via any OpenAI-compatible API, powered by `prompt_toolkit`.
+
+Designed to be installed via `pip install askllm-cli` (or `pipx install askllm-cli`), and developed using **Podman** with `python:3.12-slim` (or run directly with Python 3).
+
+---
+
+## Features
+
+- **Python Code Execution Tool:** Exposes a stateful Python execution tool to the LLM via OpenAI-compatible tool/function calling (`-x` / `--code-execution`), allowing models to execute Python code, verify calculations, inspect data, and iterate.
+- **Modern, Cross-Platform REPL (`prompt_toolkit`):** Robust, native interactive terminal experience across Linux, macOS, and Windows.
+- **Slash Command Auto-Completion:** Interactive auto-completion for slash commands (`/help`, `/model`, `/tools`, `/clear`, `/history`, etc.).
+- **Minimal Dependencies:** Uses standard library for networking (`urllib.request`) and JSON, relying solely on `prompt_toolkit` for the terminal UI.
+- **Standard Python Package:** Modern PEP 517/621 packaging (`pyproject.toml`) published as `askllm-cli` on PyPI.
+- **Podman Development Ready:** Built-in development workflow using `python:3.12-slim` (`./dev.sh`).
+- **Environment Variable Auto-Detection:** Automatically picks up standard OpenAI / Azure / local LLM variables.
+- **Streaming Responses:** Real-time token streaming via Server-Sent Events (SSE).
+- **Graceful Signal Handling:**
+  - `Ctrl+C` or `Ctrl+D` at the beginning of the line exits the REPL.
+  - `Ctrl+C` with text in the buffer cancels the line.
+  - `Ctrl+C` during response streaming halts generation cleanly without exiting.
+- **Multi-Turn Chat History:** Maintains conversation context across turns within the session.
+- **Automatic `/v1/responses` Detection & Fallback:** Automatically probes and switches to the newer `/v1/responses` API when supported, seamlessly falling back to `/v1/chat/completions` if the endpoint returns HTTP 404/405/501 (such as on Ollama, LM Studio, or vLLM). Can also be configured via `--api-mode` (`auto`, `chat`, `responses`).
+- **Persistent Input History:** History saved across runs in `$HOME/.askllm_history` or custom file specified via `-H` / `--history-file` or `ASKLLM_HISTORY_FILE` (safely falling back to in-memory history if opening fails).
+- **Multiline Input Support:**
+  - Triple quotes `"""` ... `"""`
+  - Trailing backslash `\`
+  - `/paste` command
+
+---
+
+## Development with Podman (`python:3.12-slim`)
+
+No local Python installation or host dependencies are required. A complete development environment is provided via Podman:
+
+### 1. Interactive Development Shell
+Drop into an interactive bash shell running inside `python:3.12-slim` with AskLLM installed in editable mode (`pip install -e .`):
+
+```bash
+./dev.sh
+```
+
+Inside the shell:
+```bash
+# Run AskLLM directly
+askllm --help
+
+# Run tests
+pytest
+
+# Test interactive python
+python3 -c "import askllm; print(askllm.__version__)"
+```
+
+Any changes made to files in `src/askllm` on your host are immediately reflected inside the container!
+
+### 2. Run Tests in Podman
+Run the test suite inside the `python:3.12-slim` container:
+
+```bash
+./dev.sh test
+```
+
+### 3. Run AskLLM via Podman
+Run AskLLM using Podman directly from the host:
+
+```bash
+./askllm
+```
+or with arguments:
+```bash
+./askllm --model llama3.2 --endpoint http://localhost:11434/v1
+```
+
+### 4. Dev Container (VS Code / IDEs)
+Open this repository in VS Code or any editor supporting Dev Containers to develop seamlessly inside the `python:3.12-slim` container.
+
+---
+
+## Installation via `pip` / `pipx`
+
+Install AskLLM from PyPI:
+
+```bash
+# Recommended for CLI tools
+pipx install askllm-cli
+
+# Or via standard pip
+pip install askllm-cli
+```
+
+Or install locally in editable mode in any Python virtual environment:
+
+```bash
+# Editable install
+pip install -e .
+
+# With dev dependencies (pytest)
+pip install -e ".[dev]"
+```
+
+Once installed, the `askllm` command is directly available:
+
+```bash
+askllm --help
+```
+
+Or run as a module:
+```bash
+python3 -m askllm
+```
+
+---
+
+## Production Container
+
+Build and run the production image using Podman:
+
+```bash
+podman build -t askllm .
+podman run --rm -it --network=host -e OPENAI_API_KEY askllm
+```
+
+---
+
+## Environment Variables
+
+AskLLM automatically checks for standard OpenAI variables, all of which can be overridden by their `ASKLLM_` counterparts:
+
+| Variable (AskLLM) | Fallback / Alias (OpenAI) | Description | Default |
+| :--- | :--- | :--- | :--- |
+| `ASKLLM_API_KEY` | `OPENAI_API_KEY` | Your API key | *(empty / none)* |
+| `ASKLLM_BASE_URL` / `ASKLLM_ENDPOINT` / `ASKLLM_API_BASE` | `OPENAI_BASE_URL` / `OPENAI_ENDPOINT` / `OPENAI_API_BASE` | API base URL or chat completions endpoint | `https://api.openai.com/v1` |
+| `ASKLLM_MODEL` / `ASKLLM_MODEL_NAME` | `OPENAI_MODEL` / `OPENAI_MODEL_NAME` / `MODEL` | Default model name | `gpt-4o-mini` |
+| `ASKLLM_SYSTEM_PROMPT` | `OPENAI_SYSTEM_PROMPT` | Custom system prompt | `"You are a helpful assistant."` |
+| `ASKLLM_CODE_EXECUTION` | `OPENAI_CODE_EXECUTION` | Enable Python code execution tool | `false` |
+| `ASKLLM_HISTORY_FILE` | `OPENAI_HISTORY_FILE` | Path to persistent REPL history file | `~/.askllm_history` |
+| `ASKLLM_API_MODE` | `OPENAI_API_MODE` | API mode (`auto`, `chat`, `responses`) | `auto` |
+
+---
+
+## Using with Local LLMs (Ollama, LM Studio, vLLM, etc.)
+
+Because `./askllm` and `./dev.sh` use host networking (`--network=host`), you can connect directly to local servers:
+
+#### Ollama:
+```bash
+ASKLLM_ENDPOINT="http://localhost:11434/v1" ASKLLM_MODEL="llama3.2" ./askllm
+```
+
+#### LM Studio / LocalAI / vLLM:
+```bash
+ASKLLM_ENDPOINT="http://localhost:1234/v1" ASKLLM_MODEL="local-model" ./askllm
+```
+
+---
+
+## REPL Slash Commands
+
+Inside the REPL, type `/` to access built-in commands:
+
+| Command | Action |
+| :--- | :--- |
+| `/help` | Display command help and tips |
+| `/clear` or `/reset` | Clear session conversation history and code execution namespace |
+| `/model [name]` | Show or dynamically switch model |
+| `/endpoint` | Show currently configured endpoint URL and active API mode |
+| `/system [prompt]` | Show or update the system prompt |
+| `/tools [on\|off]` | Show or toggle Python code execution tool |
+| `/history` | Show full message history for the session |
+| `/paste` | Enter multiline paste mode |
+| `/exit` or `/quit` | Exit the REPL |
+
+---
+
+## Declarative Web Request Tools
+
+Each `-w`/`--web-request` value creates a separate model tool. A request has a
+name, description, defaults, and `params`. Each parameter supplies the model
+facing name and description, a JSON Schema snippet, and a dotted (or JSON
+Pointer) path into `defaults` to replace:
+
+```json
+{
+  "name": "lookup",
+  "description": "Look up a value.",
+  "defaults": {
+    "uri": "https://example.test/lookup",
+    "query": {"page": 1},
+    "method": "GET"
+  },
+  "params": [
+    {
+      "name": "page",
+      "description": "Result page number.",
+      "schema": {"type": "integer", "minimum": 1},
+      "path": "query.page"
+    }
+  ]
+}
+```
+
+The tool exposed to the model contains only the declared parameters; request
+fields not declared in `params` remain fixed at their defaults. `-w` may be
+repeated, or its value may be a JSON array of request definitions.
+
+## Command-Line Options
+
+```
+usage: askllm [-h] [-v] [-m MODEL] [-e ENDPOINT] [-x] [-k API_KEY] [-s SYSTEM]
+              [-H HISTORY_FILE] [-w JSON] [--api-mode {auto,chat,responses}]
+
+options:
+  -h, --help            show this help message and exit
+  -v, --version         show program's version number and exit
+  -m MODEL, --model MODEL
+                        LLM model name (env: ASKLLM_MODEL, OPENAI_MODEL, default: gpt-4o-mini)
+  -e ENDPOINT, --endpoint ENDPOINT
+                        API Base URL / Endpoint (env: ASKLLM_BASE_URL, OPENAI_BASE_URL, OPENAI_ENDPOINT, OPENAI_API_BASE)
+  -x, --code-execution
+                        Enable Python code execution tool for the LLM (env: ASKLLM_CODE_EXECUTION, OPENAI_CODE_EXECUTION)
+  -k API_KEY, --api-key API_KEY
+                        API Key (env: ASKLLM_API_KEY, OPENAI_API_KEY)
+  -s SYSTEM, --system SYSTEM
+                        System prompt (env: ASKLLM_SYSTEM_PROMPT, OPENAI_SYSTEM_PROMPT)
+  -H HISTORY_FILE, --history-file HISTORY_FILE
+                        Path to history file (env: ASKLLM_HISTORY_FILE, OPENAI_HISTORY_FILE, default: ~/.askllm_history)
+  -w JSON, --web-request JSON
+                        Expose a declarative web request tool; repeat the option or provide a JSON array
+  --api-mode {auto,chat,responses}
+                        API mode: auto (probe /v1/responses then fallback to /v1/chat/completions),
+                        chat, or responses (env: ASKLLM_API_MODE, OPENAI_API_MODE, default: auto)
+```

askllm_cli-0.1.2/README.md

@@ -0,0 +1,234 @@
+# AskLLM
+
+A lightweight, cross-platform Python REPL for chatting with LLMs via any OpenAI-compatible API, powered by `prompt_toolkit`.
+
+Designed to be installed via `pip install askllm-cli` (or `pipx install askllm-cli`), and developed using **Podman** with `python:3.12-slim` (or run directly with Python 3).
+
+---
+
+## Features
+
+- **Python Code Execution Tool:** Exposes a stateful Python execution tool to the LLM via OpenAI-compatible tool/function calling (`-x` / `--code-execution`), allowing models to execute Python code, verify calculations, inspect data, and iterate.
+- **Modern, Cross-Platform REPL (`prompt_toolkit`):** Robust, native interactive terminal experience across Linux, macOS, and Windows.
+- **Slash Command Auto-Completion:** Interactive auto-completion for slash commands (`/help`, `/model`, `/tools`, `/clear`, `/history`, etc.).
+- **Minimal Dependencies:** Uses standard library for networking (`urllib.request`) and JSON, relying solely on `prompt_toolkit` for the terminal UI.
+- **Standard Python Package:** Modern PEP 517/621 packaging (`pyproject.toml`) published as `askllm-cli` on PyPI.
+- **Podman Development Ready:** Built-in development workflow using `python:3.12-slim` (`./dev.sh`).
+- **Environment Variable Auto-Detection:** Automatically picks up standard OpenAI / Azure / local LLM variables.
+- **Streaming Responses:** Real-time token streaming via Server-Sent Events (SSE).
+- **Graceful Signal Handling:**
+  - `Ctrl+C` or `Ctrl+D` at the beginning of the line exits the REPL.
+  - `Ctrl+C` with text in the buffer cancels the line.
+  - `Ctrl+C` during response streaming halts generation cleanly without exiting.
+- **Multi-Turn Chat History:** Maintains conversation context across turns within the session.
+- **Automatic `/v1/responses` Detection & Fallback:** Automatically probes and switches to the newer `/v1/responses` API when supported, seamlessly falling back to `/v1/chat/completions` if the endpoint returns HTTP 404/405/501 (such as on Ollama, LM Studio, or vLLM). Can also be configured via `--api-mode` (`auto`, `chat`, `responses`).
+- **Persistent Input History:** History saved across runs in `$HOME/.askllm_history` or custom file specified via `-H` / `--history-file` or `ASKLLM_HISTORY_FILE` (safely falling back to in-memory history if opening fails).
+- **Multiline Input Support:**
+  - Triple quotes `"""` ... `"""`
+  - Trailing backslash `\`
+  - `/paste` command
+
+---
+
+## Development with Podman (`python:3.12-slim`)
+
+No local Python installation or host dependencies are required. A complete development environment is provided via Podman:
+
+### 1. Interactive Development Shell
+Drop into an interactive bash shell running inside `python:3.12-slim` with AskLLM installed in editable mode (`pip install -e .`):
+
+```bash
+./dev.sh
+```
+
+Inside the shell:
+```bash
+# Run AskLLM directly
+askllm --help
+
+# Run tests
+pytest
+
+# Test interactive python
+python3 -c "import askllm; print(askllm.__version__)"
+```
+
+Any changes made to files in `src/askllm` on your host are immediately reflected inside the container!
+
+### 2. Run Tests in Podman
+Run the test suite inside the `python:3.12-slim` container:
+
+```bash
+./dev.sh test
+```
+
+### 3. Run AskLLM via Podman
+Run AskLLM using Podman directly from the host:
+
+```bash
+./askllm
+```
+or with arguments:
+```bash
+./askllm --model llama3.2 --endpoint http://localhost:11434/v1
+```
+
+### 4. Dev Container (VS Code / IDEs)
+Open this repository in VS Code or any editor supporting Dev Containers to develop seamlessly inside the `python:3.12-slim` container.
+
+---
+
+## Installation via `pip` / `pipx`
+
+Install AskLLM from PyPI:
+
+```bash
+# Recommended for CLI tools
+pipx install askllm-cli
+
+# Or via standard pip
+pip install askllm-cli
+```
+
+Or install locally in editable mode in any Python virtual environment:
+
+```bash
+# Editable install
+pip install -e .
+
+# With dev dependencies (pytest)
+pip install -e ".[dev]"
+```
+
+Once installed, the `askllm` command is directly available:
+
+```bash
+askllm --help
+```
+
+Or run as a module:
+```bash
+python3 -m askllm
+```
+
+---
+
+## Production Container
+
+Build and run the production image using Podman:
+
+```bash
+podman build -t askllm .
+podman run --rm -it --network=host -e OPENAI_API_KEY askllm
+```
+
+---
+
+## Environment Variables
+
+AskLLM automatically checks for standard OpenAI variables, all of which can be overridden by their `ASKLLM_` counterparts:
+
+| Variable (AskLLM) | Fallback / Alias (OpenAI) | Description | Default |
+| :--- | :--- | :--- | :--- |
+| `ASKLLM_API_KEY` | `OPENAI_API_KEY` | Your API key | *(empty / none)* |
+| `ASKLLM_BASE_URL` / `ASKLLM_ENDPOINT` / `ASKLLM_API_BASE` | `OPENAI_BASE_URL` / `OPENAI_ENDPOINT` / `OPENAI_API_BASE` | API base URL or chat completions endpoint | `https://api.openai.com/v1` |
+| `ASKLLM_MODEL` / `ASKLLM_MODEL_NAME` | `OPENAI_MODEL` / `OPENAI_MODEL_NAME` / `MODEL` | Default model name | `gpt-4o-mini` |
+| `ASKLLM_SYSTEM_PROMPT` | `OPENAI_SYSTEM_PROMPT` | Custom system prompt | `"You are a helpful assistant."` |
+| `ASKLLM_CODE_EXECUTION` | `OPENAI_CODE_EXECUTION` | Enable Python code execution tool | `false` |
+| `ASKLLM_HISTORY_FILE` | `OPENAI_HISTORY_FILE` | Path to persistent REPL history file | `~/.askllm_history` |
+| `ASKLLM_API_MODE` | `OPENAI_API_MODE` | API mode (`auto`, `chat`, `responses`) | `auto` |
+
+---
+
+## Using with Local LLMs (Ollama, LM Studio, vLLM, etc.)
+
+Because `./askllm` and `./dev.sh` use host networking (`--network=host`), you can connect directly to local servers:
+
+#### Ollama:
+```bash
+ASKLLM_ENDPOINT="http://localhost:11434/v1" ASKLLM_MODEL="llama3.2" ./askllm
+```
+
+#### LM Studio / LocalAI / vLLM:
+```bash
+ASKLLM_ENDPOINT="http://localhost:1234/v1" ASKLLM_MODEL="local-model" ./askllm
+```
+
+---
+
+## REPL Slash Commands
+
+Inside the REPL, type `/` to access built-in commands:
+
+| Command | Action |
+| :--- | :--- |
+| `/help` | Display command help and tips |
+| `/clear` or `/reset` | Clear session conversation history and code execution namespace |
+| `/model [name]` | Show or dynamically switch model |
+| `/endpoint` | Show currently configured endpoint URL and active API mode |
+| `/system [prompt]` | Show or update the system prompt |
+| `/tools [on\|off]` | Show or toggle Python code execution tool |
+| `/history` | Show full message history for the session |
+| `/paste` | Enter multiline paste mode |
+| `/exit` or `/quit` | Exit the REPL |
+
+---
+
+## Declarative Web Request Tools
+
+Each `-w`/`--web-request` value creates a separate model tool. A request has a
+name, description, defaults, and `params`. Each parameter supplies the model
+facing name and description, a JSON Schema snippet, and a dotted (or JSON
+Pointer) path into `defaults` to replace:
+
+```json
+{
+  "name": "lookup",
+  "description": "Look up a value.",
+  "defaults": {
+    "uri": "https://example.test/lookup",
+    "query": {"page": 1},
+    "method": "GET"
+  },
+  "params": [
+    {
+      "name": "page",
+      "description": "Result page number.",
+      "schema": {"type": "integer", "minimum": 1},
+      "path": "query.page"
+    }
+  ]
+}
+```
+
+The tool exposed to the model contains only the declared parameters; request
+fields not declared in `params` remain fixed at their defaults. `-w` may be
+repeated, or its value may be a JSON array of request definitions.
+
+## Command-Line Options
+
+```
+usage: askllm [-h] [-v] [-m MODEL] [-e ENDPOINT] [-x] [-k API_KEY] [-s SYSTEM]
+              [-H HISTORY_FILE] [-w JSON] [--api-mode {auto,chat,responses}]
+
+options:
+  -h, --help            show this help message and exit
+  -v, --version         show program's version number and exit
+  -m MODEL, --model MODEL
+                        LLM model name (env: ASKLLM_MODEL, OPENAI_MODEL, default: gpt-4o-mini)
+  -e ENDPOINT, --endpoint ENDPOINT
+                        API Base URL / Endpoint (env: ASKLLM_BASE_URL, OPENAI_BASE_URL, OPENAI_ENDPOINT, OPENAI_API_BASE)
+  -x, --code-execution
+                        Enable Python code execution tool for the LLM (env: ASKLLM_CODE_EXECUTION, OPENAI_CODE_EXECUTION)
+  -k API_KEY, --api-key API_KEY
+                        API Key (env: ASKLLM_API_KEY, OPENAI_API_KEY)
+  -s SYSTEM, --system SYSTEM
+                        System prompt (env: ASKLLM_SYSTEM_PROMPT, OPENAI_SYSTEM_PROMPT)
+  -H HISTORY_FILE, --history-file HISTORY_FILE
+                        Path to history file (env: ASKLLM_HISTORY_FILE, OPENAI_HISTORY_FILE, default: ~/.askllm_history)
+  -w JSON, --web-request JSON
+                        Expose a declarative web request tool; repeat the option or provide a JSON array
+  --api-mode {auto,chat,responses}
+                        API mode: auto (probe /v1/responses then fallback to /v1/chat/completions),
+                        chat, or responses (env: ASKLLM_API_MODE, OPENAI_API_MODE, default: auto)
+```

{askllm_cli-0.1.0 → askllm_cli-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "askllm-cli"
-version = "0.1.0"
+version = "0.1.2"
 description = "Lightweight OpenAI-compatible terminal REPL"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -18,6 +18,7 @@ classifiers = [
     "Environment :: Console",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
@@ -28,7 +29,9 @@ classifiers = [
     "Topic :: Communications :: Chat",
     "Topic :: Utilities",
 ]
-dependencies = []
+dependencies = [
+    "prompt_toolkit>=3.0.0",
+]
 
 [project.optional-dependencies]
 dev = [

askllm_cli-0.1.2/src/askllm/__init__.py

@@ -0,0 +1,12 @@
+"""
+AskLLM - A lightweight Python REPL for asking LLMs (OpenAI-compatible endpoints).
+Powered by prompt_toolkit for a modern, cross-platform interactive terminal UX.
+"""
+
+__version__ = "0.1.2"
+
+from askllm.cli import LLMClient, REPL, main
+from askllm.executor import PythonExecutor, PYTHON_TOOL
+
+__all__ = ["LLMClient", "REPL", "main", "PythonExecutor", "PYTHON_TOOL", "__version__"]
+