File size: 15,617 Bytes
377417d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
e93b289
 
 
377417d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
e93b289
377417d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3ed6b66
377417d
 
3ed6b66
 
 
377417d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
e93b289
 
 
377417d
 
 
 
 
01b3ee5
 
 
 
 
 
 
 
 
e93b289
 
 
377417d
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
01b3ee5
 
 
377417d
 
3ed6b66
 
 
01b3ee5
3ed6b66
377417d
 
 
 
01b3ee5
3ed6b66
 
 
377417d
 
3ed6b66
377417d
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
"""The governed ToolUniverse client β€” the ONLY module that imports ``tooluniverse``.

ADR-0001 Β§7, enforced in code rather than by convention:

- **Allow-list by construction.** ToolUniverse is built with ``keep_default_tools=False`` and
  ``load_workspace=False``, then ``load_tools(include_tools=<the endpoints' set>)``, and startup
  is REFUSED unless the loaded set equals that set exactly. With these arguments 1.5.6 loads the
  named tools and nothing else: no special tools, no tool finder, no agentic tools, no remote MCP
  servers (measured 2026-10-20, with outbound sockets blocked, so loading opens no connection).
- **No workspace.** ``load_workspace=False`` is not optional. With a workspace directory present
  (``TOOLUNIVERSE_HOME``, or ``./.tooluniverse``), 1.5.6's constructor writes a default
  ``profile.yaml`` into it and applies it, which loads ALL 2,691 tools before ``load_tools`` runs;
  it also reads that workspace's ``.env`` and ``~/.tooluniverse/.env`` into the environment, which
  could bring a model key in after the check below. Found by this repo's own tests on 2026-10-20,
  when an earlier draft pointed ``TOOLUNIVERSE_HOME`` at an empty temp dir.
- **No model provider keys.** ToolUniverse's agentic tools and tool finder can reach OpenAI, Azure
  OpenAI, Gemini, OpenRouter or a vLLM server when keys are set. None of those tools can load
  here, and startup still refuses if any key is present: the Space makes no model call
  (ADR-0001 Β§2). ``HF_TOKEN`` is allowed β€” the machine gate needs it β€” and in 1.5.6 only
  Hugging Face inference and embedding tools read it, none of which is on the allow-list.
- **Exactly one cache.** ToolUniverse's own result cache is disabled through its environment
  switches and every call passes ``use_cache=False``; :mod:`src.cache` is the only cache, because
  it is the one that keeps ``retrieved_at`` honest.
- **Pinned.** The installed version must equal ``config/tools_allowlist.yaml``'s
  ``tooluniverse_version``. A bump is its own lane (doctor, re-recorded fixtures, schema tests,
  security scan) and never changes an endpoint's name or payload shape.

:class:`ToolClient` is what the endpoints call. It also runs the few named direct calls of
:mod:`src.direct_calls` (the ADR-0001 exception for facts no ToolUniverse tool returns) through
the same cache, rate limit, deadline and schema check. It returns a :class:`SourceResult` or raises a
:class:`SourceError` whose ``reason`` is one of the three payload source-error reasons, so a
timeout, a limit or a drifted response is always structured, never a guess.
"""

from __future__ import annotations

import ast
import concurrent.futures
import inspect
import os
import re
import threading
import time
from collections.abc import Callable, Mapping
from dataclasses import dataclass
from typing import Any

from src import config, direct_calls, schemas
from src.cache import ResponseCache
from src.ratelimit import RateLimiters

# Every variable through which ToolUniverse 1.5.6 (or a library it can load) reaches a model.
LLM_KEY_VARS = (
    "OPENAI_API_KEY",
    "OPENAI_BASE_URL",
    "AZURE_OPENAI_API_KEY",
    "AZURE_OPENAI_ENDPOINT",
    "GEMINI_API_KEY",
    "GOOGLE_API_KEY",
    "OPENROUTER_API_KEY",
    "ANTHROPIC_API_KEY",
    "VLLM_SERVER_URL",
)

