opensmartroute 0.5.0__py3-none-any.whl

opensmartroute/__init__.py

@@ -0,0 +1,209 @@
+"""OpenSmartRoute — an open, intelligent route to the right decision, solution, or destination.
+
+Public SDK surface. Anything importable from this module is covered by semantic
+versioning; sub-modules may change between minor versions.
+
+Quick start::
+
+    from opensmartroute import Router, TargetRegistry, RouteTarget, TargetKind, Capabilities
+
+    reg = TargetRegistry([
+        RouteTarget("gpt-small", TargetKind.LLM, capabilities=Capabilities(max_complexity=0.5),
+                    cost={"usd_per_1k_tokens": 0.0002}),
+        RouteTarget("gpt-large", TargetKind.LLM, capabilities=Capabilities(min_complexity=0.4),
+                    cost={"usd_per_1k_tokens": 0.01}, quality_prior=0.9),
+    ])
+    router = Router(reg)
+    decision = router.route("Prove that sqrt(2) is irrational, step by step.")
+    print(decision.target.id, decision.confidence)
+    print(decision.trace.explain())
+
+Decorator SDK (see :mod:`opensmartroute.sdk`)::
+
+    import opensmartroute as osr
+
+    @osr.tool("weather", domains=["travel"], actions=["lookup"])
+    def weather(request, **kw):
+        \"\"\"Current weather for a city.\"\"\"
+        return lookup(request.text)
+
+    @osr.strategy(weight=0.8)
+    def geo_affinity(request, signals, candidates):
+        return {t.id: 1.0 if request.constraints.region in t.constraints.regions else 0.4 for t in candidates}
+
+    @osr.policy_rule
+    def business_hours(target, request, signals):
+        return "closed" if target.kind is osr.TargetKind.HUMAN and request.context.get("after_hours") else None
+
+    router = osr.components.router(reg)        # or osr.components.builder(reg).with_auto_learning().build()
+
+Settings (all tunables, ``OSR_<GROUP>_<FIELD>`` environment overrides)::
+
+    from opensmartroute import Settings, configure
+    from opensmartroute.settings import PolicySettings
+    configure(Settings().replace(policy=PolicySettings(jailbreak_threshold=0.7)))
+
+Tracing and observability (see :mod:`opensmartroute.observability`)::
+
+    from opensmartroute import configure_tracing
+    from opensmartroute.observability import MemorySink, MetricsSink
+
+    tracer = configure_tracing(MemorySink(), MetricsSink())   # or configure_tracing() -> OSR_OBSERVABILITY_*
+    d = router.route("...")
+    tracer.find(MemorySink).trace(d.request_id)              # spans + events of that request
+
+Enterprise::
+
+    from opensmartroute.enterprise import RouterBuilder, LoggingTelemetry, CacheMiddleware
+    from opensmartroute.security import GuardMiddleware
+
+    app = (RouterBuilder(reg)
+           .with_defaults()
+           .with_components()                      # everything declared with the decorators above
+           .with_auto_learning(state_dir=".osr-state")
+           .with_health(latency_slo_ms=3000)
+           .with_middleware(GuardMiddleware(redact=True), CacheMiddleware())
+           .with_telemetry(LoggingTelemetry())
+           .build())
+"""
+
+from .aio import AsyncRouter
+from .config import load_rules, load_targets
+from .core import (
+    Capabilities,
+    Objective,
+    Outcome,
+    PlanSlot,
+    RankedTarget,
+    RequestConstraints,
+    RouteDecision,
+    RoutePlan,
+    RouteRequest,
+    RouteTarget,
+    RouteTrace,
+    Signals,
+    StrategyScore,
+    TargetConstraints,
+    TargetKind,
+    TargetRegistry,
+)
+from .errors import (
+    ConfigurationError,
+    ExecutionError,
+    NoRouteError,
+    OpenSmartRouteError,
+    SecurityError,
+    StateStoreError,
+    TargetUnavailableError,
+    ValidationError,
+)
+from .execution import ExecutionResult, ExecutionStep
+from .feedback import FeedbackStore
+from .learning.self_improve import SelfImprover
+from .learning.slm import RouterSLM, SLMStrategy
+from .observability import Event, EventSink, Span, Tracer, configure_tracing, get_tracer
+from .policy import Policy
+from .router import Router
+from .sdk import (
+    ComponentRegistry,
+    agent,
+    components,
+    middleware,
+    policy_rule,
+    signal,
+    skill,
+    strategy,
+    target,
+    telemetry,
+    tool,
+)
+from .settings import Settings, configure, get_settings
+from .strategies import (
+    BanditStrategy,
+    CapabilityStrategy,
+    Cascade,
+    CascadePlanner,
+    DeferStrategy,
+    EffortStrategy,
+    LLMJudgeStrategy,
+    ProgressRouter,
+    Rule,
+    RulesStrategy,
+    SimilarityStrategy,
+    Strategy,
+    TaskTableStrategy,
+)
+
+__version__ = "0.5.0"
+
+__all__ = [
+    "AsyncRouter",
+    "BanditStrategy",
+    "Capabilities",
+    "CapabilityStrategy",
+    "Cascade",
+    "CascadePlanner",
+    "ComponentRegistry",
+    "ConfigurationError",
+    "DeferStrategy",
+    "EffortStrategy",
+    "Event",
+    "EventSink",
+    "ExecutionError",
+    "ExecutionResult",
+    "ExecutionStep",
+    "FeedbackStore",
+    "LLMJudgeStrategy",
+    "NoRouteError",
+    "Objective",
+    "OpenSmartRouteError",
+    "Outcome",
+    "PlanSlot",
+    "Policy",
+    "ProgressRouter",
+    "RankedTarget",
+    "RequestConstraints",
+    "RouteDecision",
+    "RoutePlan",
+    "RouteRequest",
+    "RouteTarget",
+    "RouteTrace",
+    "Router",
+    "RouterSLM",
+    "Rule",
+    "RulesStrategy",
+    "SLMStrategy",
+    "SecurityError",
+    "SelfImprover",
+    "Settings",
+    "Signals",
+    "SimilarityStrategy",
+    "Span",
+    "StateStoreError",
+    "Strategy",
+    "StrategyScore",
+    "TargetConstraints",
+    "TargetKind",
+    "TargetRegistry",
+    "TargetUnavailableError",
+    "TaskTableStrategy",
+    "Tracer",
+    "ValidationError",
+    "__version__",
+    "agent",
+    "components",
+    "configure",
+    "configure_tracing",
+    "get_settings",
+    "get_tracer",
+    "load_rules",
+    "load_targets",
+    "middleware",
+    "policy_rule",
+    "signal",
+    "skill",
+    "strategy",
+    "target",
+    "telemetry",
+    "tool",
+]

