grpchook 0.0.2__py3-none-any.whl

examples/interactive_streaming/GrpcServerExample.py

@@ -0,0 +1,16 @@
+"""Minimal gRPC server for the interactive streaming example."""
+from grpchook.baseserver import BaseServer
+
+
+class GrpcServer(BaseServer):
+    """
+    Minimal server for interactive streaming example.
+    """
+
+    def __init__(self, port: int = 49999):
+        super().__init__(port)
+
+
+if __name__ == "__main__":
+    s = GrpcServer(49999)
+    s.serve_forever()

examples/interactive_streaming/LMProxyClient.py

@@ -0,0 +1,100 @@
+"""LM Studio proxy client: receives lm_request, streams lm_response_stream chunks."""
+import threading
+import time
+
+from grpchook import message_pb2
+from grpchook.baseclient import BaseClient
+from grpchook.tools import json_to_struct, struct_to_json
+from examples.interactive_streaming import _lm_http
+from examples.interactive_streaming._lm_http import (
+    _iter_stream, _fetch_sync, _offline_stream, make_http_session,
+)
+
+
+try:
+    import requests
+except ImportError:
+    requests = None
+
+
+class LMProxyClient(BaseClient):
+    """Proxy: receives lm_request, queries LM Studio, streams lm_response_stream chunks."""
+
+    def __init__(self, name: str, port: int, lmstudio_base: str | None = None,
+                 model: str = "gemma-4e2b"):
+        super().__init__(port, name=name, provides=["lm_response_stream"], requires=["lm_request"])
+        self.lmstudio_base = lmstudio_base or "http://127.0.0.1:1234/v1"
+        self.model = model
+
+        if requests:
+            sess = make_http_session()
+            if sess:
+                _lm_http._session = sess
+                self.logger.debug("persistent HTTP session created")
+        else:
+            self.logger.warning("requests not installed — HTTP calls will fail")
+
+        threading.Thread(target=self.spin_forever, daemon=True).start()
+
+    def _send_chunk(self, request: message_pb2.Message, text: str,
+                    done: bool = False):
+        msg = message_pb2.Message(
+            metaInfo=message_pb2.MetaInformation(messageName="lm_response_stream"),
+            payload=message_pb2.Payload(
+                structPayload=json_to_struct({"chunk": text, "done": done})
+            ),
+        )
+        msg.metaInfo.messageId = request.metaInfo.messageId
+        self.send_data(msg)
+
+    def _handle_request(self, request: message_pb2.Message):
+        """Forward an lm_request to LM Studio and stream back the response."""
+        try:
+            prompt = struct_to_json(request.payload.structPayload).get("text", "")
+        except (ValueError, TypeError, AttributeError):
+            prompt = ""
+
+        if not prompt:
+            self._send_chunk(request, "", done=True)
+            return
+
+        mid = request.metaInfo.messageId
+        self.logger.info("Forwarding to LM Studio %s  messageId=%s", self.lmstudio_base, mid)
+
+        had_chunks = False
+        try:
+            for chunk in _iter_stream(prompt, self.lmstudio_base, self.model):
+                if not self.run_event.is_set():
+                    self.logger.debug("proxy shutting down, aborting stream messageId=%s", mid)
+                    return
+                self._send_chunk(request, chunk)
+                had_chunks = True
+        except OSError:
+            self.logger.exception("stream failed messageId=%s", mid)
+
+        if not had_chunks:
+            try:
+                self._send_chunk(request, _fetch_sync(prompt, self.lmstudio_base, self.model))
+                had_chunks = True
+            except OSError:
+                self.logger.exception("sync fetch failed messageId=%s", mid)
+
+        if not had_chunks:
+            self.logger.warning("LM Studio unreachable, using offline stream  messageId=%s", mid)
+            for chunk in _offline_stream(prompt):
+                self._send_chunk(request, chunk)
+
+        self._send_chunk(request, "", done=True)
+
+    def on_receive(self, data: message_pb2.Message) -> bool:
+        threading.Thread(target=self._handle_request, args=(data,), daemon=True).start()
+        return True
+
+
+if __name__ == "__main__":
+    proxy = LMProxyClient("lm-proxy", 49999)
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        proxy.disconnect()