# Tool types that must never load, whatever the allow-list says: LLM-backed agents, the tool
# finders (they can call a model or download an embedding index), remote MCP auto-loaders and
# web-search backends. A tool whose config names `required_api_keys` is key-gated and refused too.
FORBIDDEN_TOOL_TYPES = frozenset(
    {
        "AgenticTool",
        "SmolAgentTool",
        "MCPAutoLoaderTool",
        "MCPClientTool",
        "ToolFinderEmbedding",
        "ToolFinderLLM",
        "ToolFinderKeyword",
        "ToolFinderJev",
        "WebSearchTool",
        "WebAPIDocumentationSearchTool",
    }
)

# ToolUniverse's own switches: its result cache off. The workspace and profile variables are
# REMOVED rather than set, because any workspace widens what loads (see the module docstring).
_TU_ENV = {
    "TOOLUNIVERSE_CACHE_ENABLED": "false",
    "TOOLUNIVERSE_CACHE_PERSIST": "false",
    "TOOLUNIVERSE_QUIET": "1",
}
_TU_ENV_REMOVED = ("TOOLUNIVERSE_PROFILE", "TOOLUNIVERSE_HOME")

_HOST = re.compile(r"https?://([A-Za-z0-9.-]+)")
_build_lock = threading.Lock()


class StartupRefused(RuntimeError):
    """The Space must not start: a key is set, the version drifted, or the tool set is wrong."""


class SourceError(Exception):
    """A structured failure from one source call (``reason`` ∈ payload SOURCE_ERROR_REASONS)."""

    def __init__(self, source: str, reason: str, detail: str):
        super().__init__(f"{source}: {reason}: {detail}")
        self.source = source
        self.reason = reason
        self.detail = detail

    def as_payload(self) -> dict[str, str]:
        return {"source": self.source, "reason": self.reason, "detail": self.detail}


@dataclass(frozen=True)
class SourceResult:
    tool: str
    source: str
    args: dict[str, Any]
    data: Any
    retrieved_at: float  # epoch seconds when the SOURCE answered
    cache: str  # "hit" | "miss"
    tooluniverse_version: str


def assert_no_llm_keys(environ: Mapping[str, str] | None = None) -> None:
    env = os.environ if environ is None else environ
    present = [var for var in LLM_KEY_VARS if (env.get(var) or "").strip()]
    if present:
        raise StartupRefused(
            f"Model-provider settings are present ({', '.join(present)}). This Space makes no "
            "model call and must run without them (ADR-0001 Β§2); remove them from the Space's "
            "secrets and variables."
        )


def configure_tooluniverse_env() -> None:
    """Set ToolUniverse's environment before an instance is built (idempotent)."""
    for var, value in _TU_ENV.items():
        os.environ[var] = value
    for var in _TU_ENV_REMOVED:
        os.environ.pop(var, None)


def installed_tooluniverse_version() -> str:
    import tooluniverse

    return str(getattr(tooluniverse, "__version__", ""))


