grpchook 0.0.2__tar.gz

grpchook-0.0.2/LICENSE.txt

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Fabian Krumm
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

grpchook-0.0.2/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.1
+Name: grpchook
+Version: 0.0.2
+Summary: grpchook (grpc + hook) is an asynchronous Python gRPC bidirectional-streaming framework. Subclass BaseServer/BaseClient, override hooks — the base handles all gRPC plumbing.
+Author-Email: Fabian Krumm <ghub_fk@gmx.de>
+Classifier: Programming Language :: Python :: 3
+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: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Networking
+Project-URL: homepage, https://github.com/fwkrumm/grpchook
+Requires-Python: >=3.10
+Requires-Dist: grpcio>=1.81.0
+Requires-Dist: grpcio-tools>=1.81.0
+Requires-Dist: protobuf>=6.0.0
+Requires-Dist: coloredlogs>=15.0
+Requires-Dist: psutil>=5.0.0
+Description-Content-Type: text/markdown
+
+# grpchook
+
+**grpchook** (gRPC + hook) is a Python framework for building asynchronous gRPC bidirectional-streaming services. Subclass `BaseServer` and `BaseClient`, override the hooks you need — the framework handles all gRPC plumbing.
+
+[![PyPI](https://img.shields.io/pypi/v/grpchook)](https://pypi.org/project/grpchook/)
+[![Python](https://img.shields.io/pypi/pyversions/grpchook)](https://pypi.org/project/grpchook/)
+[![License](https://img.shields.io/badge/license-BSD%203--Clause-blue)](LICENSE.txt)
+
+> **Status: Work in Progress.**
+> The project is open source and will remain open source.
+> Treat with caution. If you depend on it, **pin your version**.
+
+---
+
+## Table of Contents
+
+- [Disclaimer](#disclaimer)
+- [When to Use and When Not to Use grpchook](#when-to-use-and-when-not-to-use-grpchook)
+- [Requirements](#requirements)
+- [Installation](#installation)
+  - [From PyPI](#from-pypi)
+  - [From Source](#from-source)
+- [Quick Start](#quick-start)
+- [Examples](#examples)
+- [Testing](#testing)
+- [Regenerating the gRPC Interface](#regenerating-the-grpc-interface)
+- [ToDos & Roadmap](#todos-roadmap)
+- [Known Issues & Troubleshooting](#known-issues-troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+- [Release History](#release-history)
+
+---
+<a name="disclaimer"></a>
+<a id="disclaimer"></a>
+
+## Disclaimer
+
+Core concept by a human developer. AI was used to assist with unit and integration tests, examples, documentation, and selected code sections. Core logic has been reviewed by a human; the test suite has not been fully audited — there may be AI-introduced oversights. Please report any issues you find.
+
+This software is provided **"as is"**, without warranty of any kind. The developer is not responsible for any damage, data loss, security vulnerabilities, or other issues that may arise from using this software. **You use it at your own risk.** See [LICENSE.txt](LICENSE.txt) for the full BSD 3-Clause terms.
+
+
+---
+<a name="when-to-use-and-when-not-to-use-grpchook"></a>
+<a id="when-to-use-and-when-not-to-use-grpchook"></a>
+## When to Use and When Not to Use grpchook
+
+### When to Use grpchook
+- You need a simple, Python-based gRPC bidirectional streaming server and client.
+- You want a data exchange blueprint for developers or AI agents to build on top of.
+- You want a framework that can be extended with custom hooks for specific events.
+- You want to distribute clients to many different machines (e.g. voice recorder, voice to text, text to LLM, and vice versa until the final response is replayed)
+
+  **Example — four clients on four machines, all routed through one grpchook server:**
+
+  > 💡 Diagram requires the [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) extension to render in VS Code.
+
+  ```mermaid
+  flowchart LR
+      subgraph M1["📦 Machine 1"]
+          VR["🎤 Voice Recorder"]
+      end
+      subgraph M2["📦 Machine 2"]
+          STT["📝 Speech-to-Text"]
+      end
+      subgraph M3["📦 Machine 3"]
+          LLM["🤖 LLM Processor"]
+      end
+      subgraph M4["📦 Machine 4"]
+          RP["🔊 Voice Replay"]
+      end
+
+      SRV(["⚙️ grpchook Server"])
+
+      VR  -->|"① audio"| SRV
+      SRV -->|"① audio"| STT
+      STT -->|"② transcript"| SRV
+      SRV -->|"② transcript"| LLM
+      LLM -->|"③ llm_response"| SRV
+      SRV -->|"③ llm_response"| RP
+  ```
+
+### When Not to Use grpchook
+- When you need a very large number of clients; the threading model may introduce overhead.
+- When you need direct peer-to-peer communication without a server intermediary; grpchook routes all messages through a central server.
+- You want a framework that supports multiple programming languages out of the box; grpchook is (currently) Python-only.
+
+---
+<a name="requirements"></a>
+<a id="requirements"></a>
+
+## Requirements
+
+- Python 3.10 or later
+- A dedicated virtual environment is **strongly recommended** — gRPC version conflicts with other packages are common when using grpchook.
+
+---
+<a name="installation"></a>
+<a id="installation"></a>
+
+## Installation
+
+<a name="from-pypi"></a>
+<a id="from-pypi"></a>
+### From PyPI
+
+```bash
+pip install grpchook
+```
+
+<a name="from-source"></a>
+<a id="from-source"></a>
+### From Source
+
+```bash
+git clone https://github.com/fwkrumm/grpchook.git
+cd grpchook
+pip install -e .
+```
+
+---
+<a name="quick-start"></a>
+<a id="quick-start"></a>
+
+## Quick Start
+
+Refer to [HOW_TO.md](grpchook/assets/HOW_TO.md) for the full API reference and code examples.
+Alternatively run
+
+```bash
+python -m grpchook --generate-skeletons
+```
+
+to generate a very basic server and client skeleton in the current directory.
+Use
+
+```bash
+python -m grpchook --generate-interface-with-skeletons
+```
+
+to generate the skeletons along with a copy of the `message.proto` interface file in the current directory to modify which is then used by the skeletons.
+
+---
+<a name="examples"></a>
+<a id="examples"></a>
+
+## Examples
+
+Runnable examples are available in two locations:
+
+- `examples/` — self-contained, scenario-focused examples
+- `tests/integration/` — integration test scenarios covering a broad range of use cases
+
+Run them on a machine with adequate resources; some scenarios are resource-intensive.
+
+---
+<a name="testing"></a>
+<a id="testing"></a>
+
+## Testing
+
+Install dev dependencies and run the unit tests:
+
+```bash
+pip install -r requirements_dev.txt
+python -m unittest discover -s tests
+```
+
+Integration tests are in `tests/integration/` and can be run via:
+
+```bash
+python tests/integration/run_integration_tests.py
+```
+
+---
+<a name="regenerating-the-grpc-interface"></a>
+<a id="regenerating-the-grpc-interface"></a>
+
+
+## Regenerating the gRPC Interface
+
+If you modify `grpchook/message.proto` after cloning the repository, regenerate the Python bindings with:
+
+```bash
+python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. --pyi_out=. grpchook/message.proto
+```
+
+Note that all clients which connect to a server have to use the same proto schema version i.e. the same proto file. The different signals for the clients must be used in substructures:
+
+```proto
+message Payload {
+    // For client A
+    SomeTypeA payloadClientA = 1;
+
+	// For client B
+    SomeTypeB payloadClientB = 2;
+
+    ...
+}
+
+```
+
+---
+<a name="todos-roadmap"></a>
+<a id="todos-roadmap"></a>
+
+## ToDos & Roadmap
+
+### Performance & Stability
+- Evaluate replacing the threading model with `asyncio` if the performance gain justifies the API tradeoff.
+- Verify behavior when connections are interrupted mid-stream; ensure no ghost threads or queue deadlocks occur.
+
+### Planned Features
+- Multi-language client example (e.g., C++ or Rust).
+- SSL/TLS usage example.
+
+
+---
+<a name="known-issues-troubleshooting"></a>
+<a id="known-issues-troubleshooting"></a>
+
+## Known Issues & Troubleshooting
+
+TBD
+
+---
+<a name="contributing"></a>
+<a id="contributing"></a>
+
+## Contributing
+
+Contributions are welcome. Please open an issue first for major changes so the approach can be discussed. For bug fixes and small improvements, a pull request is sufficient.
+
+---
+<a name="license"></a>
+<a id="license"></a>
+
+## License
+
+BSD 3-Clause — see [LICENSE.txt](LICENSE.txt).
+
+---
+<a name="release-history"></a>
+<a id="release-history"></a>
+
+## Release History
+
+
+| Version / Git Tag on Master | Description |
+|----------------------------|-------------|
+| 0.0.1                      | Initial public release. |

grpchook-0.0.2/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()

grpchook-0.0.2/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()

grpchook-0.0.2/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()

grpchook-0.0.2/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