planwise 0.1.0__py3-none-any.whl

planwise/__init__.py

@@ -0,0 +1,8 @@
+"""PlanWise Router — intelligent tool routing for large tool catalogs."""
+
+from .config import RouterConfig
+from .engine.models import RouteResult, ToolCard
+from .engine.router import Router
+
+__all__ = ["Router", "RouterConfig", "RouteResult", "ToolCard"]
+__version__ = "0.1.0"

planwise/cli.py

@@ -0,0 +1,91 @@
+"""planwise CLI.
+
+  planwise route "pull revenue and email the chart" --catalog data/sample_catalog.json
+  planwise eval  --catalog ... --queries ... [--baseline]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import Router, RouterConfig
+
+
+def _load_router(catalog_path: str) -> Router:
+    router = Router(RouterConfig())
+    catalog = json.loads(Path(catalog_path).read_text())["tools"]
+    report = router.load_catalog(catalog)
+    if report.rejected:
+        for rej in report.rejected:
+            print(f"rejected {rej.tool_id}: [{rej.code}] {rej.message}", file=sys.stderr)
+    return router
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(prog="planwise")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    route_p = sub.add_parser("route", help="route one query")
+    route_p.add_argument("query")
+    route_p.add_argument("--catalog", default="data/sample_catalog.json")
+    route_p.add_argument("--format", dest="dialect", default="anthropic",
+                         choices=["anthropic", "openai", "mcp"])
+
+    eval_p = sub.add_parser("eval", help="run the eval harness")
+    eval_p.add_argument("--catalog", default="data/sample_catalog.json")
+    eval_p.add_argument("--queries", default="data/sample_queries.json")
+    eval_p.add_argument("--baseline", action="store_true")
+
+    serve_p = sub.add_parser("serve", help="run the Tier 1 HTTP gateway")
+    serve_p.add_argument("--host", default="0.0.0.0")
+    serve_p.add_argument("--port", type=int, default=8000)
+    serve_p.add_argument("--catalog", default="data/sample_catalog.json")
+
+    mcp_p = sub.add_parser("mcp", help="run the Tier 3 MCP server (stdio)")
+    mcp_p.add_argument("--catalog", default="data/sample_catalog.json")
+
+    args = ap.parse_args()
+
+    if args.cmd == "route":
+        router = _load_router(args.catalog)
+        result = router.route(args.query, dialect=args.dialect)
+        print(json.dumps({
+            "plan_hint": result.plan_hint,
+            "sequence": result.tool_sequence(),
+            "confidence": result.confidence,
+            "tools": [t.get("name") or t.get("function", {}).get("name") for t in result.tools],
+            "tokens_saved_pct": round(result.tokens_saved.saved_pct, 1),
+            "unresolved": [s.what for s in result.unresolved],
+            "degraded": result.degraded,
+        }, indent=2))
+    elif args.cmd == "eval":
+        from eval.harness import run_naive_baseline, run_planwise
+
+        router = _load_router(args.catalog)
+        queries = json.loads(Path(args.queries).read_text())["queries"]
+        print(run_planwise(router, queries).summary())
+        if args.baseline:
+            print()
+            print(run_naive_baseline(router, queries).summary())
+
+    elif args.cmd == "serve":
+        import os
+
+        import uvicorn
+
+        os.environ.setdefault("PLANWISE_CATALOG", args.catalog)
+        from .server import create_app
+
+        uvicorn.run(create_app(), host=args.host, port=args.port)
+
+    elif args.cmd == "mcp":
+        from .mcp_server import run_stdio
+
+        run_stdio(args.catalog)
+
+
+if __name__ == "__main__":
+    main()

planwise/config.py

@@ -0,0 +1,126 @@
+"""Router configuration.
+
+All tunable numbers live here so the eval harness can sweep them and so
+deployments can override any value with a ``PLANWISE_``-prefixed env var
+(e.g. ``PLANWISE_FLOOR=0.4``).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class ScoreWeights(BaseModel):
+    """Weights of the four scoring signals. Must sum to ~1.0."""
+
+    semantic: float = 0.40
+    bm25: float = 0.25
+    param_fit: float = 0.15
+    output_fit: float = 0.20
+
+
+class DupThresholds(BaseModel):
+    """Thresholds for deciding two tools are twins (see graphs.py)."""
+
+    param_jaccard: float = 0.6
+    output_sim: float = 0.8
+    card_cosine: float = 0.90
+
+
+class RouterConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="PLANWISE_", env_nested_delimiter="__")
+
+    weights: ScoreWeights = ScoreWeights()
+
+    # Gating: a candidate must clear the absolute floor AND stay within
+    # rel_margin of the top score. noise_band is the "almost tied" gap.
+    floor: float = 0.50
+    rel_margin: float = 0.85
+    noise_band: float = 0.05
+
+    k_max_per_step: int = 3
+    k_max_total: int = 8
+
+    # Coarse filter: keep this many clusters per step, plus any cluster
+    # whose score is within cluster_margin of the last kept one.
+    clusters_kept: int = 2
+    cluster_margin: float = 0.05
+    n_clusters: int = 10
+
+    mode: Literal["advisory", "strict"] = "advisory"
+    ambiguity_policy: Literal["ship_both", "argmax"] = "argmax"
+
+    planner: Literal["llm", "rules"] = "llm"
+    planner_model: str = "Bedrock-ant-haiku-4-5-20251001-v1-0"
+    planner_timeout_s: float = 30.0
+
+    # Plan-accuracy stack. A structurally invalid plan is retried once with
+    # the validator's errors in the prompt, then falls back to rules — so
+    # callers never see an invalid plan.
+    planner_retries: int = 1
+    # >1 = self-consistency: sample N plans (first at temp 0, rest at 0.7)
+    # and keep the majority structure. Costs N calls; use where wrong plans
+    # are expensive.
+    planner_samples: int = 1
+    # Second LLM call that critiques the plan against the query; if it flags
+    # gaps, the planner retries once with that feedback.
+    planner_verify: bool = False
+    # Re-plan once with binder feedback when a step matches no tool.
+    replan_on_unresolved: bool = True
+    # JSONL audit log of every plan + route outcome ("" = disabled).
+    plan_log_path: str = ""
+
+    # LLM gateway (Crest AWS Bedrock proxy, OpenAI-compatible). The key and
+    # cert path come from the environment — never hardcode/commit them.
+    # If llm_api_key is unset, the planner falls back to the rules planner
+    # and enrichment is skipped, so the system still runs fully offline.
+    llm_base_url: str = "https://apiproxy.cdsys.local/v1"
+    llm_api_key: str = ""            # PLANWISE_LLM_API_KEY
+    llm_cert: str = ""               # PLANWISE_LLM_CERT — path to apiproxy.cdsys.crt
+    enrich_model: str = "Bedrock-ant-haiku-4-5-20251001-v1-0"
+
+    widen_rounds_max: int = 2
+
+    # "sbert" = sentence-transformers (real semantics, needs the extra).
+    # "hashing" = deterministic lexical vectors — CI/tests, no downloads.
+    # "auto" = sbert if importable, else hashing (with a warning).
+    embed_backend: Literal["auto", "sbert", "hashing"] = "auto"
+    embed_model: str = "BAAI/bge-small-en-v1.5"
+
+    dup_thresholds: DupThresholds = DupThresholds()
+
+    # Penalty applied in param_fit when a required ID-like param has no
+    # candidate entity in the query at all.
+    missing_id_penalty: float = 0.3
+
+    # --- binder: dependency-echo handling ---
+    # Mask tokens echoed from a dependency's `produces` / this step's own
+    # `needs` out of the step text before semantic+BM25 scoring. Dataflow
+    # annotations are not action evidence. (False = legacy behavior.)
+    mask_dependency_echo: bool = True
+    # Subtracted from output_fit, scaled by similarity(candidate output,
+    # step.needs): a tool that OUTPUTS what this step CONSUMES is the
+    # producer of the step's input — upstream, not this step. 0 disables.
+    needs_output_penalty: float = 0.5
+
+    # --- assembler ---
+    # Collapse consecutive same-tool plan entries only when their steps
+    # share a verb; a different-verb collision surfaces as unresolved
+    # instead of being silently dropped.
+    merge_same_verb_only: bool = True
+
+    # --- planner validation ---
+    # Two steps with the same verb whose `what` word sets overlap at or
+    # above this Jaccard are flagged as duplicates that should be one
+    # repeated step. Values <= 0 or > 1.0 disable the check.
+    planner_dup_step_jaccard: float = 0.5
+
+    # Cosine floor for mapping an unknown/hallucinated tool name back to a
+    # real catalog tool (middleware recovery). Semantic embeddings warrant
+    # a high bar; lexical/hashing backends need it lower.
+    resolve_threshold: float = 0.75
+
+    index_dir: str = "index"

