added some debug scripts

Author: chrishayuk

debug/src_size.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python
+"""
+src_size.py  <path-or-vcs-url>
+================================
+Measure how much space a Python package (plus its **runtime** dependencies)
+occupies when built **from source**, without counting the extra build tools we
+install inside a temporary virtual-env (``pip``, ``setuptools``, ``wheel``,
+etc.).
+
+What you get
+------------
+1. **Raw source** - size of the directory / checkout you point at.
+2. **Built artefacts** - combined size of the sdist + wheel produced by
+   ``python -m build``.
+3. **Runtime tree** - bytes taken by the package **and its runtime deps** once
+   installed, *excluding* build-time tooling.
+4. *(optional)* a **breakdown** of every runtime distribution, sorted
+   large → small.
+
+CLI flags
+---------
+```
+--no-deps        Skip installing dependencies (handy for library-only size)
+--breakdown, -b  Show per-package size table
+--include-tools  Include build tools (pip/setuptools/wheel) in totals + table
+```
+
+> **Note**The script still seeds pip inside the venv so it works on
+> pip-less interpreters - those files are just ignored by default in the
+> final numbers.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ensurepip
+import json
+import os
+import pathlib
+import subprocess
+import sys
+import tempfile
+from typing import List, Tuple
+
+BYTES_IN_MB = 1_048_576
+BUILD_TOOLS = {"pip", "setuptools", "wheel"}
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def du(path: pathlib.Path) -> int:
+    """Recursive size of *path* in bytes."""
+    return sum(p.stat().st_size for p in path.rglob("*") if p.is_file())
+
+
+def run(cmd: List[str]) -> None:
+    subprocess.check_call(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.STDOUT)
+
+
+def build_artefacts(src: pathlib.Path, out: pathlib.Path) -> List[pathlib.Path]:
+    run([sys.executable, "-m", "pip", "install", "-q", "build"])
+    run([sys.executable, "-m", "build", "--sdist", "--wheel", "--outdir", out, src])
+    return list(out.glob("*.*"))
+
+
+def pick_one(artefacts: List[pathlib.Path]) -> pathlib.Path:
+    return next((a for a in artefacts if a.suffix == ".whl"), artefacts[0])
+
+
+def create_venv(venv: pathlib.Path) -> pathlib.Path:
+    run([sys.executable, "-m", "venv", venv])
+    py = venv / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+    run([str(py), "-m", "ensurepip", "--upgrade"])
+    run([str(py), "-m", "pip", "install", "-q", "--upgrade", "pip", "setuptools", "wheel"])
+    return py
+
+
+def dist_sizes(py: pathlib.Path) -> List[Tuple[str, int]]:
+    """Return list of (dist_name, size_bytes) for every distribution in venv."""
+    code = r'''
+import importlib.metadata as m, pathlib, json, os
+sizes = {}
+for dist in m.distributions():
+    total = 0
+    for entry in dist.files or []:
+        p = pathlib.Path(dist.locate_file(entry))
+        if p.is_file():
+            try:
+                total += p.stat().st_size
+            except FileNotFoundError:
+                pass
+    sizes[dist.metadata['Name']] = total
+print(json.dumps(sizes))
+'''
+    out = subprocess.check_output([str(py), "-c", code], text=True)
+    data = json.loads(out)
+    return sorted(((k, v) for k, v in data.items()), key=lambda kv: kv[1], reverse=True)
+
+
+def canonical(name: str) -> str:
+    return name.lower().replace("_", "-")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main(src: str, include_deps: bool, show_breakdown: bool, include_tools: bool) -> None:
+    ensurepip.bootstrap()  # ensure pip for outer interpreter
+
+    with tempfile.TemporaryDirectory() as tmp_s:
+        tmp = pathlib.Path(tmp_s)
+
+        # 1. Obtain source ---------------------------------------------------
+        if pathlib.Path(src).is_dir():
+            src_dir = pathlib.Path(src).resolve()
+        else:
+            src_dir = tmp / "clone"
+            run(["git", "clone", "--depth", "1", src, src_dir])
+
+        print(f"Raw source:     {du(src_dir)/BYTES_IN_MB:.2f} MB")
+
+        # 2. Build artefacts -------------------------------------------------
+        artefacts = build_artefacts(src_dir, tmp)
+        print(f"Sdist+wheel:    {sum(p.stat().st_size for p in artefacts)/BYTES_IN_MB:.2f} MB")
+        artefact = pick_one(artefacts)
+
+        # 3. Install into temp venv -----------------------------------------
+        py = create_venv(tmp / "venv")
+        install_cmd = [str(py), "-m", "pip", "install", "-q", str(artefact)]
+        if not include_deps:
+            install_cmd.insert(5, "--no-deps")
+        run(install_cmd)
+
+        dists = dist_sizes(py)
+        # Filter build tools unless user asked to keep them
+        runtime_dists = [(n, sz) for n, sz in dists if include_tools or canonical(n) not in {canonical(t) for t in BUILD_TOOLS}]
+
+        total_runtime = sum(sz for _, sz in runtime_dists)
+        print(f"Runtime tree:   {total_runtime/BYTES_IN_MB:.2f} MB" + (" (includes build tools)" if include_tools else ""))
+
+        if show_breakdown:
+            print("\nBreakdown (descending):")
+            for name, sz in runtime_dists:
+                print(f"  {name:<25} {sz/BYTES_IN_MB:7.2f} MB")
+
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Measure on-disk size of a Python package built from source.")
+    p.add_argument("source", help="Path, git/https URL, or anything pip understands.")
+    p.add_argument("--no-deps", action="store_true", help="Skip installing dependencies inside the tmp venv.")
+    p.add_argument("--breakdown", "-b", action="store_true", help="Show per-package size contribution (runtime only).")
+    p.add_argument("--include-tools", action="store_true", help="Include build tools (pip/setuptools/wheel) in totals and table.")
+    args = p.parse_args()
+    main(args.source, include_deps=not args.no_deps, show_breakdown=args.breakdown, include_tools=args.include_tools)

examples/mcp_timeout_bug_demo.py

@@ -3,14 +3,14 @@
 examples/mcp_timeout_bug_demo.py (cleaned)
 
 Minimal demo that verifies the MCP timeout / retry behaviour 
-without the heavy‑weight tracing that was needed during the bug hunt.
+without the heavy-weight tracing that was needed during the bug hunt.
 
 Run it with
 
     $ python examples/mcp_timeout_bug_demo.py
 
 You should see each step finishing in ~timeout seconds rather than the full
-20‑second hang simulated by the mock transport.
+20-second hang simulated by the mock transport.
 """
 
 from __future__ import annotations