opensmartroute/adapters/__init__.py

@@ -0,0 +1,162 @@
+"""Adapters connect OpenSmartRoute to real providers and infrastructure.
+
+* :mod:`openai_compat` — stdlib HTTP client for any OpenAI-compatible API
+  (OpenAI, Azure OpenAI, vLLM, Ollama, LiteLLM, OpenRouter, Groq, Mistral …) with
+  glue for the LLM judge, the similarity embedder, and target handlers.
+* :mod:`optional` — sentence-transformers embedder and OpenTelemetry telemetry,
+  lazily imported so the core stays dependency-free.
+* :mod:`harness` — agent-harness adapters (callable, HTTP, subprocess CLI) so a
+  coding / research / support runtime is a routable ``TargetKind.AGENT``.
+* :mod:`skills` — load Agent-Skills ``SKILL.md`` packages as ``TargetKind.SKILL``.
+* :mod:`mcp` — MCP ``tools/list`` import (+ stdio client), description enrichment,
+  HMAC / Ed25519 signed manifests.
+* :mod:`a2a` — A2A Agent Cards as ``TargetKind.AGENT`` (+ per-skill slot targets).
+* :mod:`mcp_servers` — rank MCP *servers* for a task before connecting (server cards).
+* :mod:`semantic_router` — import a vLLM semantic-router ``config.yaml`` as targets + rules.
+* :mod:`personas` — persona catalogues (markdown dirs, JSON/CSV, ``*.agent.md``).
+* :mod:`frameworks` — LangGraph node / Agent Framework executor / OpenAI tool spec.
+* :mod:`handlers` — executors for non-LLM targets: HTTP endpoints, MCP tools, async queues
+  (humans, ticketing, long-running workflows) returning a pending ticket.
+* :mod:`catalogue` — live model catalogue (OpenRouter prices, Hugging Face cards) → targets,
+  cost/quality benchmark table and Pareto frontier.
+* :mod:`websearch` — bounded https fetch, HTML→text, keyless search providers (Hugging Face,
+  DuckDuckGo; Brave with a key) behind :class:`WebKnowledge` for the self-improving SLM.
+"""
+
+from .a2a import a2a_handler, agent_from_card, fetch_agent_card, skills_from_card
+from .catalogue import (
+    ModelCard,
+    ModelCatalogue,
+    card_to_target,
+    fetch_huggingface_models,
+    fetch_leaderboard_quality,
+    fetch_openrouter_models,
+    model_key,
+    quality_from_benchmarks,
+    quality_from_popularity,
+)
+from .frameworks import (
+    langgraph_condition,
+    langgraph_node,
+    maf_router_executor,
+    openai_tool_handler,
+    openai_tool_spec,
+    route_and_execute,
+)
+from .handlers import (
+    InMemoryQueue,
+    PendingResult,
+    Queue,
+    QueuedItem,
+    http_handler,
+    mcp_tool_handler,
+    queue_handler,
+)
+from .harness import (
+    AgentHarness,
+    CallableHarness,
+    HarnessResult,
+    HTTPHarness,
+    SubprocessHarness,
+    harness_handler,
+)
+from .mcp import (
+    StdioMCPClient,
+    connect_mcp,
+    enrich_description,
+    manifest_from_targets,
+    sign_manifest,
+    tools_from_manifest,
+    tools_from_mcp,
+    verify_manifest,
+)
+from .mcp_servers import ServerCard, ServerRecommendation, recommend_servers
+from .openai_compat import ChatResult, OpenAICompatClient, attach_chat_handlers, chat_handler, embedder, judge_fn
+from .optional import OpenTelemetrySink, OpenTelemetryTelemetry, sentence_transformers_embedder
+from .personas import load_personas, persona_from_markdown, persona_target, personas_from_records
+from .semantic_router import SemanticRouterImport, load_semantic_router_config
+from .skills import load_skill, load_skills, skill_from_markdown
+from .websearch import (
+    SearchHit,
+    WebKnowledge,
+    brave_search,
+    duckduckgo_search,
+    fetch_bytes,
+    fetch_json,
+    fetch_page_text,
+    html_to_text,
+    huggingface_search,
+)
+
+__all__ = [
+    "AgentHarness",
+    "CallableHarness",
+    "ChatResult",
+    "HTTPHarness",
+    "HarnessResult",
+    "InMemoryQueue",
+    "ModelCard",
+    "ModelCatalogue",
+    "OpenAICompatClient",
+    "OpenTelemetrySink",
+    "OpenTelemetryTelemetry",
+    "PendingResult",
+    "Queue",
+    "QueuedItem",
+    "SearchHit",
+    "SemanticRouterImport",
+    "ServerCard",
+    "ServerRecommendation",
+    "StdioMCPClient",
+    "SubprocessHarness",
+    "WebKnowledge",
+    "a2a_handler",
+    "agent_from_card",
+    "brave_search",
+    "card_to_target",
+    "attach_chat_handlers",
+    "chat_handler",
+    "connect_mcp",
+    "duckduckgo_search",
+    "embedder",
+    "enrich_description",
+    "fetch_agent_card",
+    "fetch_bytes",
+    "fetch_huggingface_models",
+    "fetch_json",
+    "fetch_leaderboard_quality",
+    "fetch_openrouter_models",
+    "fetch_page_text",
+    "harness_handler",
+    "html_to_text",
+    "http_handler",
+    "huggingface_search",
+    "judge_fn",
+    "langgraph_condition",
+    "langgraph_node",
+    "load_personas",
+    "load_semantic_router_config",
+    "load_skill",
+    "load_skills",
+    "maf_router_executor",
+    "manifest_from_targets",
+    "model_key",
+    "mcp_tool_handler",
+    "openai_tool_handler",
+    "openai_tool_spec",
+    "persona_from_markdown",
+    "persona_target",
+    "personas_from_records",
+    "quality_from_benchmarks",
+    "quality_from_popularity",
+    "queue_handler",
+    "recommend_servers",
+    "route_and_execute",
+    "sentence_transformers_embedder",
+    "sign_manifest",
+    "skill_from_markdown",
+    "skills_from_card",
+    "tools_from_manifest",
+    "tools_from_mcp",
+    "verify_manifest",
+]