planwise/engine/adapters.py

@@ -0,0 +1,111 @@
+"""Format adapters: external tool dialects <-> the canonical ToolCard.
+
+Supported dialects:
+- "openai":    {"type": "function", "function": {"name", "description", "parameters"}}
+- "anthropic": {"name", "description", "input_schema"}
+- "mcp":       {"name", "description", "inputSchema", "outputSchema"?}
+
+Output schemas are not part of the OpenAI/Anthropic tool formats, so we
+also accept a sibling "output_schema" / "returns" key on any dialect and
+record a warning when none is present (enrichment may infer one later).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .models import ParamSpec, ToolCard, VersionInfo
+
+_VERSION_RE = re.compile(r"^(?P<family>.+?)_v(?P<num>\d+)$", re.IGNORECASE)
+
+
+def detect_dialect(raw: dict[str, Any]) -> str:
+    if raw.get("type") == "function" and "function" in raw:
+        return "openai"
+    if "inputSchema" in raw:
+        return "mcp"
+    return "anthropic"
+
+
+def _params_from_json_schema(schema: dict[str, Any] | None) -> dict[str, ParamSpec]:
+    if not schema:
+        return {}
+    required = set(schema.get("required", []))
+    out: dict[str, ParamSpec] = {}
+    for name, spec in (schema.get("properties") or {}).items():
+        out[name] = ParamSpec(
+            type=str(spec.get("type", "string")),
+            description=str(spec.get("description", "")),
+            required=name in required,
+        )
+    return out
+
+
+def _params_to_json_schema(params: dict[str, ParamSpec]) -> dict[str, Any]:
+    return {
+        "type": "object",
+        "properties": {
+            n: {"type": p.type, "description": p.description} for n, p in params.items()
+        },
+        "required": [n for n, p in params.items() if p.required],
+    }
+
+
+def _parse_version(name: str, raw: dict[str, Any]) -> VersionInfo | None:
+    m = _VERSION_RE.match(name)
+    deprecated = bool(raw.get("deprecated", False))
+    if m:
+        return VersionInfo(family=m.group("family"), number=int(m.group("num")), deprecated=deprecated)
+    if deprecated:
+        return VersionInfo(family=name, number=1, deprecated=True)
+    return None
+
+
+def to_canonical(raw: dict[str, Any], dialect: str | None = None) -> ToolCard:
+    dialect = dialect or detect_dialect(raw)
+
+    if dialect == "openai":
+        fn = raw["function"]
+        name, description = fn["name"], fn.get("description", "")
+        input_schema = fn.get("parameters")
+    elif dialect == "mcp":
+        name, description = raw["name"], raw.get("description", "")
+        input_schema = raw.get("inputSchema")
+    else:  # anthropic
+        name, description = raw["name"], raw.get("description", "")
+        input_schema = raw.get("input_schema")
+
+    output_raw = raw.get("output_schema") or raw.get("returns") or raw.get("outputSchema")
+    card = ToolCard(
+        tool_id=name,
+        description=description,
+        input_params=_params_from_json_schema(input_schema),
+        output_schema=_params_from_json_schema(output_raw),
+        version=_parse_version(name, raw),
+        source_dialect=dialect,
+        raw=raw,
+    )
+    if not card.output_schema:
+        card.warnings.append("no_output_schema")
+    return card
+
+
+def from_canonical(card: ToolCard, dialect: str = "anthropic") -> dict[str, Any]:
+    """Render a card back into the caller's dialect for hand-off."""
+    schema = _params_to_json_schema(card.input_params)
+    if dialect == "openai":
+        return {
+            "type": "function",
+            "function": {"name": card.tool_id, "description": card.description, "parameters": schema},
+        }
+    if dialect == "mcp":
+        out: dict[str, Any] = {
+            "name": card.tool_id,
+            "description": card.description,
+            "inputSchema": schema,
+        }
+        if card.output_schema:
+            out["outputSchema"] = _params_to_json_schema(card.output_schema)
+        return out
+    return {"name": card.tool_id, "description": card.description, "input_schema": schema}

