qsp-client 0.3.0__py3-none-any.whl

qsp_client/__init__.py

@@ -0,0 +1,10 @@
+"""QSP client — relay MCP tools to any OpenAI-compatible local LLM endpoint."""
+
+from __future__ import annotations
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("qsp-client")
+except Exception:
+    __version__ = "0.0.0-dev"

qsp_client/cli.py

@@ -0,0 +1,243 @@
+"""CLI entry point for qsp-client.
+
+Supports two modes:
+- Interactive: readline-enabled chat loop
+- Single query: --query "..." for one-shot usage
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import load_config
+from .relay import QSPRelay
+
+DEFAULT_CONFIG_PATHS = [
+    Path.home() / ".config" / "qsp-client" / "config.json",
+    Path.home() / ".qsp-client.json",
+    # From when this was qsp-mcp; still read so existing setups keep working.
+    Path.home() / ".config" / "qsp-mcp" / "config.json",
+    Path.home() / ".qsp-mcp.json",
+]
+
+
+def _find_config() -> Path | None:
+    """Find the default config file."""
+    for path in DEFAULT_CONFIG_PATHS:
+        if path.exists():
+            return path
+    return None
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="qsp-client",
+        description="QSP — relay MCP tools to any OpenAI-compatible LLM endpoint",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"qsp-client {__version__}"
+    )
+    parser.add_argument(
+        "--config", "-c",
+        type=str,
+        default=None,
+        help="Path to config file (default: ~/.config/qsp-client/config.json)",
+    )
+    parser.add_argument(
+        "--endpoint", "-e",
+        type=str,
+        default=None,
+        help="LLM endpoint URL (overrides config)",
+    )
+    parser.add_argument(
+        "--api-key", "-k",
+        type=str,
+        default=None,
+        help="API key for the LLM endpoint",
+    )
+    parser.add_argument(
+        "--model", "-m",
+        type=str,
+        default=None,
+        help="Model name (overrides config)",
+    )
+    parser.add_argument(
+        "--profile", "-p",
+        type=str,
+        default=None,
+        help="Tool profile to use (e.g., contest, dx, propagation, full)",
+    )
+    parser.add_argument(
+        "--query", "-q",
+        type=str,
+        default=None,
+        help="Single query mode — ask one question and exit",
+    )
+    parser.add_argument(
+        "--enable-writes",
+        action="store_true",
+        default=False,
+        help="Enable write-capable tools (disabled by default for safety)",
+    )
+    parser.add_argument(
+        "--list-tools",
+        action="store_true",
+        default=False,
+        help="List available tools and exit",
+    )
+
+    return parser.parse_args()
+
+
+async def _run(args: argparse.Namespace) -> int:
+    """Main async entry point."""
+    # Find config
+    config_path = args.config
+    if config_path is None:
+        found = _find_config()
+        if found:
+            config_path = str(found)
+
+    if config_path is None and args.endpoint is None:
+        print(
+            "Error: No config file found and no --endpoint specified.\n"
+            "Create ~/.config/qsp-client/config.json or use --endpoint.\n"
+            "See: https://github.com/qso-graph/qsp-client",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        config = load_config(
+            config_path,
+            endpoint=args.endpoint,
+            api_key=args.api_key,
+            model=args.model,
+            profile=args.profile,
+            enable_writes=args.enable_writes,
+        )
+    except (FileNotFoundError, ValueError) as e:
+        print(f"Config error: {e}", file=sys.stderr)
+        return 1
+
+    if not config.servers:
+        print(
+            "Error: No MCP servers configured in mcpServers block.",
+            file=sys.stderr,
+        )
+        return 1
+
+    relay = QSPRelay(config, enable_writes=args.enable_writes)
+
+    try:
+        await relay.start()
+    except RuntimeError as e:
+        print(f"Startup failed: {e}", file=sys.stderr)
+        return 1
+
+    try:
+        # List tools mode
+        if args.list_tools:
+            print(relay.get_tool_summary())
+            for tool in relay._openai_tools:
+                func = tool["function"]
+                server = relay._tool_server_map.get(func["name"], "?")
+                print(f"  [{server}] {func['name']}: {func['description'][:80]}")
+            return 0
+
+        # Single query mode
+        if args.query:
+            response = await relay.query(args.query, [])
+            print(response)
+            return 0
+
+        # Interactive mode
+        return await _interactive_loop(relay, config.bridge.max_history_turns)
+
+    finally:
+        await relay.stop()
+
+
+async def _interactive_loop(relay: QSPRelay, max_history: int) -> int:
+    """Interactive chat loop with readline support."""
+    history: list[dict[str, str]] = []
+
+    print(
+        f"qsp-client {__version__} — type your question, or 'quit' to exit.\n"
+        f"Servers:\n{relay.get_tool_summary()}\n"
+    )
+
+    while True:
+        try:
+            user_input = input("You> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\n73!")
+            break
+
+        if not user_input:
+            continue
+
+        if user_input.lower() in ("quit", "exit", "q", "73"):
+            print("73!")
+            break
+
+        if user_input.lower() == "/tools":
+            print(relay.get_tool_summary())
+            for tool in relay._openai_tools:
+                func = tool["function"]
+                server = relay._tool_server_map.get(func["name"], "?")
+                print(f"  [{server}] {func['name']}")
+            continue
+
+        if user_input.lower() == "/help":
+            print(
+                "Commands:\n"
+                "  /tools  — list available tools\n"
+                "  /help   — show this help\n"
+                "  quit    — exit (or 73)\n"
+            )
+            continue
+
+        try:
+            response = await relay.query(user_input, history)
+        except Exception as e:
+            print(f"[qsp] Error: {type(e).__name__}: {e}", file=sys.stderr)
+            continue
+
+        print(f"\n{response}\n")
+
+        # Update sliding window history
+        history.append({"role": "user", "content": user_input})
+        history.append({"role": "assistant", "content": response})
+
+        # Trim to max_history turns (each turn = user + assistant = 2 messages)
+        max_messages = max_history * 2
+        if len(history) > max_messages:
+            history = history[-max_messages:]
+
+    return 0
+
+
+def main() -> None:
+    """Entry point for the qsp-client CLI."""
+    try:
+        exit_code = asyncio.run(_run(_parse_args()))
+    except KeyboardInterrupt:
+        print("\n73!")
+        exit_code = 0
+    sys.exit(exit_code)
+
+
+def main_renamed() -> None:
+    """The old `qsp-mcp` command: still works, and says where it went."""
+    print("Note: qsp-mcp is now qsp-client; the qsp-mcp command will be removed in a later release.",
+          file=sys.stderr)
+    main()
+
+
+if __name__ == "__main__":
+    main()

qsp_client/client.py

@@ -0,0 +1,130 @@
+"""HTTP client for OpenAI-compatible LLM endpoints.
+
+Handles chat completions with function calling support.
+Non-streaming only for v1 (streaming buffering is post-v1).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+
+class LLMClient:
+    """Client for OpenAI-compatible chat completions API."""
+
+    def __init__(
+        self,
+        endpoint: str,
+        *,
+        api_key: str | None = None,
+        model: str = "default",
+        max_tokens: int = 2048,
+        temperature: float = 0.3,
+        timeout: float = 120.0,
+    ) -> None:
+        self._endpoint = endpoint
+        self._model = model
+        self._max_tokens = max_tokens
+        self._temperature = temperature
+
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+
+        self._http = httpx.Client(
+            headers=headers,
+            timeout=httpx.Timeout(timeout, connect=10.0),
+        )
+
+    def chat(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        *,
+        temperature: float | None = None,
+        tool_choice: str = "auto",
+    ) -> dict[str, Any]:
+        """Send a chat completion request.
+
+        Returns the raw response dict from the LLM endpoint.
+        """
+        payload: dict[str, Any] = {
+            "model": self._model,
+            "messages": messages,
+            "max_tokens": self._max_tokens,
+            "temperature": temperature if temperature is not None else self._temperature,
+        }
+
+        if tools:
+            payload["tools"] = tools
+            payload["tool_choice"] = tool_choice
+
+        resp = self._http.post(self._endpoint, json=payload)
+        resp.raise_for_status()
+
+        return resp.json()
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> LLMClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+def extract_tool_calls(response: dict[str, Any]) -> list[dict[str, Any]]:
+    """Extract tool calls from a chat completion response.
+
+    Returns list of dicts with: id, name, arguments (parsed JSON).
+    Returns empty list if no tool calls.
+    """
+    choices = response.get("choices", [])
+    if not choices:
+        return []
+
+    message = choices[0].get("message", {})
+    raw_calls = message.get("tool_calls", [])
+
+    tool_calls = []
+    for call in raw_calls:
+        func = call.get("function", {})
+        args_str = func.get("arguments", "{}")
+
+        try:
+            arguments = json.loads(args_str)
+        except json.JSONDecodeError:
+            arguments = {"_raw": args_str, "_parse_error": True}
+
+        tool_calls.append(
+            {
+                "id": call.get("id", ""),
+                "name": func.get("name", ""),
+                "arguments": arguments,
+            }
+        )
+
+    return tool_calls
+
+
+def extract_text(response: dict[str, Any]) -> str:
+    """Extract text content from a chat completion response."""
+    choices = response.get("choices", [])
+    if not choices:
+        return ""
+
+    message = choices[0].get("message", {})
+    return message.get("content", "") or ""
+
+
+def get_finish_reason(response: dict[str, Any]) -> str:
+    """Get the finish reason from a response."""
+    choices = response.get("choices", [])
+    if not choices:
+        return ""
+    return choices[0].get("finish_reason", "")

