gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/build.py

@@ -0,0 +1,515 @@
+"""Agent build identity — "the agent IS the manifest."
+
+There is no build file and no lockfile. As the agent constructs itself, the
+SDK observes everything that defines a build: tools registered through
+:func:`define_tool` (name, declared version, effects, auto schema hash,
+source location), prompts registered through :func:`register_prompt`, the
+code ref from CI/env, and the SDK's own version. ``tracing.init(agent=...,
+version=...)`` assembles the canonical manifest, computes the
+content-addressed build hash, stamps ``gateway.build.hash`` on every span,
+and auto-registers the build with Gateway (idempotent on hash — every
+replica of the same code is one build). Releases are label moves on the
+platform, never mutations here.
+
+v1 versioning is developer-declared: you bump ``version`` on the agent and
+on tools; Gateway records schema hashes as evidence alongside.
+
+Mirrors ``@withgateway/sdk``'s ``src/build`` 1:1.
+"""
+
+from __future__ import annotations
+
+import functools
+import hashlib
+import inspect
+import json
+import logging
+import os
+import re
+import threading
+from typing import Any, Callable, Optional, TypeVar
+
+logger = logging.getLogger("gatewaysdk.build")
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_registered_tools: dict[str, dict[str, Any]] = {}
+_registered_prompts: dict[str, str] = {}
+_registered_skills: dict[str, str] = {}
+_registered_artifacts: dict[str, dict[str, Any]] = {}
+_active_build_hash: Optional[str] = None
+
+# Late registration: agents often build tool maps AFTER init. Registered
+# contexts get a debounced re-registration whenever the registry changes —
+# content-addressed and idempotent; traces keep the init-time hash.
+_active_contexts: list[dict[str, Any]] = []
+_reregister_timer: Optional[threading.Timer] = None
+_RE_REGISTER_DEBOUNCE_S = 3.0
+
+
+def _notify_registry_changed() -> None:
+    global _reregister_timer
+    if not _active_contexts:
+        return
+    if _reregister_timer is not None:
+        _reregister_timer.cancel()
+
+    def _rerun() -> None:
+        global _reregister_timer
+        _reregister_timer = None
+        for context in list(_active_contexts):
+            manifest = assemble_manifest(context["agent_id"])
+            build_hash = compute_build_hash(manifest)
+            if build_hash == context.get("last_hash"):
+                continue
+            context["last_hash"] = build_hash
+            _post_build(context, manifest, build_hash)
+
+    _reregister_timer = threading.Timer(_RE_REGISTER_DEBOUNCE_S, _rerun)
+    _reregister_timer.daemon = True
+    _reregister_timer.start()
+
+
+def canonical_json(value: Any) -> str:
+    """Deterministic JSON: keys sorted recursively, arrays kept in order."""
+    # ensure_ascii=False matches JavaScript JSON.stringify (no \uXXXX escapes),
+    # so the SAME agent hashes identically from either SDK.
+    return json.dumps(
+        value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, default=str
+    )
+
+
+def _sha256(text: str) -> str:
+    return "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _capture_source() -> Optional[str]:
+    """First app-code frame ("src/tools/checkout.py:42").
+
+    Skips only the SDK's OWN frames (this module, installed package) — not
+    every path containing "gatewaysdk", or apps developed inside a monorepo
+    next to the SDK would never resolve a source.
+    """
+    for frame_info in inspect.stack()[1:]:
+        filename = frame_info.filename.replace("\\", "/")
+        if filename.endswith("gatewaysdk/build.py"):
+            continue
+        if "site-packages/gatewaysdk/" in filename:
+            continue
+        if filename.startswith("<"):
+            continue
+        parts = filename.split("/")
+        short = "/".join(parts[-4:]) if len(parts) > 4 else filename
+        return f"{short}:{frame_info.lineno}"
+    return None
+
+
+# Ambient environment interception (gatewaysdk.environment, spec §4.4): the
+# environment package installs ONE process-wide interceptor; the define_tool
+# wrapper consults it per call. Returning the sentinel means "not intercepted —
+# run the original function" (the identity path; also taken whenever no
+# interceptor is installed or no world is active).
+_TOOL_INTERCEPT_MISS = object()
+_tool_call_interceptor: Optional[Callable[[str, Callable[..., Any], tuple, dict], Any]] = None
+
+
+def set_tool_call_interceptor(
+    interceptor: Optional[Callable[[str, Callable[..., Any], tuple, dict], Any]],
+) -> None:
+    """Install (or clear, with ``None``) the ambient tool-call interceptor.
+
+    Called by ``gatewaysdk.environment`` — not user-facing. The interceptor
+    receives ``(tool_name, original_fn, args, kwargs)`` and returns either the
+    call's result or :data:`_TOOL_INTERCEPT_MISS` to fall through.
+    """
+    global _tool_call_interceptor
+    _tool_call_interceptor = interceptor
+
+
+def define_tool(
+    name: str,
+    *,
+    version: Optional[str] = None,
+    effects: Optional[str] = None,  # "read" | "write" | "irreversible"
+    schema: Optional[Any] = None,
+    description: Optional[str] = None,
+) -> Callable[[F], F]:
+    """Register a tool's identity; usable as a decorator.
+
+    Example::
+
+        @define_tool("checkout", version="2.1", effects="write",
+                     schema=CHECKOUT_SCHEMA, description="Complete a purchase")
+        def checkout(cart_id: str) -> str: ...
+
+    Or imperatively: ``define_tool("checkout", version="2.1", schema=...)(fn)``.
+
+    The returned callable behaves identically to ``fn`` (``functools.wraps``
+    preserves its attributes) — EXCEPT inside an active mock environment
+    (``with env:`` from ``gatewaysdk.environment``), where calls routed to the
+    env execute against the mock world instead of the original function. This
+    ambient seam is spec §4.4; outside an active world the wrapper is a
+    zero-behavior-change passthrough.
+    """
+    source = _capture_source()
+    identity: dict[str, Any] = {
+        "name": name,
+        "schemaHash": _sha256(
+            canonical_json({"schema": schema, "description": description or ""})
+        ),
+    }
+    if version is not None:
+        identity["version"] = version
+    if effects is not None:
+        identity["effects"] = effects
+    if description is not None:
+        identity["description"] = description[:500]
+    if source is not None:
+        identity["source"] = source
+    _registered_tools[name] = identity
+    _notify_registry_changed()
+
+    def _decorator(fn: F) -> F:
+        @functools.wraps(fn)
+        def _tool_wrapper(*args: Any, **kwargs: Any) -> Any:
+            interceptor = _tool_call_interceptor
+            if interceptor is not None:
+                outcome = interceptor(name, fn, args, kwargs)
+                if outcome is not _TOOL_INTERCEPT_MISS:
+                    return outcome
+            return fn(*args, **kwargs)
+
+        return _tool_wrapper  # type: ignore[return-value]
+
+    return _decorator
+
+
+def register_prompt(
+    name: str, content: str, *, version: Optional[str] = None
+) -> str:
+    """Register a code-shipped prompt so it joins the build identity.
+
+    ``SYSTEM = register_prompt("system", "You are…")`` — returns the content
+    unchanged. Platform-served prompts don't need this; pin them by label.
+    """
+    _registered_prompts[name] = _sha256(content)
+    register_artifact("prompt", name, version=version, content=content)
+    return content
+
+
+def register_artifact(
+    kind: str,
+    name: str,
+    *,
+    version: Optional[str] = None,
+    content: Optional[str] = None,
+    ref: Optional[str] = None,
+    metadata: Optional[dict[str, str]] = None,
+) -> dict[str, Any]:
+    """Version ANY artifact the agent is built from — the generic primitive
+    behind register_prompt/register_skill. ``content`` hashes locally
+    (off-platform); ``ref`` pins a platform-hosted artifact
+    ("prompt/system@label:production")."""
+    source = _capture_source()
+    identity: dict[str, Any] = {"kind": kind, "name": name}
+    if version is not None:
+        identity["version"] = version
+    if content is not None:
+        identity["contentHash"] = _sha256(content)
+    if ref is not None:
+        identity["ref"] = ref
+    if source is not None:
+        identity["source"] = source
+    if metadata:
+        identity["metadata"] = metadata
+    _registered_artifacts[f"{kind}:{name}"] = identity
+    _notify_registry_changed()
+    return identity
+
+
+def get_registered_artifacts() -> list[dict[str, Any]]:
+    return sorted(
+        _registered_artifacts.values(), key=lambda a: (a["kind"], a["name"])
+    )
+
+
+def register_skill(
+    name: str,
+    version: str,
+    *,
+    content: Optional[str] = None,
+    ref: Optional[str] = None,
+) -> None:
+    """Register a skill's identity — ``register_skill("triage", "1.0")`` —
+    so skills are versioned in the build like tools and prompts."""
+    _registered_skills[name] = version
+    register_artifact("skill", name, version=version, content=content, ref=ref)
+
+
+def get_registered_skills() -> dict[str, str]:
+    return dict(sorted(_registered_skills.items()))
+
+
+def get_registered_tools() -> list[dict[str, Any]]:
+    return sorted(_registered_tools.values(), key=lambda t: t["name"])
+
+
+def get_registered_prompts() -> dict[str, str]:
+    return dict(sorted(_registered_prompts.items()))
+
+
+def reset_build_registry() -> None:
+    """Test hook."""
+    global _active_build_hash, _reregister_timer
+    _registered_tools.clear()
+    _registered_prompts.clear()
+    _registered_skills.clear()
+    _registered_artifacts.clear()
+    _active_contexts.clear()
+    if _reregister_timer is not None:
+        _reregister_timer.cancel()
+        _reregister_timer = None
+    _active_build_hash = None
+
+
+def _sdk_version() -> str:
+    try:
+        from importlib.metadata import version
+
+        return f"gatewaysdk=={version('gatewaysdk')}"
+    except Exception:
+        return "gatewaysdk"
+
+
+def _paas_git_context() -> Optional[dict[str, Any]]:
+    """Git context most PaaS runtimes inject automatically (Vercel, Render,
+    Railway, Netlify, Heroku). On those hosts attribution is fully
+    zero-config — no GATEWAY_* or GITHUB_* env plumbing needed. Explicit
+    env vars always win; this only fills gaps."""
+    if os.getenv("VERCEL_GIT_COMMIT_SHA"):
+        # Only surface the repo when it's GitHub-shaped — enrichment is
+        # GitHub-only; a GitLab/Bitbucket repo would just 404 over there.
+        is_github = (os.getenv("VERCEL_GIT_PROVIDER") or "github") == "github"
+        owner = os.getenv("VERCEL_GIT_REPO_OWNER")
+        slug = os.getenv("VERCEL_GIT_REPO_SLUG")
+        return {
+            "provider": "vercel",
+            "sha": os.getenv("VERCEL_GIT_COMMIT_SHA"),
+            "repo": f"{owner}/{slug}" if is_github and owner and slug else None,
+            "branch": os.getenv("VERCEL_GIT_COMMIT_REF"),
+            "login": os.getenv("VERCEL_GIT_COMMIT_AUTHOR_LOGIN"),
+        }
+    if os.getenv("RENDER_GIT_COMMIT"):
+        return {
+            "provider": "render",
+            "sha": os.getenv("RENDER_GIT_COMMIT"),
+            "repo": os.getenv("RENDER_GIT_REPO_SLUG"),  # already "owner/repo"
+            "branch": os.getenv("RENDER_GIT_BRANCH"),
+        }
+    if os.getenv("RAILWAY_GIT_COMMIT_SHA"):
+        owner = os.getenv("RAILWAY_GIT_REPO_OWNER")
+        name = os.getenv("RAILWAY_GIT_REPO_NAME")
+        return {
+            "provider": "railway",
+            "sha": os.getenv("RAILWAY_GIT_COMMIT_SHA"),
+            "repo": f"{owner}/{name}" if owner and name else None,
+            "branch": os.getenv("RAILWAY_GIT_BRANCH"),
+            "login": os.getenv("RAILWAY_GIT_AUTHOR"),
+        }
+    if os.getenv("NETLIFY") and os.getenv("COMMIT_REF"):
+        repo_match = re.search(
+            r"github\.com[/:]([^/]+/[^/.]+)", os.getenv("REPOSITORY_URL") or ""
+        )
+        return {
+            "provider": "netlify",
+            "sha": os.getenv("COMMIT_REF"),
+            "repo": repo_match.group(1) if repo_match else None,
+            "branch": os.getenv("BRANCH"),
+        }
+    # Heroku (dyno metadata) and common bare conventions: sha only — the
+    # platform resolves the repo server-side via the GitHub connection.
+    heroku_sha = os.getenv("HEROKU_SLUG_COMMIT") or os.getenv("SOURCE_VERSION")
+    bare_sha = heroku_sha or os.getenv("GIT_COMMIT") or os.getenv("COMMIT_SHA")
+    if bare_sha:
+        return {"provider": "heroku" if heroku_sha else "generic", "sha": bare_sha}
+    return None
+
+
+def _code_ref() -> Optional[str]:
+    paas = _paas_git_context() or {}
+    sha = (
+        os.getenv("GATEWAY_COMMIT")
+        or os.getenv("GITHUB_SHA")
+        or os.getenv("CI_COMMIT_SHA")  # GitLab
+        or os.getenv("CIRCLE_SHA1")
+        or paas.get("sha")
+    )
+    if not sha:
+        return None
+    repo = (
+        os.getenv("GITHUB_REPOSITORY")
+        or os.getenv("CI_PROJECT_PATH")
+        or paas.get("repo")
+    )
+    return f"git:{repo}@{sha}" if repo else f"git:{sha}"
+
+
+def assemble_manifest(agent_id: str) -> dict[str, Any]:
+    manifest: dict[str, Any] = {
+        "agentId": agent_id,
+        "sdk": _sdk_version(),
+        "tools": get_registered_tools(),
+        "prompts": get_registered_prompts(),
+        "skills": get_registered_skills(),
+        "artifacts": get_registered_artifacts(),
+    }
+    code_ref = _code_ref()
+    if code_ref:
+        manifest["codeRef"] = code_ref
+    return manifest
+
+
+def compute_build_hash(manifest: dict[str, Any]) -> str:
+    """Content-addressed identity. Source locations are display metadata, not
+    identity — the same tool declared on a different line is the same tool."""
+    identity = dict(manifest)
+    identity["tools"] = [
+        {k: v for k, v in tool.items() if k != "source"}
+        for tool in manifest.get("tools", [])
+    ]
+    identity["artifacts"] = [
+        {k: v for k, v in artifact.items() if k != "source"}
+        for artifact in manifest.get("artifacts", [])
+    ]
+    return _sha256(canonical_json(identity))
+
+
+def get_active_build_hash() -> Optional[str]:
+    return _active_build_hash
+
+
+def _attribution_from_env() -> dict[str, Any]:
+    attribution: dict[str, Any] = {"source": "runtime"}
+    if os.getenv("GITHUB_ACTIONS"):
+        attribution["source"] = "ci"
+    if os.getenv("GITHUB_ACTOR"):
+        attribution["githubLogin"] = os.getenv("GITHUB_ACTOR")
+    sha = os.getenv("GATEWAY_COMMIT") or os.getenv("GITHUB_SHA")
+    if sha:
+        attribution["commitSha"] = sha
+    if os.getenv("GITHUB_REPOSITORY"):
+        attribution["repo"] = os.getenv("GITHUB_REPOSITORY")
+    branch = os.getenv("GITHUB_HEAD_REF") or os.getenv("GITHUB_REF_NAME")
+    if branch:
+        attribution["branch"] = branch
+    # PaaS-injected git context (Vercel/Render/Railway/Netlify/Heroku) fills
+    # any gaps — zero-config attribution on those hosts. Explicit env wins.
+    paas = _paas_git_context()
+    if paas:
+        if attribution["source"] == "runtime":
+            attribution["source"] = f"paas:{paas['provider']}"
+        if not attribution.get("commitSha") and paas.get("sha"):
+            attribution["commitSha"] = paas["sha"]
+        if not attribution.get("repo") and paas.get("repo"):
+            attribution["repo"] = paas["repo"]
+        if not attribution.get("branch") and paas.get("branch"):
+            attribution["branch"] = paas["branch"]
+        if not attribution.get("githubLogin") and paas.get("login"):
+            attribution["githubLogin"] = paas["login"]
+    pr_match = re.search(r"refs/pull/(\d+)/", os.getenv("GITHUB_REF") or "")
+    if pr_match:
+        attribution["prNumber"] = int(pr_match.group(1))
+    # PR title/body are NOT in the default Actions env — workflows pass them
+    # through: GATEWAY_PR_TITLE/GATEWAY_PR_BODY from github.event.pull_request.
+    if os.getenv("GATEWAY_PR_TITLE"):
+        attribution["prTitle"] = (os.getenv("GATEWAY_PR_TITLE") or "")[:300]
+    if os.getenv("GATEWAY_PR_BODY"):
+        attribution["prDescription"] = (os.getenv("GATEWAY_PR_BODY") or "")[:2000]
+    if attribution.get("repo") and attribution.get("prNumber") and "prUrl" not in attribution:
+        attribution["prUrl"] = (
+            f"https://github.com/{attribution['repo']}/pull/{attribution['prNumber']}"
+        )
+    return attribution
+
+
+def activate_build(
+    agent_id: str,
+    *,
+    version: Optional[str] = None,
+    host: Optional[str] = None,
+    public_key: Optional[str] = None,
+    secret_key: Optional[str] = None,
+    register: bool = True,
+) -> str:
+    """Assemble + hash the manifest, mark it active (spans stamp it), and
+    fire-and-forget registration with Gateway. Returns the build hash."""
+    global _active_build_hash
+    manifest = assemble_manifest(agent_id)
+    build_hash = compute_build_hash(manifest)
+    _active_build_hash = build_hash
+    logger.debug(
+        "Agent build identity: %s @ %s (%d tools, %d prompts)",
+        agent_id,
+        build_hash[:15],
+        len(manifest["tools"]),
+        len(manifest["prompts"]),
+    )
+
+    resolved_host = host or os.getenv("GATEWAY_HOST")
+    resolved_public = public_key or os.getenv("GATEWAY_PUBLIC_KEY")
+    resolved_secret = secret_key or os.getenv("GATEWAY_SECRET_KEY")
+    if not register or not (resolved_host and resolved_public and resolved_secret):
+        return build_hash
+
+    context = {
+        "host": resolved_host,
+        "public_key": resolved_public,
+        "secret_key": resolved_secret,
+        "agent_id": agent_id,
+        "version": version,
+        "last_hash": build_hash,
+    }
+    # Track so tools/prompts/skills registered AFTER init re-register the
+    # fullest manifest (debounced, content-addressed, idempotent).
+    _active_contexts.append(context)
+    _post_build(context, manifest, build_hash)
+    return build_hash
+
+
+def _post_build(
+    context: dict[str, Any], manifest: dict[str, Any], build_hash: str
+) -> None:
+    """Fire-and-forget POST of one build registration (daemon thread)."""
+
+    def _register() -> None:
+        import base64
+        from urllib import request as urllib_request
+
+        payload = {
+            "agentId": context["agent_id"],
+            "buildHash": build_hash,
+            "manifest": manifest,
+            "attribution": _attribution_from_env(),
+        }
+        if context.get("version"):
+            payload["semanticVer"] = context["version"]
+        try:
+            req = urllib_request.Request(
+                f"{str(context['host']).rstrip('/')}/api/public/agent-builds",
+                data=json.dumps(payload).encode("utf-8"),
+                headers={
+                    "Authorization": "Basic "
+                    + base64.b64encode(
+                        f"{context['public_key']}:{context['secret_key']}".encode()
+                    ).decode(),
+                    "Content-Type": "application/json",
+                },
+                method="POST",
+            )
+            with urllib_request.urlopen(req, timeout=15):
+                pass
+            logger.debug("Registered agent build %s", build_hash[:15])
+        except Exception as exc:  # noqa: BLE001 — fail-soft by design
+            logger.debug("Build registration failed (agent keeps running): %s", exc)
+
+    threading.Thread(target=_register, name="gateway-build-register", daemon=True).start()