planwise/engine/assembler.py

@@ -0,0 +1,133 @@
+"""Assembly: ordered plan + call counts + tool hand-off (LLD §7).
+
+- Order: topological sort of steps by depends_on (a step waits for the
+  steps it needs), ties broken by step index.
+- Count: repeat as a number -> that many entries; "per_entity" -> one per
+  matched entity, EXCEPT when the tool takes a list for that input (then
+  one call handles all items).
+- Emission: schemas sorted in execution order (we use position bias in
+  our favor) plus a short plan-hint line for the agent's prompt.
+"""
+
+from __future__ import annotations
+
+from graphlib import CycleError, TopologicalSorter
+
+from .adapters import from_canonical
+from .entities import Entity
+from .index import CatalogIndex
+from .models import Binding, PlanEntry, RouteResult, Step, TokenStats
+from .plan_validator import IRREVERSIBLE_VERBS
+
+
+def _order_steps(steps: list[Step]) -> list[Step]:
+    ts = TopologicalSorter({s.idx: set(s.depends_on) for s in steps})
+    try:
+        order = list(ts.static_order())
+    except CycleError:
+        order = [s.idx for s in steps]  # fall back to textual order
+    by_idx = {s.idx: s for s in steps}
+    # static_order is dependency-correct; make ties follow step index.
+    return sorted((by_idx[i] for i in order if i in by_idx), key=lambda s: (order.index(s.idx),))
+
+
+def _expected_calls(step: Step, tool_id: str, index: CatalogIndex, entities: list[Entity]) -> int:
+    if isinstance(step.repeat, int):
+        return max(1, step.repeat)
+    # "per_entity": one call per matched entity unless a list-typed input
+    # lets the tool take them all at once.
+    card = index.cards[tool_id]
+    if any(p.type == "array" for p in card.input_params.values()):
+        return 1
+    n = sum(1 for e in entities if e.kind in ("email", "id", "quoted"))
+    return max(1, n)
+
+
+def _estimate_tokens(payload: object) -> int:
+    """Cheap token estimate (chars/4) — good enough for the savings metric."""
+    import json
+
+    return len(json.dumps(payload, default=str)) // 4
+
+
+def assemble(
+    steps: list[Step],
+    bindings: dict[int, Binding],
+    index: CatalogIndex,
+    entities: list[Entity],
+    dialect: str = "anthropic",
+    k_max_total: int = 8,
+    merge_same_verb_only: bool = True,
+) -> RouteResult:
+    ordered = _order_steps(steps)
+
+    plan: list[PlanEntry] = []
+    tool_order: list[str] = []
+    unresolved: list[Step] = []
+    confidences: list[float] = []
+
+    for order_no, step in enumerate(ordered, start=1):
+        b = bindings.get(step.idx)
+        if b is None or b.status == "unresolved":
+            unresolved.append(step)
+            continue
+        confidences.append(b.confidence)
+        if b.status == "agent_native":
+            continue
+        primary = b.tools[0]
+        plan.append(
+            PlanEntry(
+                order=order_no,
+                step_idx=step.idx,
+                tool_id=primary,
+                expected_calls=_expected_calls(step, primary, index, entities),
+                args_hint=", ".join(step.needs),
+                irreversible=step.verb in IRREVERSIBLE_VERBS,
+            )
+        )
+        for t in b.tools:
+            if t not in tool_order:
+                tool_order.append(t)
+
+    # Merge rule: consecutive entries bound to the same tool are one call —
+    # over-splitting by the planner must not inflate the predicted count.
+    # Guard: only when the steps share a verb (the same action stated
+    # twice). Two DIFFERENT actions colliding on one tool means one of the
+    # bindings is wrong — surface the later step as unresolved rather than
+    # silently erasing an action.
+    by_idx = {s.idx: s for s in steps}
+    merged: list[PlanEntry] = []
+    for entry in plan:
+        if merged and merged[-1].tool_id == entry.tool_id and entry.expected_calls == 1:
+            if (not merge_same_verb_only
+                    or by_idx[entry.step_idx].verb == by_idx[merged[-1].step_idx].verb):
+                continue
+            unresolved.append(by_idx[entry.step_idx])
+            continue
+        merged.append(entry)
+    plan = merged
+
+    tool_order = tool_order[:k_max_total]
+    schemas = [from_canonical(index.cards[t], dialect) for t in tool_order]
+
+    hint = "Suggested plan: " + " ".join(
+        f"{i}) {e.tool_id}" + (f" x{e.expected_calls}" if e.expected_calls > 1 else "")
+        for i, e in enumerate(plan, start=1)
+    ) if plan else ""
+
+    catalog_tokens = sum(
+        _estimate_tokens(from_canonical(c, dialect)) for c in index.cards.values()
+    )
+    return RouteResult(
+        tools=schemas,
+        plan=plan,
+        plan_hint=hint,
+        bindings=list(bindings.values()),
+        steps=steps,
+        confidence=round(min(confidences), 4) if confidences else 0.0,
+        unresolved=unresolved,
+        tokens_saved=TokenStats(
+            catalog_tokens=catalog_tokens,
+            injected_tokens=sum(_estimate_tokens(s) for s in schemas),
+        ),
+    )