qsp_client/config.py

@@ -0,0 +1,147 @@
+"""Configuration loader for qsp-client.
+
+Config format is Claude Desktop compatible — users can copy their existing
+mcpServers block directly. The 'bridge' section is qsp-client specific.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class ServerConfig:
+    """MCP server configuration — matches Claude Desktop format."""
+
+    name: str
+    command: str
+    args: list[str] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class ProfileConfig:
+    """Tool profile — subset of servers with model-specific params."""
+
+    servers: list[str] | str  # list of server names or "*" for all
+    temperature: float = 0.3
+    system_prompt: str | None = None
+
+
+@dataclass
+class BridgeConfig:
+    """Bridge-specific configuration."""
+
+    endpoint: str = "http://localhost:8000/v1/chat/completions"
+    api_key: str | None = None
+    model: str = "default"
+    max_tokens: int = 2048
+    temperature: float = 0.3
+    system_prompt: str = "You are an expert ham radio operator and RF engineer."
+    max_history_turns: int = 5
+    max_tool_calls_per_turn: int = 5
+    tool_timeout_seconds: float = 5.0
+    profile: str = "full"
+    profiles: dict[str, ProfileConfig] = field(default_factory=dict)
+    server_timeouts: dict[str, float] = field(default_factory=dict)
+
+
+@dataclass
+class Config:
+    """Top-level qsp-client configuration."""
+
+    servers: dict[str, ServerConfig] = field(default_factory=dict)
+    bridge: BridgeConfig = field(default_factory=BridgeConfig)
+
+
+def load_config(
+    config_path: str | Path | None = None,
+    *,
+    endpoint: str | None = None,
+    api_key: str | None = None,
+    model: str | None = None,
+    profile: str | None = None,
+    enable_writes: bool = False,
+) -> Config:
+    """Load config from file, with CLI overrides applied on top."""
+    if config_path is not None:
+        path = Path(config_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Config file not found: {path}")
+        raw = json.loads(path.read_text())
+    else:
+        raw = {}
+
+    config = _parse_config(raw)
+
+    # CLI overrides take precedence
+    if endpoint is not None:
+        config.bridge.endpoint = endpoint
+    if api_key is not None:
+        config.bridge.api_key = api_key
+    if model is not None:
+        config.bridge.model = model
+    if profile is not None:
+        config.bridge.profile = profile
+
+    return config
+
+
+def _parse_config(raw: dict[str, Any]) -> Config:
+    """Parse raw JSON dict into typed Config."""
+    config = Config()
+
+    # Parse mcpServers (Claude Desktop compatible)
+    for name, server_raw in raw.get("mcpServers", {}).items():
+        config.servers[name] = ServerConfig(
+            name=name,
+            command=server_raw.get("command", ""),
+            args=server_raw.get("args", []),
+            env=server_raw.get("env", {}),
+        )
+
+    # Parse bridge section
+    bridge_raw = raw.get("bridge", {})
+    config.bridge = BridgeConfig(
+        endpoint=bridge_raw.get("endpoint", config.bridge.endpoint),
+        api_key=bridge_raw.get("api_key", config.bridge.api_key),
+        model=bridge_raw.get("model", config.bridge.model),
+        max_tokens=bridge_raw.get("max_tokens", config.bridge.max_tokens),
+        temperature=bridge_raw.get("temperature", config.bridge.temperature),
+        system_prompt=bridge_raw.get("system_prompt", config.bridge.system_prompt),
+        max_history_turns=bridge_raw.get(
+            "max_history_turns", config.bridge.max_history_turns
+        ),
+        max_tool_calls_per_turn=bridge_raw.get(
+            "max_tool_calls_per_turn", config.bridge.max_tool_calls_per_turn
+        ),
+        tool_timeout_seconds=bridge_raw.get(
+            "tool_timeout_seconds", config.bridge.tool_timeout_seconds
+        ),
+        profile=bridge_raw.get("profile", config.bridge.profile),
+        server_timeouts={
+            k: float(v) for k, v in bridge_raw.get("server_timeouts", {}).items()
+        },
+    )
+
+    # Parse profiles
+    for name, prof_raw in bridge_raw.get("profiles", {}).items():
+        config.bridge.profiles[name] = ProfileConfig(
+            servers=prof_raw.get("servers", "*"),
+            temperature=prof_raw.get("temperature", config.bridge.temperature),
+            system_prompt=prof_raw.get("system_prompt"),
+        )
+
+    # Ensure "full" profile always exists
+    if "full" not in config.bridge.profiles:
+        config.bridge.profiles["full"] = ProfileConfig(servers="*")
+
+    return config
+
+
+def get_api_key(config: Config) -> str | None:
+    """Get API key from config."""
+    return config.bridge.api_key