gatewaysdk/cli/__init__.py

@@ -0,0 +1,58 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""GatewaySDK command line interface entry point."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import sys
+from typing import Dict, Iterable, Tuple
+
+_SUBCOMMANDS: Dict[str, Tuple[str, str]] = {
+    "vllm": ("gatewaysdk.cli.vllm", "Run the vLLM CLI with GatewaySDK instrumentation."),
+    "store": ("gatewaysdk.cli.store", "Run a LightningStore server."),
+    "prometheus": ("gatewaysdk.cli.prometheus", "Serve Prometheus metrics from the multiprocess registry."),
+    # "agentops" was removed: it dispatched to gatewaysdk.cli.agentops_server,
+    # a module that never existed, so the subcommand always crashed with
+    # ModuleNotFoundError. tests/test_cli_dispatch.py guards against repeats.
+}
+
+_DESCRIPTION = "GatewaySDK CLI entry point.\n\nAvailable subcommands:\n" + "\n".join(
+    f"  {name:<10}{desc}" for name, (_, desc) in _SUBCOMMANDS.items()
+)
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    """Dispatch to the requested GatewaySDK subcommand."""
+    parser = argparse.ArgumentParser(
+        prog="msk",
+        description=_DESCRIPTION,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("subcommand", choices=_SUBCOMMANDS.keys(), help="Subcommand to run.")
+    parser.add_argument("args", nargs=argparse.REMAINDER, help=argparse.SUPPRESS)
+
+    parsed = parser.parse_args(list(argv) if argv is not None else None)
+    module_name, _ = _SUBCOMMANDS[parsed.subcommand]
+    module = importlib.import_module(module_name)
+
+    entry_point = getattr(module, "main", None)
+    if entry_point is None:
+        parser.error(f"Subcommand '{parsed.subcommand}' does not define a callable 'main'")
+
+    dispatch_args = parsed.args
+    original_argv = sys.argv
+    sys.argv = [f"{parser.prog} {parsed.subcommand}", *dispatch_args]
+    try:
+        result = entry_point(dispatch_args or None)
+    finally:
+        sys.argv = original_argv
+
+    if isinstance(result, int):
+        return result
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())