planwise/engine/binder.py

@@ -0,0 +1,127 @@
+"""Binding: turn a step's scored candidates into a decision (LLD §6).
+
+Order of operations matters:
+  1. gate (floor + relative margin, k_max cap)
+  2. collapse twin groups          -> siblings to fallback pool
+  3. resolve version families      -> losers to fallback pool
+  4. decide: clear winner / near-tie / unresolved
+"""
+
+from __future__ import annotations
+
+import re
+
+from ..config import RouterConfig
+from .entities import Entity, can_fill
+from .index import CatalogIndex
+from .models import Binding, Candidate, Step
+
+_PIN_OLD_RE = re.compile(r"\b(legacy|old version|v1|deprecated)\b", re.I)
+
+
+def _resolve_versions(
+    survivors: list[Candidate],
+    index: CatalogIndex,
+    query_text: str,
+    entities: list[Entity],
+    fallback: list[str],
+) -> list[Candidate]:
+    """Keep one tool per version family: newest non-deprecated wins unless
+    the query pins an old version or the newest needs an unfillable input."""
+    by_family: dict[str, list[Candidate]] = {}
+    keep: list[Candidate] = []
+    for cand in survivors:
+        v = index.cards[cand.tool_id].version
+        if v is None:
+            keep.append(cand)
+        else:
+            by_family.setdefault(v.family, []).append(cand)
+
+    pin_old = bool(_PIN_OLD_RE.search(query_text))
+    for members in by_family.values():
+        members.sort(key=lambda c: index.cards[c.tool_id].version.number, reverse=True)  # type: ignore[union-attr]
+        chosen = members[0]
+        if pin_old and len(members) > 1:
+            chosen = members[-1]  # oldest
+        else:
+            # Newest needs a required input we can't fill, but an older one can?
+            for older in members[1:]:
+                newest_ok = _all_required_fillable(chosen.tool_id, index, entities)
+                older_ok = _all_required_fillable(older.tool_id, index, entities)
+                if not newest_ok and older_ok:
+                    chosen = older
+                    break
+        keep.append(chosen)
+        fallback.extend(c.tool_id for c in members if c is not chosen)
+    keep.sort(key=lambda c: c.score, reverse=True)
+    return keep
+
+
+def _all_required_fillable(tool_id: str, index: CatalogIndex, entities: list[Entity]) -> bool:
+    card = index.cards[tool_id]
+    return all(
+        can_fill(n, p.description, entities)
+        for n, p in card.input_params.items()
+        if p.required
+    )
+
+
+def bind_step(
+    step: Step,
+    candidates: list[Candidate],
+    index: CatalogIndex,
+    query_text: str,
+    entities: list[Entity],
+    cfg: RouterConfig,
+) -> Binding:
+    binding = Binding(step_idx=step.idx, candidates=candidates[:10])
+
+    if step.agent_native:
+        binding.status = "agent_native"
+        binding.confidence = 1.0
+        return binding
+
+    # 1. Gate.
+    top = candidates[0].score if candidates else 0.0
+    gated = [
+        c for c in candidates
+        if c.score >= cfg.floor and c.score >= cfg.rel_margin * top
+    ][: cfg.k_max_per_step + 2]  # small headroom before dedup
+
+    if not gated:
+        binding.status = "unresolved"
+        return binding
+
+    fallback: list[str] = []
+
+    # 2. Twin groups: keep each group's best.
+    seen_groups: set[str] = set()
+    deduped: list[Candidate] = []
+    for cand in gated:
+        gid = index.cards[cand.tool_id].dup_group_id
+        if gid is None:
+            deduped.append(cand)
+        elif gid not in seen_groups:
+            seen_groups.add(gid)
+            deduped.append(cand)
+        else:
+            fallback.append(cand.tool_id)
+
+    # 3. Version families.
+    resolved = _resolve_versions(deduped, index, query_text, entities, fallback)
+
+    # 4. Decide.
+    best = resolved[0]
+    second = resolved[1] if len(resolved) > 1 else None
+    gap = (best.score - second.score) / best.score if second and best.score > 0 else 1.0
+
+    near_tie = second is not None and gap <= cfg.noise_band
+    ship_both = near_tie and cfg.mode == "advisory" and cfg.ambiguity_policy == "ship_both"
+
+    binding.tools = [best.tool_id, second.tool_id] if ship_both else [best.tool_id]
+    binding.fallback_pool = fallback + [
+        c.tool_id for c in resolved if c.tool_id not in binding.tools
+    ]
+    binding.status = "bound"
+    binding.confidence = round(best.score * (0.5 + 0.5 * min(gap, 1.0)), 4)
+    return binding

