execweave 0.6.0__py3-none-any.whl

execweave/inference_gateway.py

@@ -0,0 +1,422 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def sanitize_gateway_endpoint(endpoint: str) -> str:
+    split = urlsplit(endpoint)
+    if split.scheme not in {"http", "https"} or not split.hostname:
+        raise ValueError("inference gateway endpoint must be an http(s) URL")
+    host = split.hostname
+    if ":" in host and not host.startswith("["):
+        host = f"[{host}]"
+    if split.port is not None:
+        host = f"{host}:{split.port}"
+    path = split.path.rstrip("/")
+    return urlunsplit((split.scheme, host, path, "", ""))
+
+
+def _entity(
+    entity_type: str,
+    entity_id: str,
+    *,
+    name: str | None = None,
+    attributes: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return {"type": entity_type, "id": entity_id, "name": name, "attributes": attributes or {}}
+
+
+def _gateway_entity(gateway: str, endpoint: str) -> dict[str, Any]:
+    safe_endpoint = sanitize_gateway_endpoint(endpoint)
+    digest = hashlib.sha256(safe_endpoint.encode("utf-8")).hexdigest()[:24]
+    return _entity(
+        "inference_gateway",
+        f"inference-gateway:{gateway}:{digest}",
+        name=gateway,
+        attributes={"gateway": gateway, "endpoint": safe_endpoint},
+    )
+
+
+def _model_entity(model: str) -> dict[str, Any]:
+    return _entity(
+        "model",
+        f"model:catalog:{model}",
+        name=model,
+        attributes={"catalog_id": model},
+    )
+
+
+def _provider_entity(provider: str) -> dict[str, Any]:
+    slug = hashlib.sha256(provider.encode("utf-8", errors="replace")).hexdigest()[:24]
+    return _entity(
+        "inference_provider",
+        f"inference-provider:{slug}",
+        name=provider,
+        attributes={"provider_name": provider},
+    )
+
+
+def _deployment_entity(gateway: str, deployment: str) -> dict[str, Any]:
+    slug = hashlib.sha256(deployment.encode("utf-8", errors="replace")).hexdigest()[:24]
+    return _entity(
+        "inference_deployment",
+        f"inference-deployment:{gateway}:{slug}",
+        name=deployment,
+        attributes={"gateway": gateway, "deployment_id": deployment},
+    )
+
+
+def _event(
+    *,
+    timestamp: str,
+    event_type: str,
+    relation: str,
+    source: dict[str, Any],
+    target: dict[str, Any],
+    gateway: str,
+    attributes: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    merged = {
+        "backend": "inference_gateway",
+        "attribution": "gateway_api",
+        "evidence_source": "gateway_response",
+        "gateway": gateway,
+        "causal": False,
+    }
+    if attributes:
+        merged.update(attributes)
+    return {
+        "timestamp": timestamp,
+        "event_type": event_type,
+        "relation": relation,
+        "source": source,
+        "target": target,
+        "attributes": merged,
+    }
+
+
+def _request_id(payload: dict[str, Any], explicit: str | None) -> str:
+    if explicit:
+        return explicit
+    native = payload.get("id")
+    if isinstance(native, str) and native:
+        return native
+    seed = {
+        "model": payload.get("model"),
+        "created": payload.get("created"),
+        "usage": payload.get("usage"),
+    }
+    raw = json.dumps(seed, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return hashlib.sha256(raw.encode("utf-8", errors="replace")).hexdigest()[:32]
+
+
+def _copy_int(mapping: dict[str, Any], source: str, target: str, attrs: dict[str, Any]) -> None:
+    value = mapping.get(source)
+    if isinstance(value, int) and not isinstance(value, bool) and target not in attrs:
+        attrs[target] = value
+
+
+def _usage_attributes(payload: dict[str, Any]) -> dict[str, Any]:
+    attrs: dict[str, Any] = {"protocol": "openai_compatible"}
+    usage = payload.get("usage")
+    if not isinstance(usage, dict):
+        return attrs
+    for source, target in (
+        ("prompt_tokens", "prompt_tokens"),
+        ("input_tokens", "prompt_tokens"),
+        ("completion_tokens", "completion_tokens"),
+        ("output_tokens", "completion_tokens"),
+        ("total_tokens", "total_tokens"),
+    ):
+        _copy_int(usage, source, target, attrs)
+    cost = usage.get("cost")
+    if isinstance(cost, (int, float)) and not isinstance(cost, bool):
+        attrs["cost_usd"] = float(cost)
+    for detail_key in ("prompt_tokens_details", "input_tokens_details"):
+        details = usage.get(detail_key)
+        if not isinstance(details, dict):
+            continue
+        for source, target in (
+            ("cached_tokens", "cached_prompt_tokens"),
+            ("cache_write_tokens", "cache_write_tokens"),
+        ):
+            _copy_int(details, source, target, attrs)
+    for detail_key in ("completion_tokens_details", "output_tokens_details"):
+        details = usage.get(detail_key)
+        if isinstance(details, dict):
+            _copy_int(details, "reasoning_tokens", "reasoning_tokens", attrs)
+    for source, target in (
+        ("cache_creation_input_tokens", "cache_write_tokens"),
+        ("cache_read_input_tokens", "cached_prompt_tokens"),
+    ):
+        _copy_int(usage, source, target, attrs)
+    return attrs
+
+
+def gateway_response_to_events(
+    payload: dict[str, Any],
+    *,
+    gateway_name: str,
+    endpoint: str,
+    requested_model: str | None = None,
+    resolved_model: str | None = None,
+    provider_name: str | None = None,
+    deployment_id: str | None = None,
+    request_id: str | None = None,
+    timestamp: str | None = None,
+) -> list[dict[str, Any]]:
+    observed_at = timestamp or _now()
+    gateway = _gateway_entity(gateway_name, endpoint)
+    native_id = _request_id(payload, request_id)
+    response_model = payload.get("model")
+    resolved = resolved_model
+    if not isinstance(resolved, str) or not resolved:
+        resolved = response_model if isinstance(response_model, str) and response_model else None
+
+    attrs = _usage_attributes(payload)
+    if isinstance(requested_model, str) and requested_model:
+        attrs["requested_model"] = requested_model
+    if isinstance(resolved, str) and resolved:
+        attrs["resolved_model"] = resolved
+    if isinstance(provider_name, str) and provider_name:
+        attrs["provider_name"] = provider_name
+    if isinstance(deployment_id, str) and deployment_id:
+        attrs["deployment_id"] = deployment_id
+
+    request = _entity(
+        "inference_request",
+        f"inference-request:{gateway_name}:{native_id}",
+        name=native_id,
+        attributes={"gateway": gateway_name, **attrs},
+    )
+    events = [
+        _event(
+            timestamp=observed_at,
+            event_type=f"inference_gateway.{gateway_name}.response.observed",
+            relation="SERVED_INFERENCE",
+            source=gateway,
+            target=request,
+            gateway=gateway_name,
+            attributes=attrs,
+        )
+    ]
+    if isinstance(requested_model, str) and requested_model:
+        events.append(
+            _event(
+                timestamp=observed_at,
+                event_type=f"inference_gateway.{gateway_name}.model.requested",
+                relation="REQUESTED_MODEL",
+                source=request,
+                target=_model_entity(requested_model),
+                gateway=gateway_name,
+                attributes=attrs,
+            )
+        )
+    if isinstance(resolved, str) and resolved:
+        events.append(
+            _event(
+                timestamp=observed_at,
+                event_type=f"inference_gateway.{gateway_name}.model.resolved",
+                relation="ROUTED_TO_MODEL",
+                source=request,
+                target=_model_entity(resolved),
+                gateway=gateway_name,
+                attributes=attrs,
+            )
+        )
+    if isinstance(provider_name, str) and provider_name:
+        events.append(
+            _event(
+                timestamp=observed_at,
+                event_type=f"inference_gateway.{gateway_name}.provider.resolved",
+                relation="ROUTED_TO_PROVIDER",
+                source=request,
+                target=_provider_entity(provider_name),
+                gateway=gateway_name,
+                attributes=attrs,
+            )
+        )
+    if isinstance(deployment_id, str) and deployment_id:
+        events.append(
+            _event(
+                timestamp=observed_at,
+                event_type=f"inference_gateway.{gateway_name}.deployment.resolved",
+                relation="ROUTED_TO_DEPLOYMENT",
+                source=request,
+                target=_deployment_entity(gateway_name, deployment_id),
+                gateway=gateway_name,
+                attributes=attrs,
+            )
+        )
+    return events
+
+
+def openrouter_response_to_events(
+    payload: dict[str, Any],
+    *,
+    requested_model: str | None = None,
+    resolved_model: str | None = None,
+    provider_name: str | None = None,
+    deployment_id: str | None = None,
+    endpoint: str = "https://openrouter.ai/api/v1",
+    request_id: str | None = None,
+    timestamp: str | None = None,
+) -> list[dict[str, Any]]:
+    return gateway_response_to_events(
+        payload,
+        gateway_name="openrouter",
+        endpoint=endpoint,
+        requested_model=requested_model,
+        resolved_model=resolved_model,
+        provider_name=provider_name,
+        deployment_id=deployment_id,
+        request_id=request_id,
+        timestamp=timestamp,
+    )
+
+
+def litellm_response_to_events(
+    payload: dict[str, Any],
+    *,
+    requested_model: str | None = None,
+    resolved_model: str | None = None,
+    provider_name: str | None = None,
+    deployment_id: str | None = None,
+    endpoint: str = "http://localhost:4000",
+    request_id: str | None = None,
+    timestamp: str | None = None,
+) -> list[dict[str, Any]]:
+    return gateway_response_to_events(
+        payload,
+        gateway_name="litellm",
+        endpoint=endpoint,
+        requested_model=requested_model,
+        resolved_model=resolved_model,
+        provider_name=provider_name,
+        deployment_id=deployment_id,
+        request_id=request_id,
+        timestamp=timestamp,
+    )
+
+
+def openrouter_generation_to_events(
+    payload: dict[str, Any],
+    *,
+    endpoint: str = "https://openrouter.ai/api/v1",
+    timestamp: str | None = None,
+) -> list[dict[str, Any]]:
+    data = payload.get("data") if isinstance(payload.get("data"), dict) else payload
+    if not isinstance(data, dict):
+        raise ValueError("OpenRouter generation payload must be a JSON object")
+    generation_id = data.get("id")
+    if not isinstance(generation_id, str) or not generation_id:
+        raise ValueError("OpenRouter generation metadata requires id")
+    observed_at = timestamp or _now()
+    gateway = _gateway_entity("openrouter", endpoint)
+
+    attrs: dict[str, Any] = {"protocol": "openrouter_generation"}
+    for key in (
+        "latency",
+        "generation_time",
+        "total_cost",
+        "tokens_prompt",
+        "tokens_completion",
+        "native_tokens_prompt",
+        "native_tokens_completion",
+    ):
+        value = data.get(key)
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            attrs[key] = value
+    for key in ("streamed", "cancelled"):
+        value = data.get(key)
+        if isinstance(value, bool):
+            attrs[key] = value
+
+    request = _entity(
+        "inference_request",
+        f"inference-request:openrouter:{generation_id}",
+        name=generation_id,
+        attributes={"gateway": "openrouter", **attrs},
+    )
+    events = [
+        _event(
+            timestamp=observed_at,
+            event_type="inference_gateway.openrouter.generation.observed",
+            relation="REPORTED_GENERATION_METADATA",
+            source=gateway,
+            target=request,
+            gateway="openrouter",
+            attributes=attrs,
+        )
+    ]
+
+    model = data.get("model") or data.get("model_name")
+    if isinstance(model, str) and model:
+        events.append(
+            _event(
+                timestamp=observed_at,
+                event_type="inference_gateway.openrouter.model.resolved",
+                relation="ROUTED_TO_MODEL",
+                source=request,
+                target=_model_entity(model),
+                gateway="openrouter",
+                attributes=attrs,
+            )
+        )
+    provider = data.get("provider_name") or data.get("provider")
+    if isinstance(provider, str) and provider:
+        events.append(
+            _event(
+                timestamp=observed_at,
+                event_type="inference_gateway.openrouter.provider.resolved",
+                relation="ROUTED_TO_PROVIDER",
+                source=request,
+                target=_provider_entity(provider),
+                gateway="openrouter",
+                attributes=attrs,
+            )
+        )
+    return events
+
+
+def append_gateway_records(path: str | Path, records: list[dict[str, Any]]) -> Path:
+    output = Path(path).expanduser().resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    if not records:
+        return output
+    blob = "".join(
+        json.dumps(record, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n"
+        for record in records
+    )
+    lock_dir = output.with_name(output.name + ".lock")
+    deadline = time.monotonic() + 5.0
+    while True:
+        try:
+            lock_dir.mkdir()
+            break
+        except FileExistsError:
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"timed out waiting for inference gateway sidecar lock: {lock_dir}")
+            time.sleep(0.01)
+    try:
+        with output.open("a", encoding="utf-8", newline="\n") as handle:
+            handle.write(blob)
+            handle.flush()
+            os.fsync(handle.fileno())
+    finally:
+        try:
+            lock_dir.rmdir()
+        except OSError:
+            pass
+    return output

execweave/inference_gateway_cli.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from .inference_gateway import (
+    append_gateway_records,
+    litellm_response_to_events,
+    openrouter_generation_to_events,
+    openrouter_response_to_events,
+    sanitize_gateway_endpoint,
+)
+
+_GATEWAYS = ("openrouter", "litellm")
+
+
+def _sidecar(value: Path | None) -> Path:
+    if value is not None:
+        return value
+    configured = os.environ.get("EXECWEAVE_SEMANTIC_SIDECAR")
+    if configured:
+        return Path(configured)
+    raise ValueError("--sidecar or EXECWEAVE_SEMANTIC_SIDECAR is required")
+
+
+def _read_json_stdin() -> dict:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        raise ValueError("stdin is empty")
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"stdin is invalid JSON: {exc.msg}") from exc
+    if not isinstance(payload, dict):
+        raise ValueError("stdin must contain one JSON object")
+    return payload
+
+
+def _default_endpoint(gateway: str) -> str:
+    return {
+        "openrouter": "https://openrouter.ai/api/v1",
+        "litellm": "http://localhost:4000",
+    }[gateway]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="execweave-inference-gateway",
+        description="Capture inference gateway routing/usage metadata without prompt or response content.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    event = sub.add_parser("event", help="Convert one final gateway response into metadata events.")
+    event.add_argument("--gateway", choices=_GATEWAYS, required=True)
+    event.add_argument("--endpoint", default=None)
+    event.add_argument("--requested-model", default=None)
+    event.add_argument("--resolved-model", default=None)
+    event.add_argument("--provider-name", default=None)
+    event.add_argument("--deployment-id", default=None)
+    event.add_argument("--request-id", default=None)
+    event.add_argument("--sidecar", type=Path, default=None)
+
+    generation = sub.add_parser(
+        "generation",
+        help="Convert OpenRouter generation metadata into routing/performance events.",
+    )
+    generation.add_argument("--gateway", choices=["openrouter"], required=True)
+    generation.add_argument("--endpoint", default=None)
+    generation.add_argument("--sidecar", type=Path, default=None)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        payload = _read_json_stdin()
+        endpoint = sanitize_gateway_endpoint(args.endpoint or _default_endpoint(args.gateway))
+        if args.command == "event":
+            converters = {
+                "openrouter": openrouter_response_to_events,
+                "litellm": litellm_response_to_events,
+            }
+            records = converters[args.gateway](
+                payload,
+                requested_model=args.requested_model,
+                resolved_model=args.resolved_model,
+                provider_name=args.provider_name,
+                deployment_id=args.deployment_id,
+                endpoint=endpoint,
+                request_id=args.request_id,
+            )
+        else:
+            records = openrouter_generation_to_events(payload, endpoint=endpoint)
+        output = append_gateway_records(_sidecar(args.sidecar), records)
+    except (OSError, TimeoutError, ValueError) as exc:
+        parser.error(str(exc))
+    print(json.dumps({"records": len(records), "sidecar": str(output)}, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

execweave/inference_identity.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import hashlib
+from datetime import datetime, timezone
+from typing import Any
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _entity(
+    entity_type: str,
+    entity_id: str,
+    *,
+    name: str | None = None,
+    attributes: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return {"type": entity_type, "id": entity_id, "name": name, "attributes": attributes or {}}
+
+
+def _required(value: str, *, field: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{field} must be a non-empty string")
+    return value
+
+
+def gateway_runtime_identity_event(
+    *,
+    gateway: str,
+    gateway_request_id: str,
+    runtime: str,
+    runtime_request_id: str,
+    shared_request_id: str,
+    timestamp: str | None = None,
+) -> dict[str, Any]:
+    gateway = _required(gateway, field="gateway")
+    gateway_request_id = _required(gateway_request_id, field="gateway_request_id")
+    runtime = _required(runtime, field="runtime")
+    runtime_request_id = _required(runtime_request_id, field="runtime_request_id")
+    shared_request_id = _required(shared_request_id, field="shared_request_id")
+
+    shared_hash = hashlib.sha256(
+        shared_request_id.encode("utf-8", errors="replace")
+    ).hexdigest()[:32]
+    source = _entity(
+        "inference_request",
+        f"inference-request:{gateway}:{gateway_request_id}",
+        name=gateway_request_id,
+        attributes={"gateway": gateway},
+    )
+    target = _entity(
+        "inference_request",
+        f"inference-request:{runtime}:{runtime_request_id}",
+        name=runtime_request_id,
+        attributes={"provider": runtime},
+    )
+    return {
+        "timestamp": timestamp or _now(),
+        "event_type": "inference_identity.gateway_runtime.exact",
+        "relation": "SAME_INFERENCE_REQUEST",
+        "source": source,
+        "target": target,
+        "attributes": {
+            "backend": "cross_layer_identity",
+            "attribution": "explicit_shared_request_id",
+            "evidence_source": "caller_supplied_shared_request_id",
+            "gateway": gateway,
+            "runtime": runtime,
+            "causal": False,
+            "inferred": False,
+            "identity_exact": True,
+            "identity_method": "shared_request_id",
+            "shared_request_id_hash": shared_hash,
+        },
+    }

execweave/inference_identity_cli.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+
+from .inference_gateway import append_gateway_records
+from .inference_identity import gateway_runtime_identity_event
+
+_GATEWAYS = ("openrouter", "litellm")
+_RUNTIMES = ("ollama", "llamacpp", "vllm", "lmstudio")
+
+
+def _sidecar(value: Path | None) -> Path:
+    if value is not None:
+        return value
+    configured = os.environ.get("EXECWEAVE_SEMANTIC_SIDECAR")
+    if configured:
+        return Path(configured)
+    raise ValueError("--sidecar or EXECWEAVE_SEMANTIC_SIDECAR is required")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="execweave-inference-link",
+        description=(
+            "Link gateway and model-runtime request nodes only when an explicit shared request "
+            "identity is available."
+        ),
+    )
+    parser.add_argument("--gateway", choices=_GATEWAYS, required=True)
+    parser.add_argument("--gateway-request-id", required=True)
+    parser.add_argument("--runtime", choices=_RUNTIMES, required=True)
+    parser.add_argument("--runtime-request-id", required=True)
+    parser.add_argument("--shared-request-id", required=True)
+    parser.add_argument("--sidecar", type=Path, default=None)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        record = gateway_runtime_identity_event(
+            gateway=args.gateway,
+            gateway_request_id=args.gateway_request_id,
+            runtime=args.runtime,
+            runtime_request_id=args.runtime_request_id,
+            shared_request_id=args.shared_request_id,
+        )
+        output = append_gateway_records(_sidecar(args.sidecar), [record])
+    except (OSError, TimeoutError, ValueError) as exc:
+        parser.error(str(exc))
+    print(json.dumps({"records": 1, "sidecar": str(output)}, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())