switchboard-router 0.1.0__py3-none-any.whl

switchboard_router/__init__.py

@@ -0,0 +1,12 @@
+"""Switchboard: pick the cheapest LLM that can handle each prompt."""
+from .backends import BackendError, OllamaBackend, OpenAIBackend, TransformersBackend
+from .decision import DOMAINS, TIERS, Decision, parse_decision
+from .router import DEFAULT_MODELS, MAX_PROMPT_CHARS, Router
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Router", "Decision", "parse_decision", "BackendError",
+    "OllamaBackend", "OpenAIBackend", "TransformersBackend",
+    "DEFAULT_MODELS", "TIERS", "DOMAINS", "MAX_PROMPT_CHARS", "__version__",
+]

switchboard_router/backends.py

@@ -0,0 +1,222 @@
+"""Ways to run the Switchboard model: Ollama, any OpenAI-compatible server, or Transformers in-process."""
+from __future__ import annotations
+
+import http.client
+import importlib.util
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Protocol
+
+OLLAMA_HOST = "http://localhost:11434"
+OLLAMA_MODEL = "hf.co/switchboardllm/switchboard-router-0.5b-GGUF"
+HF_REPO = "switchboardllm/switchboard-router-0.5b"
+MAX_NEW_TOKENS = 24
+MAX_PROMPT_TOKENS = 512  # the router was trained on prompts cut to 512 tokens
+DEFAULT_TIMEOUT = 15.0   # routing sits in front of every request, so don't hang for long
+PULL_TIMEOUT = 1800.0    # pulling the 994 MB GGUF on first use can take a while
+_TRANSPORT_ERRORS = (OSError, http.client.HTTPException, UnicodeDecodeError, ValueError)
+
+
+class BackendError(RuntimeError):
+    """The backend could not produce an answer (network, server or model error)."""
+
+
+class Backend(Protocol):
+    def generate(self, prompt: str) -> str: ...
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Don't follow redirects: urllib would forward the Authorization header to the new host."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect)
+
+
+def _open(req: urllib.request.Request, timeout: float):
+    return _OPENER.open(req, timeout=timeout)
+
+
+def _check_http_url(url: str, what: str) -> str:
+    parts = urllib.parse.urlsplit(url)
+    if parts.scheme not in ("http", "https") or not parts.netloc:
+        raise ValueError(f"{what} must be an http(s) URL, got {url!r}")
+    return url.rstrip("/")
+
+
+def _safe_url(url: str) -> str:
+    """The URL without credentials or query, for error messages."""
+    parts = urllib.parse.urlsplit(url)
+    host = parts.hostname or ""
+    if parts.port:
+        host = f"{host}:{parts.port}"
+    return urllib.parse.urlunsplit((parts.scheme, host, parts.path, "", ""))
+
+
+def _redact(text: str, secret: str | None) -> str:
+    return text.replace(secret, "***") if secret else text
+
+
+def _post_json(url: str, body: dict, headers: dict | None = None, timeout: float = DEFAULT_TIMEOUT,
+               secret: str | None = None) -> dict:
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(body).encode("utf-8"),
+        headers={"Content-Type": "application/json", **(headers or {})},
+        method="POST",
+    )
+    where = _safe_url(url)
+    try:
+        with _open(req, timeout) as resp:
+            raw = resp.read()
+    except urllib.error.HTTPError as exc:
+        try:
+            detail = exc.read().decode("utf-8", "replace")[:200]
+        except _TRANSPORT_ERRORS:
+            detail = ""
+        raise BackendError(_redact(f"HTTP {exc.code} from {where}: {detail}", secret)) from exc
+    except _TRANSPORT_ERRORS as exc:
+        reason = getattr(exc, "reason", exc)
+        raise BackendError(_redact(f"could not reach {where}: {reason}", secret)) from exc
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError) as exc:
+        raise BackendError(f"{where} did not return JSON") from exc
+
+
+class OllamaBackend:
+    """Calls a local Ollama server. Pulls the GGUF from Hugging Face the first time it's missing."""
+
+    def __init__(self, model: str = OLLAMA_MODEL, host: str = OLLAMA_HOST, timeout: float = DEFAULT_TIMEOUT,
+                 auto_pull: bool = True):
+        self.model = model
+        self.host = _check_http_url(host, "host")
+        self.timeout = timeout
+        self.auto_pull = auto_pull
+
+    def _chat(self, prompt: str) -> dict:
+        body = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": prompt}],
+            "stream": False,
+            "options": {"temperature": 0, "num_predict": MAX_NEW_TOKENS},
+        }
+        return _post_json(f"{self.host}/api/chat", body, timeout=self.timeout)
+
+    def pull(self) -> None:
+        _post_json(f"{self.host}/api/pull", {"model": self.model, "stream": False}, timeout=PULL_TIMEOUT)
+
+    def generate(self, prompt: str) -> str:
+        try:
+            data = self._chat(prompt)
+        except BackendError as exc:
+            if "HTTP 404" not in str(exc):
+                raise
+            if not self.auto_pull:
+                raise BackendError(f"model not pulled yet; run: ollama pull {self.model}") from exc
+            self.pull()
+            data = self._chat(prompt)
+        try:
+            return data["message"]["content"]
+        except (KeyError, TypeError) as exc:
+            raise BackendError(f"unexpected Ollama response: {str(data)[:200]}") from exc
+
+
+class OpenAIBackend:
+    """Calls any OpenAI-compatible chat endpoint: llama-server, vLLM, or the Surplus API."""
+
+    def __init__(self, base_url: str, model: str, api_key: str | None = None, timeout: float = DEFAULT_TIMEOUT):
+        self.base_url = _check_http_url(base_url, "base_url")
+        self.model = model
+        self.api_key = api_key
+        self.timeout = timeout
+
+    def generate(self, prompt: str) -> str:
+        body = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": 0,
+            "max_tokens": MAX_NEW_TOKENS,
+        }
+        headers = {"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}
+        data = _post_json(f"{self.base_url}/chat/completions", body, headers, self.timeout, secret=self.api_key)
+        try:
+            return data["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError) as exc:
+            raise BackendError(_redact(f"unexpected response: {str(data)[:200]}", self.api_key)) from exc
+
+
+class TransformersBackend:
+    """Runs the model in this process. Needs `pip install switchboard-router[local]`."""
+
+    def __init__(self, repo: str = HF_REPO, device: str | None = None, revision: str | None = None):
+        if not transformers_available():
+            raise RuntimeError("the transformers backend needs: pip install 'switchboard-router[local]'")
+        import torch
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+
+        self._torch = torch
+        self.device = device or ("cuda" if torch.cuda.is_available() else "cpu")
+        self.tokenizer = AutoTokenizer.from_pretrained(repo, revision=revision)
+        self.model = AutoModelForCausalLM.from_pretrained(repo, revision=revision).to(self.device).eval()
+
+    def generate(self, prompt: str) -> str:
+        tok = self.tokenizer
+        ids = tok(prompt, add_special_tokens=False)["input_ids"]
+        if len(ids) > MAX_PROMPT_TOKENS:
+            prompt = tok.decode(ids[:MAX_PROMPT_TOKENS])
+        # render to text first: apply_chat_template's return type changed across transformers versions
+        text = tok.apply_chat_template([{"role": "user", "content": prompt}], add_generation_prompt=True, tokenize=False)
+        enc = tok(text, return_tensors="pt", add_special_tokens=False).to(self.device)
+        with self._torch.inference_mode():
+            out = self.model.generate(**enc, max_new_tokens=MAX_NEW_TOKENS, do_sample=False,
+                                      pad_token_id=tok.eos_token_id)
+        return tok.decode(out[0, enc["input_ids"].shape[1]:], skip_special_tokens=True)
+
+
+def ollama_is_running(host: str = OLLAMA_HOST, timeout: float = 1.0) -> bool:
+    try:
+        with _open(urllib.request.Request(f"{host.rstrip('/')}/api/version"), timeout):
+            return True
+    except _TRANSPORT_ERRORS:
+        return False
+
+
+def transformers_available() -> bool:
+    return all(importlib.util.find_spec(m) is not None for m in ("transformers", "torch"))
+
+
+def build_backend(
+    name: str = "auto",
+    *,
+    base_url: str | None = None,
+    backend_model: str | None = None,
+    api_key: str | None = None,
+    host: str = OLLAMA_HOST,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> Backend:
+    if name == "auto":
+        if base_url:
+            name = "openai"
+        elif ollama_is_running(host):
+            name = "ollama"
+        elif transformers_available():
+            name = "transformers"
+        else:
+            raise RuntimeError(
+                "No backend found. Start Ollama (https://ollama.com), or install the local backend with "
+                "pip install 'switchboard-router[local]', or pass backend='openai' with a base_url."
+            )
+    if name == "ollama":
+        return OllamaBackend(model=backend_model or OLLAMA_MODEL, host=host, timeout=timeout)
+    if name == "openai":
+        if not base_url:
+            raise ValueError("backend='openai' needs base_url, e.g. http://localhost:8080/v1")
+        return OpenAIBackend(base_url=base_url, model=backend_model or "switchboard", api_key=api_key, timeout=timeout)
+    if name == "transformers":
+        return TransformersBackend(repo=backend_model or HF_REPO)
+    raise ValueError(f"unknown backend {name!r}: use auto, ollama, openai or transformers")

switchboard_router/cli.py

@@ -0,0 +1,58 @@
+"""`switchboard "your prompt"` prints the tier, domain and model as JSON. Use `-` to read the prompt from stdin."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from .router import Router
+
+
+def build_router(**kwargs) -> Router:
+    return Router(**kwargs)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="switchboard", description="Pick the cheapest model tier for a prompt.")
+    ap.add_argument("prompt", help="the prompt to route, or - to read it from stdin")
+    ap.add_argument("--backend", default="auto", choices=["auto", "ollama", "openai", "transformers"])
+    ap.add_argument("--base-url", default=None, help="OpenAI-compatible base URL, e.g. http://localhost:8080/v1")
+    ap.add_argument("--backend-model", default=None, help="model name on the backend")
+    ap.add_argument("--api-key-env", default=None, help="name of the env var holding the API key")
+    ap.add_argument("--timeout", type=float, default=None, help="seconds to wait for the backend")
+    args = ap.parse_args(argv)
+
+    prompt = sys.stdin.read() if args.prompt == "-" else args.prompt
+    if not prompt.strip():
+        print("switchboard: prompt is empty", file=sys.stderr)
+        return 2
+    options: dict = {"backend": args.backend}
+    if args.base_url:
+        options["base_url"] = args.base_url
+    if args.backend_model:
+        options["backend_model"] = args.backend_model
+    if args.timeout:
+        options["timeout"] = args.timeout
+    if args.api_key_env:
+        key = os.environ.get(args.api_key_env)
+        if not key:
+            print(f"switchboard: environment variable {args.api_key_env} is not set", file=sys.stderr)
+            return 1
+        options["api_key"] = key
+    try:
+        router = build_router(**options)
+        decision = router.route(prompt)
+    except Exception as exc:  # report setup problems as a message, not a traceback
+        print(f"switchboard: {exc}", file=sys.stderr)
+        return 1
+    result = {**decision.to_dict(), "model": router.models[decision.tier]}
+    if decision.error:
+        result["error"] = decision.error
+        print(f"switchboard: routing failed, using frontier: {decision.error}", file=sys.stderr)
+    print(json.dumps(result))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

switchboard_router/decision.py

@@ -0,0 +1,37 @@
+"""The router's answer, parsed from one line of JSON, failing safe to the frontier tier."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+TIERS = ("small", "mid", "frontier")
+DOMAINS = ("code", "math", "writing", "general")
+SAFE_TIER = "frontier"
+
+
+@dataclass(frozen=True)
+class Decision:
+    tier: str
+    domain: str = "general"
+    raw: str = ""
+    valid: bool = True
+    error: str = ""
+
+    def to_dict(self) -> dict:
+        return {"tier": self.tier, "domain": self.domain, "valid": self.valid}
+
+
+def parse_decision(text: str) -> Decision:
+    """Read the model's output. Anything unreadable becomes frontier, so a bad call costs money, not quality."""
+    try:
+        data = json.loads(text.strip())
+    except (ValueError, RecursionError, AttributeError, TypeError):
+        return Decision(tier=SAFE_TIER, raw=text, valid=False)
+    if not isinstance(data, dict) or data.get("tier") not in TIERS:
+        return Decision(tier=SAFE_TIER, raw=text, valid=False)
+    domain = data.get("domain") if data.get("domain") in DOMAINS else "general"
+    return Decision(tier=data["tier"], domain=domain, raw=text, valid=True)
+
+
+def failed(error: str) -> Decision:
+    return Decision(tier=SAFE_TIER, valid=False, error=error)

switchboard_router/router.py

@@ -0,0 +1,79 @@
+"""Route a prompt to the cheapest tier that can handle it, then map the tier to a model id."""
+from __future__ import annotations
+
+import warnings
+from types import MappingProxyType
+from typing import Mapping, Union
+
+from . import backends
+from .backends import Backend, BackendError
+from .decision import TIERS, Decision, failed, parse_decision
+
+MAX_PROMPT_CHARS = 2000
+
+# Default tier models on Surplus (list output price per 1M tokens: $0.50, $10, $20).
+DEFAULT_MODELS: Mapping[str, str] = MappingProxyType({
+    "small": "anthropic/claude-haiku-5.5",
+    "mid": "anthropic/claude-sonnet-5.5",
+    "frontier": "anthropic/claude-opus-5.5",
+})
+
+
+def _check_models(models: Mapping[str, str] | None) -> Mapping[str, str]:
+    models = dict(models or {})
+    unknown = set(models) - set(TIERS)
+    if unknown:
+        raise ValueError(f"unknown tier(s) in models: {sorted(unknown)}; use {list(TIERS)}")
+    if any(not isinstance(v, str) or not v.strip() for v in models.values()):
+        raise ValueError("model ids must be non-empty strings")
+    missing = [t for t in TIERS if t not in models]
+    if models and missing:
+        warnings.warn(f"models has no entry for {missing}; those tiers use the defaults", UserWarning, stacklevel=3)
+    return MappingProxyType({**DEFAULT_MODELS, **models})
+
+
+class Router:
+    """
+    >>> router = Router()                      # uses Ollama if it's running
+    >>> router.route("Write a haiku about rain").tier
+    'small'
+    >>> router.pick_model("Unscramble the following words: eglar, ngareo, kobo")
+    'anthropic/claude-opus-5.5'
+
+    Unreadable output and backend failures route to frontier (valid=False) unless fail_safe=False,
+    in which case they raise. Empty or non-string prompts always raise.
+    """
+
+    def __init__(
+        self,
+        backend: Union[str, Backend] = "auto",
+        models: Mapping[str, str] | None = None,
+        fail_safe: bool = True,
+        **backend_options,
+    ):
+        self.models = _check_models(models)
+        self.fail_safe = fail_safe
+        if isinstance(backend, str):
+            backend = backends.build_backend(backend, **backend_options)
+        if not callable(getattr(backend, "generate", None)):
+            raise TypeError("backend must be a name or an object with a generate(prompt) method")
+        self.backend: Backend = backend
+
+    def route(self, prompt: str) -> Decision:
+        if not isinstance(prompt, str):
+            raise TypeError(f"prompt must be a string, got {type(prompt).__name__}")
+        if not prompt.strip():
+            raise ValueError("prompt is empty")
+        try:
+            text = self.backend.generate(prompt[:MAX_PROMPT_CHARS])
+        except Exception as exc:  # any failure must still produce a safe decision
+            if not self.fail_safe:
+                raise
+            return failed(f"{type(exc).__name__}: {exc}")
+        decision = parse_decision(text)
+        if not decision.valid and not self.fail_safe:
+            raise BackendError(f"unreadable router output: {str(text)[:100]!r}")
+        return decision
+
+    def pick_model(self, prompt: str) -> str:
+        return self.models[self.route(prompt).tier]

switchboard_router-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: switchboard-router
+Version: 0.1.0
+Summary: Pick the cheapest LLM that can handle each prompt, with the open Switchboard router.
+Project-URL: Homepage, https://huggingface.co/spaces/switchboardllm/switchboard
+Project-URL: Model, https://huggingface.co/switchboardllm/switchboard-router-0.5b
+Author: Switchboard
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cost,llm,llm-routing,ollama,openai,router
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: local
+Requires-Dist: torch>=2.1; extra == 'local'
+Requires-Dist: transformers>=4.45; extra == 'local'
+Description-Content-Type: text/markdown
+
+# switchboard-router
+
+Pick the cheapest LLM that can handle each prompt.
+
+`switchboard-router` asks [Switchboard](https://huggingface.co/switchboardllm/switchboard-router-0.5b), a 0.5B open router model, which tier a prompt needs: `small`, `mid` or `frontier`. Easy prompts go to a cheap model, and you pay frontier prices only when the prompt needs it.
+
+```
+pip install switchboard-router
+```
+
+## Quickstart
+
+You need one way to run the model. The easiest is [Ollama](https://ollama.com): install it and leave it running. If the model isn't in Ollama yet, the first call pulls it (994 MB) from Hugging Face, which takes a minute or two. To do that ahead of time:
+
+```
+ollama pull hf.co/switchboardllm/switchboard-router-0.5b-GGUF
+```
+
+```python
+from switchboard_router import Router
+
+router = Router()  # uses Ollama when it's running
+
+router.route("Write a haiku about rain").tier
+# 'small'
+
+
+router.pick_model("Unscramble the following words: eglar, ngareo, kobo")
+# 'anthropic/claude-opus-5.5'
+```
+
+From the terminal:
+
+```
+switchboard "Design a rate limiter for 10M requests per second across 5 regions"
+{"tier": "mid", "domain": "general", "valid": true, "model": "anthropic/claude-sonnet-5.5"}
+```
+
+## Route, then call the model
+
+`pick_model` returns a model id for the tier. By default these are Claude models on [Surplus](https://surplusllm.com), which serves every model behind one OpenAI-compatible key:
+
+```python
+from openai import OpenAI
+from switchboard_router import Router
+
+router = Router()
+llm = OpenAI(base_url="https://api.surplusllm.com/api/v1", api_key="sk-surplus-...")
+
+prompt = "Write a Python function that reverses a string"
+reply = llm.chat.completions.create(
+    model=router.pick_model(prompt),
+    messages=[{"role": "user", "content": prompt}],
+)
+```
+
+Use your own models per tier (give all three, or the rest fall back to the defaults with a warning):
+
+```python
+router = Router(models={"small": "my/small-model", "mid": "my/mid-model", "frontier": "my/frontier-model"})
+```
+
+## Backends
+
+| Backend | Use it when | How |
+|---|---|---|
+| `ollama` | You run models locally | `Router(backend="ollama")` |
+| `openai` | You serve the model with llama-server or vLLM, or call it on the Surplus API | `Router(backend="openai", base_url="http://localhost:8080/v1", backend_model="switchboard")` |
+| `transformers` | You want it in-process | `pip install 'switchboard-router[local]'`, then `Router(backend="transformers")` |
+
+`Router()` with no backend uses Ollama if it's running, then Transformers if it's installed, and otherwise tells you what to install.
+
+## Failing safe
+
+If the backend can't be reached, errors out, or the model's output isn't valid JSON, the decision is `frontier` with `valid=False` and the reason in `decision.error`. A failed routing call costs you money, never quality. With `fail_safe=False`, those cases raise instead. Empty or non-string prompts always raise `ValueError` or `TypeError`.
+
+Requests time out after 15 seconds by default (`Router(timeout=5)` to change it), and redirects are not followed, so an API key is never sent to another host.
+
+## Limits
+
+- The router reads the first 2,000 characters of a prompt. A question at the very end of a long prompt may be missed.
+- It reads the prompt it's given, so a prompt can try to talk it into a cheaper tier. Don't use it as a security boundary.
+
+## How good is the routing?
+
+Switchboard v0.1 on 10,000 held-out prompts: 64.5% cheaper than sending every prompt to Claude Opus 5.5, and 5.5% of prompts were sent to a cheaper tier than they needed. Method, limits and the full results are in the [model card](https://huggingface.co/switchboardllm/switchboard-router-0.5b). Try it in your browser: [Switchboard demo](https://huggingface.co/spaces/switchboardllm/switchboard).
+
+## License
+
+Apache-2.0.

switchboard_router-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+switchboard_router/__init__.py,sha256=d1LWJ9ERBYdNz38cZGqdz9KMqTgg7kcqwTBGJZyg5I4,516
+switchboard_router/backends.py,sha256=6lI3CgkZQwvpYrnNudsmdA40dTuxB1jiJqTENgGsSos,8964
+switchboard_router/cli.py,sha256=sfd7x2yMImjleF0hP2RcSy4gLTWtjMm2BwVxgZtf5d8,2341
+switchboard_router/decision.py,sha256=9lfhEt6kZCXSoa53w6GJX8i-Xq7YBAJyB2YaX2lxlrA,1302
+switchboard_router/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+switchboard_router/router.py,sha256=q6__NNI7hB_7juElaLyuff0yGOJvsQep7psP5FHetlA,3168
+switchboard_router-0.1.0.dist-info/METADATA,sha256=ACmp0NIMQrw4xJcAtT1NNCjvO5hXGEMvJP-yN_K9wTk,4883
+switchboard_router-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+switchboard_router-0.1.0.dist-info/entry_points.txt,sha256=RoQCRaAkT-1shO7vs-348Vtt6l9UhiaHeN6O_IK-brE,60
+switchboard_router-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+switchboard_router-0.1.0.dist-info/RECORD,,

switchboard_router-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

switchboard_router-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+switchboard = switchboard_router.cli:main

switchboard_router-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.