askllm-cli 0.1.0__tar.gz

askllm_cli-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: askllm-cli
+Version: 0.1.0
+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: 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
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# AskLLM
+
+A lightweight, zero-dependency Python REPL for chatting with LLMs via any OpenAI-compatible API.
+
+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
+
+- **Zero Third-Party Runtime Dependencies:** Uses standard library only (`urllib.request`, `json`, `readline`).
+- **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.
+- **Persistent Input History:** Readline history saved across runs in `~/.askllm_history`.
+- **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 these environment variables:
+
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `OPENAI_API_KEY` | Your API key | *(empty / none)* |
+| `OPENAI_ENDPOINT` or `OPENAI_BASE_URL` or `OPENAI_API_BASE` | API base URL or chat endpoint | `https://api.openai.com/v1` |
+| `OPENAI_MODEL` | Default model name | `gpt-4o-mini` |
+| `OPENAI_SYSTEM_PROMPT` | Custom system prompt | `"You are a helpful assistant."` |
+
+---
+
+## 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
+OPENAI_ENDPOINT="http://localhost:11434/v1" OPENAI_MODEL="llama3.2" ./askllm
+```
+
+#### LM Studio / LocalAI / vLLM:
+```bash
+OPENAI_ENDPOINT="http://localhost:1234/v1" OPENAI_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 |
+| `/model [name]` | Show or dynamically switch model |
+| `/endpoint` | Show currently configured endpoint URL |
+| `/system [prompt]` | Show or update the system prompt |
+| `/history` | Show full message history for the session |
+| `/paste` | Enter multiline paste mode |
+| `/exit` or `/quit` | Exit the REPL |
+
+---
+
+## Command-Line Options
+
+```
+usage: askllm [-h] [-v] [-m MODEL] [-e ENDPOINT] [-k API_KEY] [-s SYSTEM]
+
+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: OPENAI_MODEL, default: gpt-4o-mini)
+  -e ENDPOINT, --endpoint ENDPOINT
+                        API Base URL / Endpoint (env: OPENAI_BASE_URL, OPENAI_ENDPOINT, OPENAI_API_BASE)
+  -k API_KEY, --api-key API_KEY
+                        API Key (env: OPENAI_API_KEY)
+  -s SYSTEM, --system SYSTEM
+                        System prompt (env: OPENAI_SYSTEM_PROMPT)
+```

askllm_cli-0.1.0/README.md

@@ -0,0 +1,185 @@
+# AskLLM
+
+A lightweight, zero-dependency Python REPL for chatting with LLMs via any OpenAI-compatible API.
+
+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
+
+- **Zero Third-Party Runtime Dependencies:** Uses standard library only (`urllib.request`, `json`, `readline`).
+- **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.
+- **Persistent Input History:** Readline history saved across runs in `~/.askllm_history`.
+- **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 these environment variables:
+
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `OPENAI_API_KEY` | Your API key | *(empty / none)* |
+| `OPENAI_ENDPOINT` or `OPENAI_BASE_URL` or `OPENAI_API_BASE` | API base URL or chat endpoint | `https://api.openai.com/v1` |
+| `OPENAI_MODEL` | Default model name | `gpt-4o-mini` |
+| `OPENAI_SYSTEM_PROMPT` | Custom system prompt | `"You are a helpful assistant."` |
+
+---
+
+## 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
+OPENAI_ENDPOINT="http://localhost:11434/v1" OPENAI_MODEL="llama3.2" ./askllm
+```
+
+#### LM Studio / LocalAI / vLLM:
+```bash
+OPENAI_ENDPOINT="http://localhost:1234/v1" OPENAI_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 |
+| `/model [name]` | Show or dynamically switch model |
+| `/endpoint` | Show currently configured endpoint URL |
+| `/system [prompt]` | Show or update the system prompt |
+| `/history` | Show full message history for the session |
+| `/paste` | Enter multiline paste mode |
+| `/exit` or `/quit` | Exit the REPL |
+
+---
+
+## Command-Line Options
+
+```
+usage: askllm [-h] [-v] [-m MODEL] [-e ENDPOINT] [-k API_KEY] [-s SYSTEM]
+
+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: OPENAI_MODEL, default: gpt-4o-mini)
+  -e ENDPOINT, --endpoint ENDPOINT
+                        API Base URL / Endpoint (env: OPENAI_BASE_URL, OPENAI_ENDPOINT, OPENAI_API_BASE)
+  -k API_KEY, --api-key API_KEY
+                        API Key (env: OPENAI_API_KEY)
+  -s SYSTEM, --system SYSTEM
+                        System prompt (env: OPENAI_SYSTEM_PROMPT)
+```