examples/interactive_streaming/TextClient.py

@@ -0,0 +1,102 @@
+"""Interactive text client for the LM Studio streaming example."""
+import uuid
+import queue
+
+from grpchook import message_pb2
+from grpchook.baseclient import BaseClient
+from grpchook.tools import json_to_struct, struct_to_json
+
+
+class TextClient(BaseClient):
+    """
+    Interactive text client. Sends `lm_request` and receives streaming
+    `lm_response_stream` messages (partial chunks with `done` flag).
+    """
+
+    def __init__(self, identifier: str, port: int):
+        super().__init__(port, name=identifier,
+                         provides=["lm_request"],
+                         requires=["lm_response_stream"])
+        self.logger.setLevel("WARNING")
+
+    def on_receive(self, data: message_pb2.Message) -> bool:
+        try:
+            payload = (
+                struct_to_json(data.payload.structPayload)
+                if data.payload and data.payload.structPayload
+                else {}
+            )
+        except (ValueError, TypeError, AttributeError):
+            payload = {}
+
+        chunk = payload.get("chunk", "")
+        done = payload.get("done", False)
+
+        if chunk:
+            print(chunk, end="", flush=True)
+        if done:
+            print()
+        return True
+
+    def interactive_loop(self):
+        """
+        Prompt user, send request, stream responses until `done` True.
+        """
+        try:
+            while True:
+                text = input("You: ").strip()
+                if not text:
+                    continue
+                if text.lower() in ("exit", "quit"):
+                    break
+
+                msg_id = str(uuid.uuid4())
+                msg = message_pb2.Message(
+                    metaInfo=message_pb2.MetaInformation(
+                        messageId=msg_id,
+                        messageName="lm_request",
+                    ),
+                    payload=message_pb2.Payload(structPayload=json_to_struct({"text": text}))
+                )
+
+                self.send_data(msg)
+
+                # collect streaming chunks for this request
+                while True:
+                    try:
+                        resp = self.get_data()
+                    except queue.Empty:
+                        print("\nTimeout waiting for response")
+                        break
+                    except (RuntimeError, OSError) as e:
+                        print("\nClient stopped:", e)
+                        return
+
+                    if resp.metaInfo.messageId != msg_id:
+                        # not for this request; ignore
+                        continue
+
+                    try:
+                        payload = (
+                            struct_to_json(resp.payload.structPayload)
+                            if resp.payload and resp.payload.structPayload
+                            else {}
+                        )
+                    except (ValueError, TypeError, AttributeError):
+                        payload = {}
+
+                    chunk = payload.get("chunk", "")
+                    done = payload.get("done", False)
+                    if chunk:
+                        print(chunk, end="", flush=True)
+                    if done:
+                        print()
+                        break
+
+        finally:
+            self.disconnect()
+
+
+if __name__ == "__main__":
+    client = TextClient("text-ui", 49999)
+    client.interactive_loop()

examples/interactive_streaming/_lm_http.py