def build_tooluniverse(include: frozenset[str] | None = None):
    """A ToolUniverse holding exactly ``include`` (default: the endpoints' set), or refuse."""
    include = config.endpoint_tool_names() if include is None else include
    if not include <= config.allowed_tool_names():
        raise StartupRefused(
            f"not on the allow-list: {sorted(include - config.allowed_tool_names())}"
        )
    assert_no_llm_keys()
    configure_tooluniverse_env()
    version = installed_tooluniverse_version()
    if version != config.pinned_tooluniverse_version():
        raise StartupRefused(
            f"ToolUniverse {version!r} is installed; config pins "
            f"{config.pinned_tooluniverse_version()!r}. A version bump is its own reviewed lane."
        )
    from tooluniverse import ToolUniverse

    tu = ToolUniverse(keep_default_tools=False, load_workspace=False)
    if tu.all_tool_dict:
        raise StartupRefused(
            f"ToolUniverse loaded {len(tu.all_tool_dict)} tools before the allow-list was applied"
        )
    tu.load_tools(include_tools=sorted(include), quiet=True)
    assert_no_llm_keys()  # again: nothing during construction may have brought one in
    loaded = frozenset(tu.all_tool_dict)
    if loaded != include:
        raise StartupRefused(
            f"loaded tool set differs from the allow-listed set: extra {sorted(loaded - include)}, "
            f"missing {sorted(include - loaded)}"
        )
    unsafe = sorted(
        name
        for name, cfg in tu.all_tool_dict.items()
        if cfg.get("type") in FORBIDDEN_TOOL_TYPES or cfg.get("required_api_keys")
    )
    if unsafe:
        raise StartupRefused(f"agentic, finder, remote-MCP, web-search or key-gated: {unsafe}")
    cache_manager = getattr(tu, "cache_manager", None)
    if cache_manager is not None and getattr(cache_manager, "enabled", False):
        raise StartupRefused("ToolUniverse's own result cache is enabled; it must be off")
    return tu


def tool_hosts(tu, tool: str) -> set[str]:
    """Every host a loaded tool can reach: URLs in its config plus its class's code.

    Read offline from the installed package: the tool's config dict, the source of its class and
    ToolUniverse base classes, and any module-level URL constant those classes name (HGNC keeps
    its base URL in one). So the egress statement in config/sources.yaml can be checked without a
    network call (tests/test_sources_hosts.py).
    """
    from tooluniverse.tool_registry import get_tool_class_lazy

    cfg = tu.all_tool_dict[tool]
    hosts = set(_HOST.findall(repr(cfg)))
    # The lazy lookup imports the class's module (offline); the plain registry is empty until a
    # tool instance has been created, which would make this check silently find nothing.
    cls = get_tool_class_lazy(cfg["type"])
    if cls is None:
        raise StartupRefused(f"{tool}: tool type {cfg['type']!r} has no class to inspect")
    for klass in inspect.getmro(cls):
        if not klass.__module__.startswith("tooluniverse"):
            continue
        try:
            class_source = inspect.getsource(klass)
            module_source = inspect.getsource(inspect.getmodule(klass))
        except (OSError, TypeError):
            continue
        hosts.update(_HOST.findall(class_source))
        for name, value in _module_url_constants(module_source).items():
            if re.search(rf"\b{re.escape(name)}\b", class_source):
                hosts.update(_HOST.findall(value))
    return hosts


def _module_url_constants(module_source: str) -> dict[str, str]:
    """Top-level ``NAME = "https://…"`` assignments in a module."""
    found: dict[str, str] = {}
    for node in ast.parse(module_source).body:
        if isinstance(node, ast.Assign) and isinstance(node.value, ast.Constant):
            value = node.value.value
            if isinstance(value, str) and _HOST.search(value):
                for target in node.targets:
                    if isinstance(target, ast.Name):
                        found[target.id] = value
    return found


def _unwrap(tool: str, source: str, raw: Any) -> Any:
    """ToolUniverse's envelope β†’ the source's data, or a structured error."""
    if raw is None:
        raise SourceError(source, "source_unavailable", f"{tool} returned nothing")
    if isinstance(raw, dict):
        status = raw.get("status")
        if status == "success" and "data" in raw:
            return raw["data"]
        if status == "error" or ("error" in raw and raw.get("error")):
            detail = str(raw.get("error") or raw.get("message") or "error")[:200]
            raise SourceError(source, "source_unavailable", f"{tool}: {detail}")
    if isinstance(raw, str) and raw.lower().startswith("error"):
        raise SourceError(source, "source_unavailable", f"{tool}: {raw[:200]}")
    return raw