planwise/engine/embeddings.py

@@ -0,0 +1,88 @@
+"""Embedding backends.
+
+Two interchangeable backends behind one tiny interface:
+
+- ``SbertBackend`` — sentence-transformers (real semantic vectors). Used in
+  the actual product; needs the ``embeddings`` extra installed.
+- ``HashingBackend`` — deterministic bag-of-words vectors via feature
+  hashing. No downloads, no randomness: this is what unit tests and CI use,
+  and the automatic fallback when sentence-transformers is unavailable.
+
+Both return L2-normalized float32 matrices, so cosine similarity is a
+plain dot product everywhere downstream.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import re
+from typing import Protocol
+
+import numpy as np
+
+log = logging.getLogger(__name__)
+
+_TOKEN_RE = re.compile(r"[a-z0-9]+")
+
+
+def tokenize(text: str) -> list[str]:
+    """Lowercase word tokens; snake_case and camelCase are split upstream
+    by card_text()."""
+    return _TOKEN_RE.findall(text.lower())
+
+
+class EmbeddingBackend(Protocol):
+    dim: int
+
+    def encode(self, texts: list[str]) -> np.ndarray: ...
+
+
+class HashingBackend:
+    """Deterministic lexical embeddings (feature hashing + L2 norm).
+
+    Not semantic — two synonyms won't match — but perfectly stable, fast
+    and dependency-free. Good enough for tests and as a degraded mode;
+    BM25 carries most lexical weight anyway.
+    """
+
+    def __init__(self, dim: int = 512) -> None:
+        self.dim = dim
+
+    def _bucket(self, token: str) -> int:
+        return int.from_bytes(hashlib.md5(token.encode()).digest()[:4], "little") % self.dim
+
+    def encode(self, texts: list[str]) -> np.ndarray:
+        out = np.zeros((len(texts), self.dim), dtype=np.float32)
+        for i, text in enumerate(texts):
+            for tok in tokenize(text):
+                out[i, self._bucket(tok)] += 1.0
+        norms = np.linalg.norm(out, axis=1, keepdims=True)
+        norms[norms == 0] = 1.0
+        return out / norms
+
+
+class SbertBackend:
+    def __init__(self, model_name: str) -> None:
+        from sentence_transformers import SentenceTransformer  # lazy import
+
+        self._model = SentenceTransformer(model_name)
+        self.dim = self._model.get_sentence_embedding_dimension()
+
+    def encode(self, texts: list[str]) -> np.ndarray:
+        vecs = self._model.encode(texts, normalize_embeddings=True, show_progress_bar=False)
+        return np.asarray(vecs, dtype=np.float32)
+
+
+def make_backend(kind: str, model_name: str) -> EmbeddingBackend:
+    """Factory honoring RouterConfig.embed_backend ("auto"/"sbert"/"hashing")."""
+    if kind == "hashing":
+        return HashingBackend()
+    if kind == "sbert":
+        return SbertBackend(model_name)
+    # auto
+    try:
+        return SbertBackend(model_name)
+    except Exception as exc:  # ImportError or model download failure
+        log.warning("sentence-transformers unavailable (%s); using hashing backend", exc)
+        return HashingBackend()