@@ -23,7 +23,7 @@
 from typing import Dict, List, Any
 
 # ---------------------------------------------------------------------------
-# Local imports – add project root so `python examples/...` works everywhere.
+# Local imports - add project root so `python examples/...` works everywhere.
 # ---------------------------------------------------------------------------
 PROJECT_ROOT = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(PROJECT_ROOT))
@@ -36,12 +36,12 @@
 # ---------------------------------------------------------------------------
 
 class _MockTransport:
-    """Transport that *never* responds within the caller‑supplied timeout."""
+    """Transport that *never* responds within the caller-supplied timeout."""
 
-    async def initialize(self) -> bool:  # noqa: D401 – simple bool
+    async def initialize(self) -> bool:  # noqa: D401 - simple bool
         return True
 
-    async def close(self) -> None:  # noqa: D401 – just a noop
+    async def close(self) -> None:  # noqa: D401 - just a noop
         return None
 
     async def send_ping(self) -> bool:  # keep StreamManager happy
@@ -71,7 +71,7 @@ async def _patched_stream_manager():
 
     from chuk_tool_processor.mcp.stream_manager import StreamManager
 
-    async def _factory(  # type: ignore[override] – signature comes from classmethod
+    async def _factory(  # type: ignore[override] - signature comes from classmethod
         cls, servers, server_names=None
     ):
         mgr = StreamManager()
@@ -115,7 +115,7 @@ async def _run_demo() -> None:
         # -------------------------------------------------------------------
         # 1️⃣ Processor.process (XML) with explicit timeout
         # -------------------------------------------------------------------
-        print("\n1️⃣  processor.process() – expect ~3s timeout")
+        print("\n1️⃣  processor.process() - expect ~3s timeout")
         start = time.perf_counter()
         result = await processor.process(
             '<tool name="mcp.hanging_tool" args="{\"message\": \"hello\"}"/>',
@@ -127,7 +127,7 @@ async def _run_demo() -> None:
         # -------------------------------------------------------------------
         # 2️⃣ Processor.execute (ToolCall) with explicit timeout
         # -------------------------------------------------------------------
-        print("\n2️⃣  processor.execute() – expect ~1s timeout")
+        print("\n2️⃣  processor.execute() - expect ~1s timeout")
         tc = ToolCall(tool="hanging_tool", namespace="mcp", arguments={})
         start = time.perf_counter()
         result = await processor.execute([tc], timeout=1.0)
@@ -137,7 +137,7 @@ async def _run_demo() -> None:
         # -------------------------------------------------------------------
         # 3️⃣ StreamManager.call_tool with timeout parameter
         # -------------------------------------------------------------------
-        print("\n3️⃣  stream_manager.call_tool() – expect ~2s timeout")
+        print("\n3️⃣  stream_manager.call_tool() - expect ~2s timeout")
         start = time.perf_counter()
         sm_result = await stream_manager.call_tool(
             "hanging_tool", {"message": "hi"}, timeout=2.0
@@ -153,7 +153,7 @@ async def _run_demo() -> None:
 # ---------------------------------------------------------------------------
 
 def _report(err: str | None, elapsed: float, *, expect: float) -> None:
-    """Pretty‑print outcome and highlight if expectation wasn’t met."""
+    """Pretty-print outcome and highlight if expectation wasn’t met."""
 
     status = "✅ OK" if err and abs(elapsed - expect) < 0.5 else "⚠️  ISSUE"
     print(f"   · elapsed {_pretty(elapsed)} → {status}; error=\"{err}\"")

src/chuk_tool_processor/execution/wrappers/retry.py

@@ -2,7 +2,7 @@
 """
 Async-native retry wrapper for tool execution.
 
-Adds exponential–back-off retry logic and *deadline-aware* timeout handling so a
+Adds exponential-back-off retry logic and *deadline-aware* timeout handling so a
 `timeout=` passed by callers is treated as the **total wall-clock budget** for
 all attempts of a single tool call.
 """

tests/plugins/parsers/test_openai_tool.py

@@ -1,9 +1,9 @@
 # tests/tool_processor/plugins/parsers/test_openai_tool.py
 """OpenAI *tool_calls* parser plugin.
 
-Maps Chat‑Completions native tool calls back into *ToolCall* objects using
+Maps Chat-Completions native tool calls back into *ToolCall* objects using
 ``registry.tool_export.tool_by_openai_name``.  The import is done lazily
-inside ``try_parse`` to avoid circular‑import issues revealed by tests.
+inside ``try_parse`` to avoid circular-import issues revealed by tests.
 """
 from __future__ import annotations
 
@@ -18,7 +18,7 @@
 
 
 class OpenAIToolPlugin(ParserPlugin):
-    """Convert Chat‑Completions *tool_calls* to internal *ToolCall*s."""
+    """Convert Chat-Completions *tool_calls* to internal *ToolCall*s."""
 
     # ------------------------------------------------------------------
     def try_parse(self, raw: str | Any) -> List[ToolCall]:  # type: ignore[override]