class ToolClient:
    """Cache β†’ rate limit β†’ call with a deadline β†’ schema check β†’ cache.

    ``runner(tool, args)`` performs the actual call. By default it is ToolUniverse's
    ``run_one_function`` on a lazily built, allow-listed instance; tests inject a fake runner
    with synthetic or recorded responses, so the suite never reaches the network.
    """

    def __init__(
        self,
        *,
        runner: Callable[[str, dict[str, Any]], Any] | None = None,
        cache: ResponseCache | None = None,
        limiters: RateLimiters | None = None,
        clock: Callable[[], float] = time.time,
        tooluniverse_version: str | None = None,
        tooluniverse: Any = None,
    ):
        self._runner = runner
        # gradio_ui passes an instance built at import, so a Space that must not start (a model
        # key, a version drift, a widened tool set) fails at startup, not on its first call.
        self._tu = tooluniverse
        self.cache = cache if cache is not None else ResponseCache()
        self.limiters = limiters if limiters is not None else RateLimiters()
        self._clock = clock
        self._version = tooluniverse_version
        self._pool = concurrent.futures.ThreadPoolExecutor(
            max_workers=8, thread_name_prefix="tu-call"
        )

    @property
    def tooluniverse_version(self) -> str:
        if self._version is None:
            self._version = installed_tooluniverse_version()
        return self._version

    def _default_runner(self, tool: str, args: dict[str, Any]) -> Any:
        if direct_calls.is_direct(tool):
            timeout = config.source(config.source_of(tool))["timeout_seconds"]
            return direct_calls.run(tool, args, timeout)
        with _build_lock:
            if self._tu is None:
                self._tu = build_tooluniverse()
        return self._tu.run_one_function({"name": tool, "arguments": args}, use_cache=False)

    def call(
        self,
        tool: str,
        args: dict[str, Any],
        *,
        max_wait: float = 10.0,
        deadline: float | None = None,
    ) -> SourceResult:
        """``deadline`` can shorten the source's ``timeout_seconds`` for this call, never extend it."""
        if tool not in config.endpoint_tool_names() and not direct_calls.is_direct(tool):
            # A programming error, not a user input: endpoints only ever name loaded tools (or a
            # named direct call, src/direct_calls.py).
            raise ValueError(f"{tool!r} is not an endpoint tool")
        source = config.source_of(tool)
        cfg = config.source(source)

        hit = self.cache.get(source, tool, args)
        if hit is not None:
            data, retrieved_at = hit
            return SourceResult(
                tool, source, dict(args), data, retrieved_at, "hit", self.tooluniverse_version
            )

        if not self.limiters.acquire(source, max_wait):
            raise SourceError(
                source, "rate_limited", f"{cfg['name']} limit of {cfg['rate_per_second']}/s reached"
            )

        timeout = cfg["timeout_seconds"]
        if deadline is not None:
            timeout = max(0.0, min(timeout, deadline))
        runner = self._runner or self._default_runner
        future = self._pool.submit(runner, tool, dict(args))
        # `wait`, not `result(timeout=…)`: since Python 3.11 concurrent.futures.TimeoutError IS the
        # builtin TimeoutError, so a source's own read timeout raised inside the call would be
        # indistinguishable from our deadline passing (caught by a test on 2026-10-20).
        done, _ = concurrent.futures.wait([future], timeout=timeout)
        if not done:
            future.cancel()
            raise SourceError(
                source,
                "source_unavailable",
                f"{cfg['name']} did not answer within {round(timeout, 1):g} s",
            )
        try:
            raw = future.result()
        except SourceError:
            raise
        except Exception as e:  # any failure inside a source call is structured, never raised
            raise SourceError(source, "source_unavailable", f"{tool}: {type(e).__name__}") from e
        retrieved_at = self._clock()

        data = _unwrap(tool, source, raw)
        try:
            schemas.validate(tool, data)
        except schemas.SchemaDrift as drift:
            raise SourceError(source, "upstream_schema_drift", drift.detail) from drift

        self.cache.put(source, tool, args, data, retrieved_at)
        return SourceResult(
            tool, source, dict(args), data, retrieved_at, "miss", self.tooluniverse_version
        )