@@ -0,0 +1,144 @@
+"""HTTP helpers for LMProxyClient: streaming/sync LM Studio calls."""
+
+import json
+import logging
+import os
+import re
+import time
+
+try:
+    import requests
+    from requests.adapters import HTTPAdapter as _HTTPAdapter
+except ImportError:
+    requests = None
+    _HTTPAdapter = None
+
+from grpchook.logger import get_logger
+
+SYSTEM_PROMPT = os.environ.get(
+    "LMSTUDIO_SYSTEM_PROMPT",
+    "Use only printable UTF-8 characters. Reply in plain text without special symbols or emojis.",
+)
+
+# Set by LMProxyClient.__init__() to a persistent requests.Session.
+_session = None
+
+
+def _sanitize_text(s: object) -> str:
+    if s is None:
+        return ""
+    if isinstance(s, bytes):
+        s = s.decode("utf-8", errors="ignore")
+    s = str(s)
+    s = s.replace("\ufffd", "")
+    s = re.sub(r"[\x00-\x08\x0b-\x0c\x0e-\x1f\x7f]", "", s)
+    return s
+
+
+def _build_messages(prompt: str) -> list:
+    return [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user",   "content": prompt},
+    ]
+
+
+def _extract_text(j: dict) -> str | None:
+    """Return the text content from a parsed SSE JSON object, or None."""
+    if "choices" in j and j["choices"]:
+        c = j["choices"][0]
+        return c.get("delta", {}).get("content") or c.get("text")
+    return j.get("text") or j.get("token")
+
+
+def _iter_stream(prompt: str, base_url: str, model: str):
+    """Stream from OpenAI-compatible /chat/completions. Yields sanitized text chunks."""
+    api_key = os.environ.get("LMSTUDIO_API_KEY") or os.environ.get("OPENAI_API_KEY")
+    url = base_url.rstrip("/") + "/chat/completions"
+    headers = {"Accept": "text/event-stream", "Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    payload = {"model": model, "messages": _build_messages(prompt), "stream": True}
+    log = get_logger("LMProxyClient", log_level=logging.DEBUG)
+    sess = _session or requests
+    log.debug("stream POST %s model=%s", url, model)
+    n_chunks = 0
+    with sess.post(url, json=payload, stream=True, headers=headers, timeout=(5, None)) as r:
+        log.debug("stream response status=%s", r.status_code)
+        if not 200 <= r.status_code < 300:
+            log.warning("stream got non-2xx status=%s", r.status_code)
+            return
+        for raw in r.iter_lines(decode_unicode=False):
+            if not raw:
+                continue
+            line = (
+                raw.decode("utf-8", errors="ignore").strip()
+                if isinstance(raw, bytes)
+                else str(raw).strip()
+            )
+            if line.startswith("data: "):
+                line = line[6:]
+            if line == "[DONE]":
+                log.debug("stream [DONE] after %d chunks", n_chunks)
+                return
+            try:
+                j = json.loads(line)
+            except json.JSONDecodeError:
+                yield _sanitize_text(line)
+                n_chunks += 1
+                continue
+            text = _extract_text(j)
+            if text:
+                if n_chunks == 0:
+                    log.debug("stream first chunk received")
+                n_chunks += 1
+                yield _sanitize_text(text)
+
+
+def _fetch_sync(prompt: str, base_url: str, model: str) -> str:
+    """Synchronous /chat/completions fallback. Returns text or raises."""
+    api_key = os.environ.get("LMSTUDIO_API_KEY") or os.environ.get("OPENAI_API_KEY")
+    url = base_url.rstrip("/") + "/chat/completions"
+    headers = {"Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    payload = {"model": model, "messages": _build_messages(prompt)}
+    log = get_logger("LMProxyClient", log_level=logging.DEBUG)
+    sess = _session or requests
+    log.debug("sync POST %s model=%s", url, model)
+    r = sess.post(url, json=payload, headers=headers, timeout=30)
+    log.debug("sync response status=%s", r.status_code)
+    r.raise_for_status()
+    j = r.json()
+    if "choices" in j and j["choices"]:
+        c = j["choices"][0]
+        text = (c.get("message") or {}).get("content") or c.get("text")
+        if text:
+            log.debug("sync got text len=%d", len(text))
+            return _sanitize_text(text)
+    raise RuntimeError("No text in sync response")
+
+
+def _offline_stream(_prompt: str):
+    """Multi-chunk offline fallback when LM Studio is unreachable."""
+    chunks = [
+        "LM Studio is not available. This is a static offline response.",
+        " It simulates streaming by sending multiple chunks.",
+        " Use it to test client rendering and chunk reassembly.",
+    ]
+    for chunk in chunks:
+        yield _sanitize_text(chunk)
+        time.sleep(0.05)
+
+
+def make_http_session():
+    """Create a persistent requests.Session with connection pooling.
+
+    Returns None when requests is not installed.
+    """
+    if requests is None or _HTTPAdapter is None:
+        return None
+    sess = requests.Session()
+    adapter = _HTTPAdapter(pool_connections=4, pool_maxsize=16)
+    sess.mount("http://", adapter)
+    sess.mount("https://", adapter)
+    return sess

examples/interactive_streaming/readme.md

@@ -0,0 +1,48 @@
+# interactive_streaming
+
+Bidirectional streaming chat demo using **LM Studio** as the LLM backend.
+A proxy client forwards user prompts to LM Studio and streams the response back token-by-token.
+
+## Architecture
+
+```
+TextClient  ──lm_request──►  GrpcServer  ──lm_request──►  LMProxyClient
+            ◄─lm_response_stream──────────────────────────  (HTTP → LM Studio)
+```
+
+- **GrpcServer** — plain `BaseServer`, no custom logic.
+- **LMProxyClient** — receives `lm_request`, calls LM Studio `/v1/chat/completions` (streaming), sends back `lm_response_stream` chunks with a `done` flag.
+- **TextClient** — interactive CLI; reads user input, sends `lm_request`, prints streaming chunks as they arrive.
+
+## Requirements
+
+- LM Studio running locally at `http://127.0.0.1:1234` with a model loaded (default: `gemma-4e2b`).
+- `pip install requests` (included in `requirements_examples.txt`).
+
+> If LM Studio is not running, `LMProxyClient` falls back to an offline stub that echoes the prompt.
+
+## How to run
+
+**Option A — two separate terminals:**
+
+```
+# Terminal 1: server + proxy together
+python examples/interactive_streaming/run_server_proxy.py
+
+# Terminal 2: interactive text UI
+python examples/interactive_streaming/run_text_client.py
+```
+
+**Option B — three separate processes:**
+
+```
+python examples/interactive_streaming/GrpcServerExample.py
+python examples/interactive_streaming/LMProxyClient.py
+python examples/interactive_streaming/TextClient.py
+```
+
+Type a prompt in the `TextClient` terminal and the LLM response streams back live. `exit` or `quit` to stop.
+
+## TL;DR
+
+Start `run_server_proxy.py`, then `run_text_client.py`. Type prompts, get streamed LLM responses. Needs LM Studio running locally.

examples/interactive_streaming/run_server_proxy.py

@@ -0,0 +1,26 @@
+"""Launch the gRPC server and LM proxy client for the interactive streaming example."""
+import threading
+import time
+
+from examples.interactive_streaming.GrpcServerExample import GrpcServer
+from examples.interactive_streaming.LMProxyClient import LMProxyClient
+
+
+def main():
+    server = GrpcServer(49999)
+    server_thread = threading.Thread(target=server.serve_forever, daemon=True)
+    server_thread.start()
+
+    # start LM proxy client (connects automatically)
+    proxy = LMProxyClient("lm-proxy", 49999)
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        proxy.disconnect()
+        server.shutdown()
+
+
+if __name__ == "__main__":
+    main()

examples/interactive_streaming/run_text_client.py

@@ -0,0 +1,14 @@
+"""Launch the interactive text client for the LM Studio streaming example."""
+from examples.interactive_streaming.TextClient import TextClient
+
+
+def main():
+    client = TextClient("text-ui", 49999)
+    try:
+        client.interactive_loop()
+    except KeyboardInterrupt:
+        client.disconnect()
+
+
+if __name__ == "__main__":
+    main()

examples/mcp_server/FileOperationClient.py

@@ -0,0 +1,200 @@
+"""gRPC client that executes sandboxed file operations (create / edit / delete)."""
+import os
+import tempfile
+import threading
+from pathlib import Path
+
+from grpchook.baseclient import BaseClient
+from grpchook import message_pb2
+from grpchook.tools import struct_to_json, json_to_struct
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+
+MCP_OPERATIONS = ["mcp.file.create", "mcp.file.edit", "mcp.file.delete"]
+MCP_RESPONSE    = "mcp.file.response"
+
+# Use the OS temp directory so no project files are ever touched.
+# Windows: %TMP% / %TEMP%   Unix: $TMPDIR / /tmp
+BASE_DIR      = Path(tempfile.gettempdir()) / "mcp_server"
+MAX_FILE_SIZE = 1024 * 1024  # 1 MB
+
+
+# ── FileOperationClient ──────────────────────────────────────────────────────
+
+class FileOperationClient(BaseClient):
+    """
+    gRPC client that executes sandboxed file operations (create / edit / delete).
+
+    Receives mcp.file.{create,edit,delete} messages from the gRPC server,
+    executes the requested file operation (restricted to BASE_DIR), and
+    sends back an mcp.file.response message to the original requester.
+
+    Security
+    --------
+    - All paths are resolved with Path.resolve() + relative_to() so that
+      any attempt to escape BASE_DIR (e.g. via "..") is rejected.
+    - Content size is capped at MAX_FILE_SIZE bytes.
+    - Writes are atomic: temp file → os.replace().
+    """
+
+    def __init__(self, port: int):
+        BASE_DIR.mkdir(parents=True, exist_ok=True)
+        super().__init__(
+            name="FileOperationClient",
+            port=port,
+            requires=MCP_OPERATIONS,
+            provides=[MCP_RESPONSE],
+        )
+
+    def on_init(self):
+        self.logger.info(
+            "FileOperationClient ready.  ALL file operations are restricted to: %s",
+            BASE_DIR.resolve(),
+        )
+        # Drive on_receive() from a background thread so the client processes
+        # incoming messages without the caller needing to call spin_forever().
+        threading.Thread(target=self.spin_forever, daemon=True).start()
+
+    # ── Path safety ───────────────────────────────────────────────────────────
+
+    def _safe_path(self, rel_path: str) -> Path | None:
+        """
+        Resolve *rel_path* relative to BASE_DIR.
+        Returns None when the resolved path escapes BASE_DIR.
+        """
+        if not rel_path:
+            return None
+        try:
+            target = (BASE_DIR / rel_path).resolve()
+            target.relative_to(BASE_DIR.resolve())  # raises ValueError if outside
+            return target
+        except (ValueError, OSError):
+            return None
+
+    # ── Response helper ───────────────────────────────────────────────────────
+
+    def _make_response(self, ok: bool, operation: str, path: str,
+                       error: str = "") -> message_pb2.Message:
+        payload: dict = {"ok": ok, "operation": operation, "path": path}
+        if error:
+            payload["error"] = error
+        return message_pb2.Message(
+            metaInfo=message_pb2.MetaInformation(messageName=MCP_RESPONSE),
+            payload=message_pb2.Payload(structPayload=json_to_struct(payload)),
+        )
+
+    # ── File operations ───────────────────────────────────────────────────────
+
+    def _handle_create(self, data: dict) -> tuple[bool, str]:
+        """Atomically create a new file at *data['path']* with *data['content']*."""
+        path    = data.get("path", "")
+        content = data.get("content", "")
+        enc     = data.get("encoding", "utf-8")
+
+        target = self._safe_path(path)
+        if target is None:
+            return False, f"path '{path}' is outside the allowed directory"
+        if target.exists():
+            return False, f"file already exists: {path}"
+        if len(content.encode(enc, errors="replace")) > MAX_FILE_SIZE:
+            return False, f"content exceeds {MAX_FILE_SIZE} bytes"
+
+        target.parent.mkdir(parents=True, exist_ok=True)
+        tmp = target.with_suffix(target.suffix + ".tmp")
+        try:
+            self.logger.info("create: writing to '%s'", target)
+            tmp.write_text(content, encoding=enc)
+            os.replace(tmp, target)
+            self.logger.info("create: file written at '%s'", target)
+            return True, ""
+        except OSError as exc:
+            tmp.unlink(missing_ok=True)
+            return False, str(exc)
+
+    def _handle_edit(self, data: dict) -> tuple[bool, str]:
+        """Atomically overwrite an existing file at *data['path']* with *data['content']*."""
+        path    = data.get("path", "")
+        content = data.get("content", "")
+        enc     = data.get("encoding", "utf-8")
+
+        target = self._safe_path(path)
+        if target is None:
+            return False, f"path '{path}' is outside the allowed directory"
+        if not target.exists():
+            return False, f"file does not exist: {path}"
+        if len(content.encode(enc, errors="replace")) > MAX_FILE_SIZE:
+            return False, f"content exceeds {MAX_FILE_SIZE} bytes"
+
+        tmp = target.with_suffix(target.suffix + ".tmp")
+        try:
+            self.logger.info("edit: overwriting '%s'", target)
+            tmp.write_text(content, encoding=enc)
+            os.replace(tmp, target)
+            self.logger.info("edit: file updated at '%s'", target)
+            return True, ""
+        except OSError as exc:
+            tmp.unlink(missing_ok=True)
+            return False, str(exc)
+
+    def _handle_delete(self, data: dict) -> tuple[bool, str]:
+        """Remove the file at *data['path']* if it exists inside BASE_DIR."""
+        path = data.get("path", "")
+
+        target = self._safe_path(path)
+        if target is None:
+            return False, f"path '{path}' is outside the allowed directory"
+        if not target.exists():
+            return False, f"file does not exist: {path}"
+
+        try:
+            self.logger.info("delete: removing '%s'", target)
+            target.unlink()
+            self.logger.info("delete: file removed at '%s'", target)
+            return True, ""
+        except OSError as exc:
+            return False, str(exc)
+
+    # ── Hook ────────────────────────────────────────────────────────────────────────────
+
+    def on_receive(self, data: message_pb2.Message) -> bool:
+        """Dispatch incoming file operation requests to the appropriate handler."""
+        operation = data.metaInfo.messageName
+        payload   = struct_to_json(data.payload.structPayload)
+        path      = payload.get("path", "")
+
+        self.logger.info("op=%s  path='%s'", operation, path)
+
+        if operation == "mcp.file.create":
+            ok, error = self._handle_create(payload)
+        elif operation == "mcp.file.edit":
+            ok, error = self._handle_edit(payload)
+        elif operation == "mcp.file.delete":
+            ok, error = self._handle_delete(payload)
+        else:
+            self.logger.warning("Unknown operation: %s", operation)
+            return True
+
+        abs_path = self._safe_path(path)
+
+        if ok:
+            self.logger.info("op=%s  rel='%s'  abs='%s'  -> OK",
+                             operation, path, abs_path)
+        else:
+            self.logger.warning("op=%s  rel='%s'  -> FAIL: %s", operation, path, error)
+
+        response = self._make_response(ok, operation, path, error)
+        response.metaInfo.messageId = data.metaInfo.messageId
+        self.send_data(response)
+        return True
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    client = FileOperationClient(49998)
+    try:
+        client.spin_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        client.disconnect()

examples/mcp_server/GrpcServer.py

@@ -0,0 +1,22 @@
+"""Plain gRPC relay server for the mcp_server example."""
+from grpchook.baseserver import BaseServer
+
+
+class McpGrpcServer(BaseServer):
+    """
+    Plain gRPC server for the mcp_server example.
+
+    No custom routing logic needed — the default on_receive() returns True
+    so every message is fanned out via DataRegister to all subscribers.
+    """
+
+    def __init__(self, port: int):
+        super().__init__(port, name="McpGrpcServer")
+
+    def on_init(self):
+        self.logger.info("McpGrpcServer ready on port %d", self._port)
+
+
+if __name__ == "__main__":
+    server = McpGrpcServer(49998)
+    server.serve_forever()