askllm_cli-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "askllm-cli"
+version = "0.1.0"
+description = "Lightweight OpenAI-compatible terminal REPL"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "AskLLM" }
+]
+keywords = ["llm", "repl", "cli", "openai", "terminal", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Chat",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+
+[project.scripts]
+askllm = "askllm.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

askllm_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

askllm_cli-0.1.0/src/askllm/__init__.py

@@ -0,0 +1,10 @@
+"""
+AskLLM - A lightweight Python REPL for asking LLMs (OpenAI-compatible endpoints).
+Zero external dependencies (uses Python standard library).
+"""
+
+__version__ = "0.1.0"
+
+from askllm.cli import LLMClient, REPL, main
+
+__all__ = ["LLMClient", "REPL", "main", "__version__"]

askllm_cli-0.1.0/src/askllm/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m askllm."""
+
+from askllm.cli import main
+
+if __name__ == "__main__":
+    main()

askllm_cli-0.1.0/src/askllm/cli.py

@@ -0,0 +1,431 @@
+#!/usr/bin/env python3
+"""
+askllm - A lightweight Python REPL for asking LLMs (OpenAI-compatible endpoints).
+Zero external dependencies (uses Python standard library).
+"""
+
+import atexit
+import json
+import os
+import readline
+import signal
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import List, Dict, Generator, Optional, Tuple
+
+try:
+    from askllm import __version__
+except ImportError:
+    __version__ = "0.1.0"
+
+# ANSI color codes
+COLOR_RESET = "\033[0m"
+COLOR_BOLD = "\033[1m"
+COLOR_DIM = "\033[2m"
+COLOR_CYAN = "\033[36m"
+COLOR_GREEN = "\033[32m"
+COLOR_YELLOW = "\033[33m"
+COLOR_RED = "\033[31m"
+COLOR_MAGENTA = "\033[35m"
+
+# Disable colors if not a TTY or NO_COLOR is set
+if not sys.stdout.isatty() or os.environ.get("NO_COLOR"):
+    COLOR_RESET = ""
+    COLOR_BOLD = ""
+    COLOR_DIM = ""
+    COLOR_CYAN = ""
+    COLOR_GREEN = ""
+    COLOR_YELLOW = ""
+    COLOR_RED = ""
+    COLOR_MAGENTA = ""
+
+
+def get_default_env(key_names: List[str], default: Optional[str] = None) -> Optional[str]:
+    """Return the first set environment variable from a list of aliases."""
+    for key in key_names:
+        val = os.environ.get(key)
+        if val and val.strip():
+            return val.strip()
+    return default
+
+
+def resolve_chat_url(base_url: str) -> str:
+    """Normalize user-provided base URL or endpoint to chat completions URL."""
+    if not base_url:
+        return "https://api.openai.com/v1/chat/completions"
+
+    parsed = urllib.parse.urlparse(base_url)
+    path = parsed.path.rstrip("/")
+
+    if path.endswith("/chat/completions"):
+        pass
+    elif path.endswith("/v1"):
+        path = f"{path}/chat/completions"
+    elif not path or path == "/":
+        path = "/v1/chat/completions"
+    else:
+        if "chat/completions" not in path:
+            path = f"{path}/chat/completions"
+
+    return urllib.parse.urlunparse(parsed._replace(path=path))
+
+
+class LLMClient:
+    def __init__(self, api_key: str, endpoint: str, model: str):
+        self.api_key = api_key
+        self.endpoint_url = resolve_chat_url(endpoint)
+        self.model = model
+
+    def stream_chat(
+        self, messages: List[Dict[str, str]], stop_event: Optional[dict] = None
+    ) -> Generator[str, None, None]:
+        """Stream chat completions from OpenAI-compatible API."""
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "text/event-stream",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+            headers["api-key"] = self.api_key  # For Azure OpenAI compatibility
+
+        payload = {
+            "model": self.model,
+            "messages": messages,
+            "stream": True,
+        }
+
+        data = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(self.endpoint_url, data=data, headers=headers, method="POST")
+
+        try:
+            with urllib.request.urlopen(req, timeout=60) as resp:
+                for line in resp:
+                    if stop_event and stop_event.get("stop"):
+                        break
+                    line = line.decode("utf-8", errors="replace").strip()
+                    if not line or line.startswith(":"):
+                        continue
+                    if line.startswith("data: "):
+                        content_str = line[6:].strip()
+                        if content_str == "[DONE]":
+                            break
+                        try:
+                            chunk = json.loads(content_str)
+                            choices = chunk.get("choices", [])
+                            if choices:
+                                delta = choices[0].get("delta", {})
+                                text = delta.get("content", "")
+                                if text:
+                                    yield text
+                        except json.JSONDecodeError:
+                            continue
+        except urllib.error.HTTPError as e:
+            err_body = e.read().decode("utf-8", errors="replace")
+            try:
+                err_json = json.loads(err_body)
+                msg = err_json.get("error", {}).get("message", err_body)
+            except Exception:
+                msg = err_body
+            raise RuntimeError(f"HTTP {e.code} Error: {msg}") from e
+        except urllib.error.URLError as e:
+            raise RuntimeError(f"Connection Error: {e.reason}") from e
+
+
+class REPL:
+    def __init__(self, api_key: str, endpoint: str, model: str, system_prompt: str):
+        self.api_key = api_key
+        self.endpoint = endpoint
+        self.model = model
+        self.system_prompt = system_prompt
+        self.client = LLMClient(api_key=self.api_key, endpoint=self.endpoint, model=self.model)
+        self.history: List[Dict[str, str]] = []
+        self.history_file = os.path.expanduser("~/.askllm_history")
+        self._init_readline()
+
+    def _init_readline(self):
+        try:
+            readline.parse_and_bind("tab: complete")
+            if os.path.exists(self.history_file):
+                try:
+                    readline.read_history_file(self.history_file)
+                except Exception:
+                    pass
+            readline.set_history_length(1000)
+            atexit.register(self._save_history)
+        except Exception:
+            pass
+
+    def _save_history(self):
+        try:
+            readline.write_history_file(self.history_file)
+        except Exception:
+            pass
+
+    def reset_conversation(self):
+        self.history.clear()
+        print(f"{COLOR_DIM}Conversation history reset.{COLOR_RESET}")
+
+    def print_help(self):
+        print(f"""
+{COLOR_BOLD}Commands:{COLOR_RESET}
+  {COLOR_CYAN}/help{COLOR_RESET}           Show this help message
+  {COLOR_CYAN}/clear{COLOR_RESET}, {COLOR_CYAN}/reset{COLOR_RESET}   Clear current conversation history
+  {COLOR_CYAN}/model [name]{COLOR_RESET}   Show or switch current model
+  {COLOR_CYAN}/system [prompt]{COLOR_RESET} Show or update system prompt
+  {COLOR_CYAN}/history{COLOR_RESET}        Show current session history
+  {COLOR_CYAN}/endpoint{COLOR_RESET}       Show current API endpoint
+  {COLOR_CYAN}/paste{COLOR_RESET}          Start multiline paste mode (finish with empty line or EOF)
+  {COLOR_CYAN}/quit{COLOR_RESET}, {COLOR_CYAN}/exit{COLOR_RESET}   Exit REPL (or press Ctrl+C / Ctrl+D on an empty line)
+
+{COLOR_BOLD}Tips:{COLOR_RESET}
+  - Type {COLOR_CYAN}\\\\{COLOR_RESET} at the end of a line or triple quotes {COLOR_CYAN}\"\"\"{COLOR_RESET} for multiline input.
+  - Press {COLOR_CYAN}Ctrl+C{COLOR_RESET} during streaming to cancel generation.
+  - Press {COLOR_CYAN}Ctrl+C{COLOR_RESET} or {COLOR_CYAN}Ctrl+D{COLOR_RESET} at the start of a prompt to exit.
+""")
+
+    def handle_command(self, cmd: str) -> bool:
+        """Handle slash command. Returns True if handled, False otherwise."""
+        parts = cmd.strip().split(maxsplit=1)
+        action = parts[0].lower()
+        arg = parts[1].strip() if len(parts) > 1 else ""
+
+        if action in ("/quit", "/exit"):
+            print(f"{COLOR_DIM}Goodbye!{COLOR_RESET}")
+            sys.exit(0)
+        elif action in ("/help", "/?"):
+            self.print_help()
+            return True
+        elif action in ("/clear", "/reset"):
+            self.reset_conversation()
+            return True
+        elif action == "/model":
+            if arg:
+                self.model = arg
+                self.client.model = arg
+                print(f"{COLOR_DIM}Model switched to:{COLOR_RESET} {COLOR_BOLD}{self.model}{COLOR_RESET}")
+            else:
+                print(f"{COLOR_DIM}Current model:{COLOR_RESET} {COLOR_BOLD}{self.model}{COLOR_RESET}")
+            return True
+        elif action == "/endpoint":
+            print(f"{COLOR_DIM}Endpoint URL:{COLOR_RESET} {COLOR_BOLD}{self.client.endpoint_url}{COLOR_RESET}")
+            return True
+        elif action == "/system":
+            if arg:
+                self.system_prompt = arg
+                print(f"{COLOR_DIM}System prompt updated to:{COLOR_RESET}\n{self.system_prompt}")
+            else:
+                print(f"{COLOR_DIM}Current system prompt:{COLOR_RESET}\n{self.system_prompt}")
+            return True
+        elif action == "/history":
+            if not self.history:
+                print(f"{COLOR_DIM}No conversation history.{COLOR_RESET}")
+            else:
+                print(f"{COLOR_BOLD}--- Session History ---{COLOR_RESET}")
+                for msg in self.history:
+                    role = msg["role"].upper()
+                    color = COLOR_CYAN if role == "USER" else COLOR_GREEN
+                    print(f"{color}{role}:{COLOR_RESET} {msg['content']}\n")
+            return True
+        elif action == "/paste":
+            self.read_paste_mode()
+            return True
+        else:
+            print(f"{COLOR_RED}Unknown command: {action}. Type /help for assistance.{COLOR_RESET}")
+            return True
+
+    def read_paste_mode(self):
+        print(f"{COLOR_DIM}Entering multiline paste mode. Press Enter twice or Ctrl+D on empty line to submit:{COLOR_RESET}")
+        lines = []
+        while True:
+            try:
+                line = input(f"{COLOR_DIM}... {COLOR_RESET}")
+                if line == "" and lines and lines[-1] == "":
+                    lines.pop()
+                    break
+                lines.append(line)
+            except EOFError:
+                break
+            except KeyboardInterrupt:
+                print(f"\n{COLOR_DIM}[Paste cancelled]{COLOR_RESET}")
+                return
+        text = "\n".join(lines).strip()
+        if text:
+            self.send_prompt(text)
+
+    def send_prompt(self, user_text: str):
+        # Build message history for the request
+        messages = []
+        if self.system_prompt:
+            messages.append({"role": "system", "content": self.system_prompt})
+        messages.extend(self.history)
+        messages.append({"role": "user", "content": user_text})
+
+        stop_event = {"stop": False}
+
+        def sigint_handler(sig, frame):
+            stop_event["stop"] = True
+            print(f"\n{COLOR_YELLOW}[Interrupted by user]{COLOR_RESET}")
+
+        orig_handler = signal.signal(signal.SIGINT, sigint_handler)
+
+        sys.stdout.write(f"\n{COLOR_GREEN}{COLOR_BOLD}AI:{COLOR_RESET} ")
+        sys.stdout.flush()
+
+        ai_response_chunks = []
+        try:
+            for chunk in self.client.stream_chat(messages, stop_event=stop_event):
+                if stop_event["stop"]:
+                    break
+                sys.stdout.write(chunk)
+                sys.stdout.flush()
+                ai_response_chunks.append(chunk)
+            sys.stdout.write("\n\n")
+            sys.stdout.flush()
+        except RuntimeError as e:
+            sys.stdout.write("\n")
+            print(f"{COLOR_RED}Error: {e}{COLOR_RESET}\n")
+            return
+        except Exception as e:
+            sys.stdout.write("\n")
+            print(f"{COLOR_RED}Unexpected error: {e}{COLOR_RESET}\n")
+            return
+        finally:
+            signal.signal(signal.SIGINT, orig_handler)
+
+        ai_full_text = "".join(ai_response_chunks).strip()
+        if ai_full_text:
+            self.history.append({"role": "user", "content": user_text})
+            self.history.append({"role": "assistant", "content": ai_full_text})
+
+    def run(self):
+        print(f"{COLOR_BOLD}=== AskLLM REPL ==={COLOR_RESET}")
+        print(f"{COLOR_DIM}Endpoint:{COLOR_RESET} {COLOR_CYAN}{self.client.endpoint_url}{COLOR_RESET}")
+        print(f"{COLOR_DIM}Model:   {COLOR_RESET} {COLOR_CYAN}{self.model}{COLOR_RESET}")
+        if not self.api_key:
+            print(f"{COLOR_YELLOW}Warning: OPENAI_API_KEY is not set.{COLOR_RESET}")
+        print(f"{COLOR_DIM}Type {COLOR_RESET}{COLOR_CYAN}/help{COLOR_RESET}{COLOR_DIM} for commands, {COLOR_RESET}{COLOR_CYAN}Ctrl+C{COLOR_RESET}{COLOR_DIM} or {COLOR_RESET}{COLOR_CYAN}Ctrl+D{COLOR_RESET}{COLOR_DIM} at beginning of line to exit.{COLOR_RESET}\n")
+
+        while True:
+            try:
+                prompt_line = input(f"{COLOR_BOLD}{COLOR_CYAN}>>> {COLOR_RESET}")
+            except EOFError:
+                # Ctrl+D at beginning of line quits
+                print(f"\n{COLOR_DIM}Goodbye!{COLOR_RESET}")
+                break
+            except KeyboardInterrupt:
+                # Check readline buffer
+                buf = readline.get_line_buffer()
+                if not buf:
+                    # Ctrl+C at beginning of line quits
+                    print(f"\n{COLOR_DIM}Goodbye!{COLOR_RESET}")
+                    break
+                else:
+                    # Ctrl+C with text in buffer clears line and gives new prompt
+                    print("^C")
+                    continue
+
+            user_text = prompt_line.strip()
+            if not user_text:
+                continue
+
+            # Check if entering triple quotes multiline mode
+            if user_text.startswith('"""') or user_text.startswith("'''"):
+                quote_type = user_text[:3]
+                remaining = user_text[3:]
+                lines = []
+                if remaining.endswith(quote_type) and len(remaining) >= 3:
+                    user_text = remaining[:-3].strip()
+                else:
+                    if remaining:
+                        lines.append(remaining)
+                    while True:
+                        try:
+                            cont_line = input(f"{COLOR_DIM}... {COLOR_RESET}")
+                            if cont_line.endswith(quote_type):
+                                lines.append(cont_line[:-3])
+                                break
+                            lines.append(cont_line)
+                        except (EOFError, KeyboardInterrupt):
+                            print(f"\n{COLOR_DIM}[Input cancelled]{COLOR_RESET}")
+                            lines = None
+                            break
+                    if lines is None:
+                        continue
+                    user_text = "\n".join(lines).strip()
+
+            # Check for trailing backslash continuation
+            elif user_text.endswith("\\"):
+                lines = [user_text[:-1]]
+                cancelled = False
+                while True:
+                    try:
+                        cont_line = input(f"{COLOR_DIM}... {COLOR_RESET}")
+                        if cont_line.endswith("\\"):
+                            lines.append(cont_line[:-1])
+                        else:
+                            lines.append(cont_line)
+                            break
+                    except (EOFError, KeyboardInterrupt):
+                        print(f"\n{COLOR_DIM}[Input cancelled]{COLOR_RESET}")
+                        cancelled = True
+                        break
+                if cancelled:
+                    continue
+                user_text = "\n".join(lines).strip()
+
+            if not user_text:
+                continue
+
+            if user_text.startswith("/"):
+                self.handle_command(user_text)
+                continue
+
+            self.send_prompt(user_text)
+
+
+def parse_args(args=None):
+    import argparse
+    parser = argparse.ArgumentParser(prog="askllm", description="AskLLM - Lightweight Python REPL for LLMs")
+    parser.add_argument(
+        "-v", "--version",
+        action="version",
+        version=f"%(prog)s {__version__}"
+    )
+    parser.add_argument(
+        "-m", "--model",
+        default=get_default_env(["OPENAI_MODEL", "OPENAI_MODEL_NAME", "MODEL"], "gpt-4o-mini"),
+        help="LLM model name (env: OPENAI_MODEL, default: gpt-4o-mini)"
+    )
+    parser.add_argument(
+        "-e", "--endpoint",
+        default=get_default_env(["OPENAI_BASE_URL", "OPENAI_ENDPOINT", "OPENAI_API_BASE"], "https://api.openai.com/v1"),
+        help="API Base URL / Endpoint (env: OPENAI_BASE_URL, OPENAI_ENDPOINT, OPENAI_API_BASE)"
+    )
+    parser.add_argument(
+        "-k", "--api-key",
+        default=get_default_env(["OPENAI_API_KEY"], ""),
+        help="API Key (env: OPENAI_API_KEY)"
+    )
+    parser.add_argument(
+        "-s", "--system",
+        default=get_default_env(["OPENAI_SYSTEM_PROMPT"], "You are a helpful assistant."),
+        help="System prompt (env: OPENAI_SYSTEM_PROMPT)"
+    )
+    return parser.parse_args(args)
+
+
+def main(argv=None):
+    args = parse_args(argv)
+    repl = REPL(
+        api_key=args.api_key,
+        endpoint=args.endpoint,
+        model=args.model,
+        system_prompt=args.system,
+    )
+    repl.run()
+
+
+if __name__ == "__main__":
+    main()

askllm_cli-0.1.0/src/askllm_cli.egg-info/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: askllm-cli
+Version: 0.1.0
+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: 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
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# AskLLM
+
+A lightweight, zero-dependency Python REPL for chatting with LLMs via any OpenAI-compatible API.
+
+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
+
+- **Zero Third-Party Runtime Dependencies:** Uses standard library only (`urllib.request`, `json`, `readline`).
+- **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.
+- **Persistent Input History:** Readline history saved across runs in `~/.askllm_history`.
+- **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 these environment variables:
+
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `OPENAI_API_KEY` | Your API key | *(empty / none)* |
+| `OPENAI_ENDPOINT` or `OPENAI_BASE_URL` or `OPENAI_API_BASE` | API base URL or chat endpoint | `https://api.openai.com/v1` |
+| `OPENAI_MODEL` | Default model name | `gpt-4o-mini` |
+| `OPENAI_SYSTEM_PROMPT` | Custom system prompt | `"You are a helpful assistant."` |
+
+---
+
+## 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
+OPENAI_ENDPOINT="http://localhost:11434/v1" OPENAI_MODEL="llama3.2" ./askllm
+```
+
+#### LM Studio / LocalAI / vLLM:
+```bash
+OPENAI_ENDPOINT="http://localhost:1234/v1" OPENAI_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 |
+| `/model [name]` | Show or dynamically switch model |
+| `/endpoint` | Show currently configured endpoint URL |
+| `/system [prompt]` | Show or update the system prompt |
+| `/history` | Show full message history for the session |
+| `/paste` | Enter multiline paste mode |
+| `/exit` or `/quit` | Exit the REPL |
+
+---
+
+## Command-Line Options
+
+```
+usage: askllm [-h] [-v] [-m MODEL] [-e ENDPOINT] [-k API_KEY] [-s SYSTEM]
+
+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: OPENAI_MODEL, default: gpt-4o-mini)
+  -e ENDPOINT, --endpoint ENDPOINT
+                        API Base URL / Endpoint (env: OPENAI_BASE_URL, OPENAI_ENDPOINT, OPENAI_API_BASE)
+  -k API_KEY, --api-key API_KEY
+                        API Key (env: OPENAI_API_KEY)
+  -s SYSTEM, --system SYSTEM
+                        System prompt (env: OPENAI_SYSTEM_PROMPT)
+```

askllm_cli-0.1.0/src/askllm_cli.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/askllm/__init__.py
+src/askllm/__main__.py
+src/askllm/cli.py
+src/askllm_cli.egg-info/PKG-INFO
+src/askllm_cli.egg-info/SOURCES.txt
+src/askllm_cli.egg-info/dependency_links.txt
+src/askllm_cli.egg-info/entry_points.txt
+src/askllm_cli.egg-info/requires.txt
+src/askllm_cli.egg-info/top_level.txt
+tests/test_askllm.py

askllm_cli-0.1.0/src/askllm_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

askllm_cli-0.1.0/src/askllm_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+askllm = askllm.cli:main

askllm_cli-0.1.0/src/askllm_cli.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=7.0

askllm_cli-0.1.0/src/askllm_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+askllm

askllm_cli-0.1.0/tests/test_askllm.py

@@ -0,0 +1,99 @@
+import os
+import unittest
+from unittest.mock import patch
+
+from askllm import __version__, LLMClient, REPL
+from askllm.cli import resolve_chat_url, get_default_env, parse_args
+
+
+class TestAskLLM(unittest.TestCase):
+    def test_version(self):
+        self.assertEqual(__version__, "0.1.0")
+
+    def test_resolve_chat_url(self):
+        self.assertEqual(
+            resolve_chat_url(""),
+            "https://api.openai.com/v1/chat/completions"
+        )
+        self.assertEqual(
+            resolve_chat_url("https://api.openai.com/v1"),
+            "https://api.openai.com/v1/chat/completions"
+        )
+        self.assertEqual(
+            resolve_chat_url("https://api.openai.com/v1/"),
+            "https://api.openai.com/v1/chat/completions"
+        )
+        self.assertEqual(
+            resolve_chat_url("https://api.openai.com/v1/chat/completions"),
+            "https://api.openai.com/v1/chat/completions"
+        )
+        self.assertEqual(
+            resolve_chat_url("http://localhost:11434/v1"),
+            "http://localhost:11434/v1/chat/completions"
+        )
+        self.assertEqual(
+            resolve_chat_url("http://localhost:1234"),
+            "http://localhost:1234/v1/chat/completions"
+        )
+
+    def test_get_default_env(self):
+        with patch.dict(os.environ, {"TEST_KEY_B": "val_b"}, clear=True):
+            self.assertEqual(
+                get_default_env(["TEST_KEY_A", "TEST_KEY_B"], "fallback"),
+                "val_b"
+            )
+            self.assertEqual(
+                get_default_env(["TEST_KEY_NONE"], "fallback"),
+                "fallback"
+            )
+
+    def test_parse_args_defaults(self):
+        with patch.dict(os.environ, {}, clear=True):
+            args = parse_args([])
+            self.assertEqual(args.model, "gpt-4o-mini")
+            self.assertEqual(args.endpoint, "https://api.openai.com/v1")
+            self.assertEqual(args.api_key, "")
+            self.assertEqual(args.system, "You are a helpful assistant.")
+
+    def test_parse_args_custom(self):
+        args = parse_args([
+            "-m", "llama3.2",
+            "-e", "http://localhost:11434/v1",
+            "-k", "my-secret-key",
+            "-s", "Custom system prompt"
+        ])
+        self.assertEqual(args.model, "llama3.2")
+        self.assertEqual(args.endpoint, "http://localhost:11434/v1")
+        self.assertEqual(args.api_key, "my-secret-key")
+        self.assertEqual(args.system, "Custom system prompt")
+
+    def test_repl_commands(self):
+        repl = REPL(
+            api_key="test-key",
+            endpoint="http://localhost:1234/v1",
+            model="gpt-4o",
+            system_prompt="Initial system prompt"
+        )
+        # Add a fake conversation history
+        repl.history.append({"role": "user", "content": "hello"})
+        self.assertEqual(len(repl.history), 1)
+
+        # /reset command
+        handled = repl.handle_command("/reset")
+        self.assertTrue(handled)
+        self.assertEqual(len(repl.history), 0)
+
+        # /model command
+        handled = repl.handle_command("/model claude-3-opus")
+        self.assertTrue(handled)
+        self.assertEqual(repl.model, "claude-3-opus")
+        self.assertEqual(repl.client.model, "claude-3-opus")
+
+        # /system command
+        handled = repl.handle_command("/system New prompt")
+        self.assertTrue(handled)
+        self.assertEqual(repl.system_prompt, "New prompt")
+
+
+if __name__ == "__main__":
+    unittest.main()