opensmartroute/adapters/a2a.py

@@ -0,0 +1,246 @@
+"""Import A2A (Agent-to-Agent protocol) **Agent Cards** as ``TargetKind.AGENT`` targets.
+
+An Agent Card (served at ``/.well-known/agent.json`` / ``agent-card.json``) advertises an
+agent's ``name``, ``description``, ``url``, ``skills`` (each with ``id``, ``name``,
+``description``, ``tags``, ``examples``, ``inputModes``/``outputModes``), ``capabilities``
+(``streaming``, ``pushNotifications``) and ``defaultInputModes``/``defaultOutputModes``.
+
+* :func:`agent_from_card` – one target per agent, whose routing text/examples are the union of
+  its skills (so the agent is found for any of them).
+* :func:`skills_from_card` – optionally one ``TargetKind.SKILL`` target per advertised skill,
+  ``primary=False`` and linked to the agent through ``metadata["agent_id"]``; lets the planner
+  pick a specific skill and the executor pass ``skillId`` to the agent.
+* :func:`a2a_handler` – stdlib JSON-RPC ``message/send`` client (``tasks/send`` for older
+  servers) so the imported agent is executable; extracts the text parts of the final
+  artifact / status message.
+* :func:`fetch_agent_card` – GET the well-known card over https.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+import uuid
+from collections.abc import Callable
+from typing import Any
+
+from ..core.types import Capabilities, RouteRequest, RouteTarget, TargetKind
+from ..errors import ConfigurationError, ExecutionError, TargetUnavailableError
+
+_MODALITY = {
+    "text": "text",
+    "text/plain": "text",
+    "application/json": "text",
+    "image": "image",
+    "image/png": "image",
+    "image/jpeg": "image",
+    "audio": "audio",
+    "audio/wav": "audio",
+    "audio/mpeg": "audio",
+    "video": "video",
+    "video/mp4": "video",
+    "file": "file",
+}
+
+
+def _modes(values: Any) -> list[str]:
+    out: list[str] = []
+    for v in values or []:
+        m = _MODALITY.get(str(v).lower(), str(v).split("/")[0].lower())
+        if m not in out:
+            out.append(m)
+    return out or ["text"]
+
+
+def _agent_id(card: dict[str, Any]) -> str:
+    name = str(card.get("name", "agent")).strip().lower()
+    slug = "".join(c if c.isalnum() else "-" for c in name).strip("-")
+    return f"a2a:{slug or 'agent'}"
+
+
+def agent_from_card(
+    card: dict[str, Any],
+    *,
+    call: Callable[[str, RouteRequest], Any] | None = None,
+    cost_per_1k_tokens: float = 0.0,
+    latency_ms: float = 2000.0,
+    quality_prior: float = 0.65,
+    languages: list[str] | None = None,
+) -> RouteTarget:
+    """Build an ``agent`` RouteTarget from an A2A agent card (name, skills, tags, input modes)."""
+    if not isinstance(card, dict) or not card.get("name"):
+        raise ConfigurationError("agent card must be a mapping with a name")
+    skills = [s for s in card.get("skills", []) if isinstance(s, dict)]
+    examples: list[str] = []
+    tags: list[str] = ["a2a"]
+    domains: list[str] = []
+    actions: list[str] = []
+    for s in skills:
+        examples += [str(e) for e in s.get("examples", []) if isinstance(e, str)]
+        d = s.get("description")
+        if isinstance(d, str) and d:
+            examples.append(d)
+        for t in s.get("tags", []) or []:
+            t = str(t).lower()
+            tags.append(t)
+            domains.append(t)
+        sid = str(s.get("id", "")).lower()
+        if sid:
+            actions.append(sid)
+    modalities = _modes(card.get("defaultInputModes")) + [m for s in skills for m in _modes(s.get("inputModes"))]
+    caps = Capabilities(
+        domains=list(dict.fromkeys(domains)),
+        actions=list(dict.fromkeys(actions)),
+        languages=languages or ["en"],
+        modalities=list(dict.fromkeys(modalities)),
+        tags=list(dict.fromkeys(tags)),
+        supports_tools=True,
+        supports_streaming=bool((card.get("capabilities") or {}).get("streaming", False)),
+    )
+    url = str(card.get("url", ""))
+    handler = None
+    if call is not None:
+        agent_url = url
+
+        def _h(request: RouteRequest, **_: Any) -> Any:
+            return call(agent_url, request)
+
+        handler = _h
+    elif url.startswith("https://"):
+        handler = a2a_handler(url)
+    return RouteTarget(
+        id=_agent_id(card),
+        kind=TargetKind.AGENT,
+        name=str(card["name"]),
+        description=str(card.get("description", "")),
+        capabilities=caps,
+        cost={"usd_per_1k_tokens": cost_per_1k_tokens},
+        latency_ms=latency_ms,
+        quality_prior=quality_prior,
+        examples=examples[:24],
+        handler=handler,
+        metadata={
+            "source": "a2a",
+            "url": url,
+            "version": card.get("version"),
+            "provider": card.get("provider"),
+            "skills": [str(s.get("id", "")) for s in skills],
+            "capabilities": card.get("capabilities", {}),
+            "security_schemes": list((card.get("securitySchemes") or {}).keys()),
+        },
+    )
+
+
+def skills_from_card(card: dict[str, Any], agent_id: str | None = None) -> list[RouteTarget]:
+    """One non-primary ``skill`` target per skill declared on an A2A agent card (``<agent>/<skill>``)."""
+    aid = agent_id or _agent_id(card)
+    out: list[RouteTarget] = []
+    for s in card.get("skills", []) or []:
+        if not isinstance(s, dict) or not s.get("id"):
+            continue
+        tags = [str(t).lower() for t in s.get("tags", []) or []]
+        out.append(
+            RouteTarget(
+                id=f"{aid}/{s['id']}",
+                kind=TargetKind.SKILL,
+                name=str(s.get("name", s["id"])),
+                description=str(s.get("description", "")),
+                capabilities=Capabilities(
+                    domains=tags, tags=["a2a-skill", *tags], modalities=_modes(s.get("inputModes"))
+                ),
+                quality_prior=0.65,
+                examples=[str(e) for e in s.get("examples", []) if isinstance(e, str)],
+                primary=False,
+                metadata={"source": "a2a", "agent_id": aid, "skill_id": str(s["id"])},
+            )
+        )
+    return out
+
+
+def fetch_agent_card(base_url: str, timeout_s: float = 10.0, path: str = "/.well-known/agent.json") -> dict[str, Any]:
+    """Download an agent card over HTTPS (plain HTTP is refused); raises TargetUnavailableError on failure."""
+    if not base_url.startswith("https://"):
+        raise ConfigurationError("agent card url must be https")
+    url = base_url.rstrip("/") + path
+    req = urllib.request.Request(url, headers={"Accept": "application/json"})  # noqa: S310 - https enforced
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as resp:  # noqa: S310  # nosec B310 - https enforced above
+            data = json.loads(resp.read().decode())
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as e:
+        raise TargetUnavailableError(
+            "could not fetch agent card", details={"url": url, "error": type(e).__name__}
+        ) from None
+    if not isinstance(data, dict):
+        raise ConfigurationError("agent card is not a JSON object")
+    return data
+
+
+def _extract_text(result: Any) -> str:
+    texts: list[str] = []
+
+    def walk(o: Any) -> None:
+        if isinstance(o, dict):
+            if o.get("kind") == "text" or o.get("type") == "text":
+                t = o.get("text")
+                if isinstance(t, str):
+                    texts.append(t)
+            for k in ("artifacts", "parts", "status", "message", "history", "result"):
+                if k in o:
+                    walk(o[k])
+        elif isinstance(o, list):
+            for x in o:
+                walk(x)
+
+    walk(result)
+    return "\n".join(texts)
+
+
+def a2a_handler(
+    url: str,
+    token: str | None = None,
+    timeout_s: float = 60.0,
+    method: str = "message/send",
+) -> Callable[..., Any]:
+    """Return a handler that sends the request text to an A2A agent and returns its text."""
+    if not url.startswith(("https://", "http://localhost", "http://127.0.0.1")):
+        raise ConfigurationError("a2a url must be https (or localhost)")
+    headers = {"Content-Type": "application/json", "Accept": "application/json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    def _h(request: RouteRequest, **_: Any) -> Any:
+        msg: dict[str, Any] = {
+            "role": "user",
+            "parts": [{"kind": "text", "text": request.text}],
+            "messageId": uuid.uuid4().hex,
+        }
+        skill = request.context.get("skill_id")
+        params: dict[str, Any] = {"message": msg}
+        if isinstance(skill, str) and skill:
+            params["metadata"] = {"skillId": skill}
+        body = json.dumps({"jsonrpc": "2.0", "id": uuid.uuid4().hex, "method": method, "params": params}).encode()
+        req = urllib.request.Request(url, data=body, headers=headers, method="POST")  # noqa: S310
+        t0 = time.perf_counter()
+        try:
+            with urllib.request.urlopen(req, timeout=timeout_s) as resp:  # noqa: S310  # nosec B310 - scheme validated
+                data = json.loads(resp.read().decode())
+        except urllib.error.HTTPError as e:
+            raise TargetUnavailableError(f"a2a upstream {e.code}", details={"url": url}) from None
+        except (urllib.error.URLError, TimeoutError) as e:
+            raise TargetUnavailableError(
+                "a2a connection failed", details={"url": url, "error": type(e).__name__}
+            ) from None
+        if "error" in data:
+            raise ExecutionError("a2a error", details=data["error"])
+        return {
+            "text": _extract_text(data.get("result")),
+            "raw": data.get("result"),
+            "latency_ms": (time.perf_counter() - t0) * 1000,
+        }
+
+    return _h
+
+
+__all__ = ["a2a_handler", "agent_from_card", "fetch_agent_card", "skills_from_card"]