pal-code 0.1.0__py3-none-any.whl

pal/llm_wrapper/components/features.py

@@ -0,0 +1,104 @@
+"""Function calling and structured output, in two flavours.
+
+Native: the backend supports it (`WrapperCapabilities.supports_tools` / `supports_json`) and the core uses the provider's own
+mechanism. Emulated: for backends that do not (an in-process Hugging Face model, for one), the adapter puts the contract in
+the prompt and validates what comes back. Both produce the same result shape, so callers never know which was used.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+
+def normalize_tools(tools: list[dict] | None) -> list[dict]:
+    """Accept OpenAI-style {"type": "function", "function": {...}} or flat {"name", "description", "parameters"}."""
+    out = []
+    for t in tools or []:
+        fn = t.get("function", t) if isinstance(t, dict) else {}
+        name = fn.get("name")
+        if not name:
+            raise ValueError("every tool needs a name")
+        out.append({"name": name, "description": fn.get("description", ""),
+                    "parameters": fn.get("parameters") or fn.get("input_schema") or {"type": "object", "properties": {}}})
+    return out
+
+
+def is_response_format(rf: dict | None) -> bool:
+    """True for a provider-style response format ({"type": "json_object"} and friends); False for a JSON schema, which
+    also has a `type` key ({"type": "object", ...})."""
+    return isinstance(rf, dict) and rf.get("type") in ("json_object", "json_schema", "text")
+
+
+def parse_arguments(raw: Any) -> dict:
+    if isinstance(raw, dict):
+        return raw
+    if isinstance(raw, str) and raw.strip():
+        try:
+            val = json.loads(raw)
+            return val if isinstance(val, dict) else {"value": val}
+        except ValueError:
+            return {"_raw": raw}
+    return {}
+
+
+def extract_json(text: str) -> Any:
+    """Parse JSON from a model reply, tolerating ``` fences and a sentence before or after it."""
+    t = (text or "").strip()
+    fence = re.match(r"^```(?:json)?\s*(.*?)\s*```$", t, re.S | re.I)
+    if fence:
+        t = fence.group(1)
+    try:
+        return json.loads(t)
+    except ValueError:
+        pass
+    for open_c, close_c in (("{", "}"), ("[", "]")):
+        a, b = t.find(open_c), t.rfind(close_c)
+        if 0 <= a < b:
+            try:
+                return json.loads(t[a:b + 1])
+            except ValueError:
+                continue
+    raise ValueError("no valid JSON found in the reply")
+
+
+def json_instruction(schema: dict | None) -> str:
+    base = "Reply with only a single valid JSON value. No explanation, no markdown fences."
+    if schema and not is_response_format(schema):
+        return base + " It must match this JSON schema: " + json.dumps(schema, separators=(",", ":"))
+    return base
+
+
+def tools_instruction(tools: list[dict]) -> str:
+    listing = "; ".join(f'{t["name"]}: {t["description"]} parameters={json.dumps(t["parameters"], separators=(",", ":"))}'
+                        for t in tools)
+    return ('You can call tools. To call one or more, reply with only JSON of the form '
+            '{"tool_calls": [{"name": "<tool name>", "parameters": {...}}]} and nothing else. '
+            'If no tool is needed, answer normally in plain text. Tools: ' + listing)
+
+
+def parse_emulated_tool_calls(text: str, tools: list[dict]) -> list[dict] | None:
+    """The tool calls a model asked for in the emulated format, or None when it answered in plain text."""
+    try:
+        data = extract_json(text)
+    except ValueError:
+        return None
+    calls = data.get("tool_calls") if isinstance(data, dict) else None
+    if not isinstance(calls, list) or not calls:
+        return None
+    out = []
+    for c in calls:
+        if isinstance(c, dict) and isinstance(c.get("name"), str):
+            out.append({"name": c["name"], "parameters": parse_arguments(c.get("parameters", c.get("arguments")))})
+    return out or None
+
+
+class ToolCallError(ValueError):
+    """The model asked for a tool that was not offered."""
+
+
+def check_tool_names(calls: list[dict], tools: list[dict]) -> None:
+    known = {t["name"] for t in tools}
+    for c in calls:
+        if c["name"] not in known:
+            raise ToolCallError(f"the model called an unknown tool: {c['name']!r}")

pal/llm_wrapper/components/litellm_wrapper.py

@@ -0,0 +1,215 @@
+"""The LiteLLM wrapper, the one wrapper for every model call: the cloud APIs (OpenAI, Anthropic, Google Gemini, Groq, DeepSeek, Mistral, Together,
+OpenRouter, Perplexity, Azure OpenAI, Amazon Bedrock) AND the local runtimes (Ollama, vLLM, LM Studio, llama.cpp servers) all go
+through LiteLLM's Python SDK (`litellm.completion`). The only core that does not is the in-process Hugging Face one, because
+LiteLLM calls model servers and cannot load a model into this process.
+
+How it is kept safe, because this library handles users' API keys:
+  * only the SDK is used, never the LiteLLM proxy server (most of its 2026 CVEs, and the March 2026 backdoor's second payload,
+    are in the proxy);
+  * the version is pinned and hash-locked (requirements/litellm.lock, pyproject extra `litellm`);
+  * the key is passed to each call explicitly, never put in a global;
+  * LiteLLM's telemetry and callbacks are off, and its price table is the copy bundled with the pinned version (no download at
+    import time).
+A local runtime has no key to protect, so for it the point of LiteLLM is one interface, one token and error format, and one
+path to test. Stopping a stream early (the scheduler's pause) closes the connection underneath LiteLLM's wrapper, which has no
+close() of its own: otherwise the model server would keep generating and block the job that paused it.
+"""
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Iterator
+from typing import Any
+
+from pal.errors import DependencyMissingError
+from pal.tokens import estimate_tokens
+
+from .base import DeploymentType, LLMResponse, LLMSyscall, LLMWrapper, WrapperCapabilities, WrapperConfig
+from .features import is_response_format, normalize_tools, parse_arguments
+
+PINNED = "1.102.1"
+
+# our provider name -> LiteLLM's provider prefix
+PREFIX = {"openai": "openai", "azure_openai": "azure", "anthropic": "anthropic", "gemini": "gemini", "groq": "groq",
+          "together": "together_ai", "mistral": "mistral", "deepseek": "deepseek", "openrouter": "openrouter",
+          "perplexity": "perplexity", "bedrock": "bedrock"}
+
+# local runtime -> LiteLLM's provider prefix. "ollama_chat" is LiteLLM's /api/chat route (the one that handles chat turns and tools).
+LOCAL_PREFIX = {"ollama": "ollama_chat", "vllm": "hosted_vllm", "lmstudio": "lm_studio", "llamacpp": "openai"}
+# The OpenAI-style local servers need SOME key in the request. Without an explicit one LiteLLM would fall back to a real key in the
+# environment (OPENAI_API_KEY) and send it to a local process, so a placeholder is always sent unless you configured a real one.
+_PLACEHOLDER_KEY = "not-needed"
+_NEEDS_PLACEHOLDER = ("vllm", "lmstudio", "llamacpp")
+
+_PASSTHROUGH = ("top_p", "stop", "seed", "frequency_penalty", "presence_penalty")
+_STREAM_HANDLES = ("streaming_response", "response_iterator", "http_response")
+_module: Any = None
+
+
+def _import_litellm() -> Any:
+    """Import LiteLLM once, with its network and logging side effects switched off first."""
+    global _module
+    if _module is not None:
+        return _module
+    os.environ.setdefault("LITELLM_LOCAL_MODEL_COST_MAP", "True")      # use the bundled price table: no download at import
+    os.environ.setdefault("LITELLM_TELEMETRY", "False")
+    try:
+        import litellm
+    except ImportError as e:
+        raise DependencyMissingError(
+            f"litellm is not installed. Run: pip install 'pal-code[litellm]'  (pinned to litellm=={PINNED}; a hash-locked "
+            "install is in requirements/litellm.lock)") from e
+    litellm.suppress_debug_info = True
+    litellm.set_verbose = False
+    for attr in ("telemetry",):
+        if hasattr(litellm, attr):
+            setattr(litellm, attr, False)
+    litellm.success_callback = []
+    litellm.failure_callback = []
+    _module = litellm
+    return litellm
+
+
+def full_model(backend: str, model: str) -> str:
+    prefix = PREFIX.get(backend) or LOCAL_PREFIX.get(backend)
+    if prefix is None or model.startswith(prefix + "/"):
+        return model
+    return f"{prefix}/{model}"
+
+
+def close_stream(stream: Any) -> None:
+    """Stop a LiteLLM stream so the model server stops generating. LiteLLM's wrapper has no sync close(); the HTTP stream is held
+    by generators underneath it, and closing those closes the connection. Tolerant: anything missing or failing is skipped."""
+    inner = getattr(stream, "completion_stream", None)
+    for obj in (stream, inner):
+        close = getattr(obj, "close", None)
+        if callable(close):
+            try:
+                close()
+            except Exception:  # noqa: BLE001  (already closed, or not closable)
+                pass
+    for name in _STREAM_HANDLES:
+        handle = getattr(inner, name, None)
+        close = getattr(handle, "close", None)
+        if callable(close):
+            try:
+                close()
+            except Exception:  # noqa: BLE001
+                pass
+
+
+class LiteLLMWrapper(LLMWrapper):
+    """Your own key, any provider LiteLLM knows. Two specialised kinds build on it: `OpenRouterWrapper` (one key, hundreds of models) and
+    `LocalLLM` (models served on this machine); they set what differs and share everything else, so the key handling lives in one place."""
+    name = "litellm"
+    IS_LOCAL = False
+
+    def __init__(self, config: WrapperConfig):
+        super().__init__(config)
+        self.ll = _import_litellm()
+        self.model = full_model(config.backend, config.model)
+        self.api_key = config.api_key
+        self.local = self.IS_LOCAL or config.backend in LOCAL_PREFIX
+        self.timeout = float(config.extra.get("timeout", 300 if self.local else 120))   # a local model's first call loads it
+
+    # -- one request ---------------------------------------------------------------------------------------------
+    def _kwargs(self, syscall: LLMSyscall) -> dict:
+        kw: dict = {"model": syscall.model if syscall.model and "/" in syscall.model else self.model,
+                    "messages": syscall.messages, "timeout": self.timeout, "num_retries": 0, "drop_params": True}
+        key = self._key()
+        if key:
+            kw["api_key"] = key
+        base = self.config.base_url or self.config.host
+        if base:
+            kw["api_base"] = base
+        if syscall.temperature is not None:
+            kw["temperature"] = syscall.temperature
+        if syscall.max_tokens is not None:
+            kw["max_tokens"] = syscall.max_tokens
+        tools = normalize_tools(getattr(syscall, "tools", None))
+        if tools:
+            kw["tools"] = [{"type": "function", "function": t} for t in tools]
+        rf = getattr(syscall, "response_format", None)
+        if rf:
+            kw["response_format"] = rf if is_response_format(rf) else {
+                "type": "json_schema", "json_schema": {"name": "response", "schema": rf}}
+        kw.update({k: v for k, v in syscall.params.items() if k in _PASSTHROUGH})
+        kw.update(self.config.extra.get("litellm_params", {}))
+        return kw
+
+    def chat(self, syscall: LLMSyscall) -> LLMResponse:
+        t0 = time.time()
+        r = self.ll.completion(**self._kwargs(syscall))
+        latency = time.time() - t0
+        msg = r.choices[0].message
+        calls = [{"name": c.function.name, "parameters": parse_arguments(c.function.arguments)}
+                 for c in (getattr(msg, "tool_calls", None) or [])]
+        usage = getattr(r, "usage", None)
+        try:
+            cost = float(self.ll.completion_cost(completion_response=r))
+        except Exception:  # noqa: BLE001  (a model with no known price)
+            cost = None
+        return LLMResponse(
+            text=getattr(msg, "content", None) or "", raw=r,
+            prompt_tokens=int(getattr(usage, "prompt_tokens", 0) or 0),
+            completion_tokens=int(getattr(usage, "completion_tokens", 0) or 0),
+            meta={"latency": latency, "tool_calls": calls or None, "cost_usd": cost, "model": self.model})
+
+    def stream_chat(self, syscall: LLMSyscall) -> Iterator[str]:
+        stream = self.ll.completion(**self._kwargs(syscall), stream=True)
+        try:
+            for chunk in stream:
+                delta = chunk.choices[0].delta if chunk.choices else None
+                piece = getattr(delta, "content", None) if delta is not None else None
+                if piece:
+                    yield piece
+        finally:
+            close_stream(stream)            # runs when the consumer stops early too (the scheduler pausing a job)
+
+    # -- facts about the model -------------------------------------------------------------------------------------
+    def token_count(self, text: str) -> int:
+        try:
+            return int(self.ll.token_counter(model=self.model, text=text))
+        except Exception:  # noqa: BLE001  (an unknown model has no tokenizer: estimate)
+            return estimate_tokens(text)
+
+    def _key(self) -> str | None:
+        if self.api_key:
+            return self.api_key
+        return _PLACEHOLDER_KEY if self.config.backend in _NEEDS_PLACEHOLDER else None
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        kw: dict = {"model": self.model, "input": texts, "timeout": self.timeout}
+        key = self._key()
+        if key:
+            kw["api_key"] = key
+        base = self.config.base_url or self.config.host
+        if base:
+            kw["api_base"] = base
+        return [list(d["embedding"]) for d in self.ll.embedding(**kw).data]
+
+    def price_per_token(self) -> tuple[float, float] | None:
+        """(input, output) USD per token from LiteLLM's bundled price table, or None for an unknown model. A local model is free."""
+        if self.local:
+            return None
+        try:
+            info = self.ll.get_model_info(model=self.model)       # provider-aware: "openrouter/gpt-4o" is not OpenAI's gpt-4o
+        except Exception:  # noqa: BLE001  (not in the price table)
+            return None
+        if not info or info.get("input_cost_per_token") is None:
+            return None
+        return float(info["input_cost_per_token"]), float(info.get("output_cost_per_token") or 0.0)
+
+    def capabilities(self) -> WrapperCapabilities:
+        tools = json_mode = False
+        try:
+            tools = bool(self.ll.supports_function_calling(model=self.model))
+        except Exception:  # noqa: BLE001
+            pass
+        try:
+            json_mode = "response_format" in (self.ll.get_supported_openai_params(model=self.model) or [])
+        except Exception:  # noqa: BLE001
+            pass
+        return WrapperCapabilities(
+            deployment_type=DeploymentType.LOCAL_SERVER if self.local else DeploymentType.CLOUD_API, supports_embeddings=self.local,
+            supports_streaming=True, supports_tools=tools, supports_json=json_mode, billed_per_token=not self.local)

pal/llm_wrapper/components/openrouter_wrapper.py

@@ -0,0 +1,114 @@
+"""The OpenRouter wrapper: one OpenRouter key reaches hundreds of models from many labs, some of them free. It is for EXPLORING models: trying a
+new one costs nothing but a model name. (If you have your own key for one provider, use the LiteLLM wrapper directly: no middleman.)
+
+It is the LiteLLM wrapper underneath, so the key is handled exactly the same way (per call, never in a global), plus:
+  * the app's name is sent as OpenRouter's optional attribution header;
+  * `models()` reads OpenRouter's public model list (no key needed) so you can browse: name, context size, price, and whether it is free.
+
+What to know before using it: your prompts pass through OpenRouter on their way to the model's lab; free models are rate-limited (about 20 a
+minute); the list changes, and a model can disappear. The list is read live and kept for an hour; if it cannot be read you get an error, never
+a stale guess.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from pal.llm_wrapper.components.litellm_wrapper import LiteLLMWrapper
+
+CATALOGUE_URL = "https://openrouter.ai/api/v1/models"
+CATALOGUE_TTL = 3600.0
+APP_TITLE = "Pal"
+
+
+@dataclass(frozen=True)
+class ModelInfo:
+    id: str                          # what you pass as the model name, e.g. "meta-llama/llama-3.3-70b-instruct:free"
+    name: str
+    context_length: int | None
+    prompt_per_million: float | None       # USD per million input tokens; None when not stated
+    completion_per_million: float | None
+    free: bool
+
+    def label(self) -> str:
+        ctx = f"{self.context_length // 1000}k" if self.context_length else "?"
+        price = "free" if self.free else (f"${self.prompt_per_million:g}/M in" if self.prompt_per_million is not None else "price ?")
+        return f"{self.name} | {ctx} | {price}"
+
+
+def _per_million(value: Any) -> float | None:
+    try:
+        return round(float(value) * 1_000_000, 6)
+    except (TypeError, ValueError):
+        return None
+
+
+def parse_catalogue(payload: Any) -> list[ModelInfo]:
+    """OpenRouter's model list -> ModelInfo. Tolerant: an entry without an id is skipped, a missing or odd field becomes None."""
+    out: list[ModelInfo] = []
+    data = payload.get("data") if isinstance(payload, dict) else None
+    for m in data if isinstance(data, list) else []:
+        if not isinstance(m, dict) or not m.get("id"):
+            continue
+        pricing = m.get("pricing") or {}
+        prompt, completion = _per_million(pricing.get("prompt")), _per_million(pricing.get("completion"))
+        ctx = m.get("context_length")
+        out.append(ModelInfo(id=str(m["id"]), name=str(m.get("name") or m["id"]), context_length=int(ctx) if isinstance(ctx, (int, float)) else None,
+                             prompt_per_million=prompt, completion_per_million=completion,
+                             free=str(m["id"]).endswith(":free") or (prompt == 0.0 and completion == 0.0)))
+    return sorted(out, key=lambda x: x.id)
+
+
+def _fetch_json(url: str, timeout: float = 10.0) -> Any:
+    import requests
+    r = requests.get(url, timeout=timeout, headers={"Accept": "application/json"})
+    r.raise_for_status()
+    return r.json()
+
+
+_cache: dict = {"at": 0.0, "models": []}
+_cache_lock = threading.Lock()
+
+
+def fetch_models(fetch: Callable[[str], Any] | None = None, force: bool = False) -> list[ModelInfo]:
+    """OpenRouter's current models, from its public list (no key). Kept for an hour. Raises if it cannot be read."""
+    with _cache_lock:
+        if not force and _cache["models"] and time.time() - _cache["at"] < CATALOGUE_TTL:
+            return list(_cache["models"])
+    models = parse_catalogue((fetch or _fetch_json)(CATALOGUE_URL))
+    if not models:
+        raise RuntimeError("OpenRouter's model list came back empty or in a format this version does not understand")
+    with _cache_lock:
+        _cache.update(at=time.time(), models=models)
+    return list(models)
+
+
+def search_models(models: list[ModelInfo], text: str = "", free_only: bool = False, limit: int = 50) -> list[ModelInfo]:
+    """Models whose id or name contains every word of `text` (any case), free ones only if asked, at most `limit`."""
+    words = [w for w in text.lower().split() if w]
+    hits = [m for m in models if (not free_only or m.free) and all(w in f"{m.id} {m.name}".lower() for w in words)]
+    return hits[:limit] if limit else hits
+
+
+class OpenRouterWrapper(LiteLLMWrapper):
+    name = "openrouter"
+
+    def __init__(self, config):
+        super().__init__(config)
+        self.app_title = str(config.extra.get("app_title", APP_TITLE))
+        self.app_url = str(config.extra.get("app_url", ""))
+
+    def _kwargs(self, syscall) -> dict:
+        kw = super()._kwargs(syscall)
+        headers = {"X-Title": self.app_title}
+        if self.app_url:
+            headers["HTTP-Referer"] = self.app_url
+        kw["extra_headers"] = {**headers, **kw.get("extra_headers", {})}
+        return kw
+
+    @staticmethod
+    def models(fetch: Callable[[str], Any] | None = None, force: bool = False) -> list[ModelInfo]:
+        return fetch_models(fetch, force)

pal/llm_wrapper/modes.py

@@ -0,0 +1,73 @@
+"""Two ways to reach a cloud model, and which providers belong to each.
+
+  explore    One OpenRouter key reaches hundreds of models, some free: the way to try new models. Your prompts pass through OpenRouter.
+  own_key    Your own key for one provider (Anthropic, OpenAI, Gemini ...): direct, no middleman, that provider's own terms.
+
+Both are served by the same LiteLLM-based wrapper (the OpenRouter wrapper adds the model browser); a mode is only a choice of which providers to
+offer. Local models are a third thing (the Local LLM component) and are not a mode.
+"""
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+# provider -> the environment variable that holds its key (the order is the order they are offered in)
+PROVIDER_KEYS = {
+    "anthropic": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "gemini": "GEMINI_API_KEY",
+    "groq": "GROQ_API_KEY",
+    "deepseek": "DEEPSEEK_API_KEY",
+    "mistral": "MISTRAL_API_KEY",
+    "together": "TOGETHER_API_KEY",
+    "openrouter": "OPENROUTER_API_KEY",
+}
+EXPLORE_PROVIDER = "openrouter"
+
+
+@dataclass(frozen=True)
+class Mode:
+    key: str
+    title: str
+    summary: str
+    providers: tuple[str, ...]
+
+
+MODES: dict[str, Mode] = {
+    "explore": Mode("explore", "Explore models",
+                    "One OpenRouter key reaches hundreds of models, some of them free. Your prompts pass through OpenRouter on the way to the model.",
+                    (EXPLORE_PROVIDER,)),
+    "own_key": Mode("own_key", "Use my own key",
+                    "Your own key for one provider (Anthropic, OpenAI, Gemini ...). Direct to that provider, no middleman.",
+                    tuple(p for p in PROVIDER_KEYS if p != EXPLORE_PROVIDER)),
+}
+
+
+def mode_for(provider: str) -> str:
+    """Which mode a provider belongs to."""
+    if provider not in PROVIDER_KEYS:
+        raise KeyError(f"unknown provider {provider!r} (known: {', '.join(PROVIDER_KEYS)})")
+    return "explore" if provider == EXPLORE_PROVIDER else "own_key"
+
+
+def providers_with_keys(env: Mapping[str, str] | None = None) -> dict[str, bool]:
+    """Every provider and whether its key is set in the environment."""
+    env = os.environ if env is None else env
+    return {p: bool(env.get(var)) for p, var in PROVIDER_KEYS.items()}
+
+
+def default_mode(env: Mapping[str, str] | None = None) -> str:
+    """own_key if any provider key is set, else explore if only an OpenRouter key is, else own_key (the plain default)."""
+    have = providers_with_keys(env)
+    if any(v for p, v in have.items() if p != EXPLORE_PROVIDER):
+        return "own_key"
+    return "explore" if have[EXPLORE_PROVIDER] else "own_key"
+
+
+def describe_modes(env: Mapping[str, str] | None = None) -> list[dict]:
+    """The modes as plain data for the web page and the command line, with which providers already have a key."""
+    have = providers_with_keys(env)
+    return [{"key": m.key, "title": m.title, "summary": m.summary,
+             "providers": [{"name": p, "key_env": PROVIDER_KEYS[p], "key_set": have[p]} for p in m.providers],
+             "ready": any(have[p] for p in m.providers)} for m in MODES.values()]

pal/llm_wrapper/pipeline.py

@@ -0,0 +1,61 @@
+"""
+LLMWrapperPipeline is the single entry point callers use to talk to an LLM,
+regardless of deployment option. It owns exactly one active LLMWrapper at a
+time (swappable via switch()) and exposes the unified system calls --
+callers never see LiteLLMWrapper vs the in-process Hugging Face core vs a local
+in-process model, only syscall_chat/syscall_token_count/syscall_embed.
+
+This replaces the old Router, which only dispatched to a fixed set of
+BackendAdapter subclasses with backend-specific interfaces; the syscall
+layer here is the "standardized system calls" piece AIOS 3.2 describes
+and the old Router didn't actually have.
+"""
+from __future__ import annotations
+
+from pal.llm_wrapper.components.base import LLMResponse, LLMSyscall, WrapperCapabilities, WrapperConfig
+from pal.llm_wrapper.utils.registry import available_backends, build_wrapper
+
+
+class LLMWrapperPipeline:
+    def __init__(self, config: WrapperConfig):
+        self.config = config
+        self.core = build_wrapper(config)
+
+    def switch(self, config: WrapperConfig) -> None:
+        """Swap the active core -- e.g. moving from a local Ollama core
+        to a cloud Gemini core mid-session. Every syscall below is core-
+        agnostic, so nothing else needs to change when this is called."""
+        self.config = config
+        self.core = build_wrapper(config)
+
+    # -- unified system calls -------------------------------------------------
+
+    def syscall_chat(self, messages: list[dict], **kwargs) -> LLMResponse:
+        syscall = LLMSyscall(
+            messages=messages,
+            model=kwargs.pop("model", None),
+            temperature=kwargs.pop("temperature", None),
+            max_tokens=kwargs.pop("max_tokens", None),
+            stream=kwargs.pop("stream", False),
+            params=kwargs,
+        )
+        return self.core.chat(syscall)
+
+    def syscall_token_count(self, text: str) -> int:
+        return self.core.token_count(text)
+
+    def syscall_embed(self, texts: list[str]) -> list[list[float]]:
+        return self.core.embed(texts)
+
+    def capabilities(self) -> WrapperCapabilities:
+        return self.core.capabilities()
+
+    def supports_kv_cache(self) -> bool:
+        return self.core.supports_kv_cache()
+
+    def reset_kv_cache(self) -> None:
+        self.core.reset_kv_cache()
+
+    @staticmethod
+    def list_backends() -> list[str]:
+        return available_backends()

pal/llm_wrapper/utils/__init__.py

@@ -0,0 +1,4 @@
+from pal.llm_wrapper.utils.registry import WRAPPER_REGISTRY, available_backends, build_wrapper
+from pal.llm_wrapper.utils.token_counting import heuristic_token_count
+
+__all__ = ["WRAPPER_REGISTRY", "available_backends", "build_wrapper", "heuristic_token_count"]

pal/llm_wrapper/utils/registry.py

@@ -0,0 +1,49 @@
+"""
+Backend-name -> wrapper-class registry, and the factory that builds a
+concrete LLMWrapper from a WrapperConfig. This is the single place that
+knows how a `backend` string maps to a deployment option -- adding a
+new cloud API or local runtime means adding one line here, not
+touching the pipeline or callers.
+"""
+from __future__ import annotations
+
+from pal.llm_wrapper.components.base import LLMWrapper, WrapperConfig
+from pal.llm_wrapper.components.litellm_wrapper import LOCAL_PREFIX, LiteLLMWrapper
+from pal.llm_wrapper.components.litellm_wrapper import PREFIX as LITELLM_PROVIDERS
+from pal.llm_wrapper.components.openrouter_wrapper import OpenRouterWrapper
+from pal.local_llm.components.huggingface_local import HuggingFaceLocalLLM
+from pal.local_llm.components.local_llm import LocalLLM
+
+# EVERY model call goes through ONE wrapper: LiteLLM's Python SDK (see litellm_wrapper.py for how it is kept safe). That covers the
+# cloud APIs and the local runtimes. The single exception is the in-process Hugging Face core: LiteLLM calls model servers, it
+# cannot load a model into this process.
+# EVERY model call goes through ONE wrapper, LiteLLM's Python SDK (see litellm_wrapper.py for how it is kept safe). Three kinds build on it:
+#   LiteLLMWrapper    your own key for a provider (OpenAI, Anthropic, Gemini, Groq, DeepSeek, Mistral, Together, Perplexity, Azure, Bedrock),
+#                     or any LiteLLM model string with the backend "litellm"
+#   OpenRouterWrapper one OpenRouter key, hundreds of models, a model browser: for exploring
+#   LocalLLM          models served on this machine (Ollama, vLLM, LM Studio, llama.cpp), in the Local LLM component
+# The single exception is the in-process Hugging Face model, also in the Local LLM component: LiteLLM calls model servers, it cannot load a
+# model into this process.
+WRAPPER_REGISTRY: dict[str, type[LLMWrapper]] = {
+    **{name: LiteLLMWrapper for name in LITELLM_PROVIDERS},
+    **{name: LocalLLM for name in LOCAL_PREFIX},
+    "openrouter": OpenRouterWrapper,
+    "litellm": LiteLLMWrapper,          # any LiteLLM model string, e.g. "cohere/command-r"
+    "huggingface_local": HuggingFaceLocalLLM,
+}
+# Names the paper's backend table uses, mapped to ours.
+BACKEND_ALIASES = {"google": "gemini", "huggingface": "huggingface_local", "hf": "huggingface_local",
+                   "aws_bedrock": "bedrock"}
+
+
+def build_wrapper(config: WrapperConfig) -> LLMWrapper:
+    config.backend = BACKEND_ALIASES.get(config.backend, config.backend)
+    cls = WRAPPER_REGISTRY.get(config.backend)
+    if cls is None:
+        known = ", ".join(sorted(WRAPPER_REGISTRY))
+        raise ValueError(f"unknown backend: {config.backend!r} (known backends: {known})")
+    return cls(config)
+
+
+def available_backends() -> list[str]:
+    return sorted(WRAPPER_REGISTRY)

pal/llm_wrapper/utils/token_counting.py

@@ -0,0 +1,10 @@
+"""Shared fallback token-count heuristic, used when a core's real
+tokenizer/endpoint is unavailable (offline, no matching tiktoken
+encoding, network error on a pure estimation call, etc.)."""
+
+
+def heuristic_token_count(text: str) -> int:
+    """~4 characters per token is the same rough approximation every
+    core already falls back to individually; centralised here so it's
+    defined once."""
+    return max(1, len(text) // 4)

pal/local_llm/__init__.py

@@ -0,0 +1,5 @@
+"""The Local LLM component: models served on this machine (Ollama, vLLM, LM Studio, llama.cpp) and the in-process Hugging Face model."""
+from pal.local_llm.components.huggingface_local import HuggingFaceLocalLLM
+from pal.local_llm.components.local_llm import DEFAULT_URLS, LOCAL_BACKENDS, LocalLLM
+
+__all__ = ["DEFAULT_URLS", "LOCAL_BACKENDS", "HuggingFaceLocalLLM", "LocalLLM"]