google-adk-surface 0.1.0__py3-none-any.whl

google_adk_surface/__init__.py

@@ -0,0 +1,15 @@
+"""Surface for Google ADK: the link-safety layer between an AI agent and the open web."""
+from google.adk.tools import FunctionTool
+from ._core import preflight, preflight_text, TOOL_DESCRIPTION
+
+def surface_preflight(url: str) -> str:
+    """Check a link before you open it. Unwraps short links, follows redirects, and answers fetch or skip plus where the link really goes.
+
+    Args:
+        url: The link to check.
+    """
+    return preflight_text(url, ua="google-adk-surface/0.1.0")
+
+surface_preflight_tool = FunctionTool(surface_preflight)
+
+__all__ = ["surface_preflight", "surface_preflight_tool", "preflight", "preflight_text", "TOOL_DESCRIPTION"]

google_adk_surface/_core.py

@@ -0,0 +1,48 @@
+"""Surface Preflight client: the link-safety layer between an AI agent and the open web."""
+from __future__ import annotations
+import json, os, urllib.parse, urllib.request
+from typing import Any, Dict, Optional
+
+DEFAULT_BASE_URL = "https://nova-otter-delta-cloud.grok.me"
+TOOL_NAME = "surface_preflight"
+TOOL_DESCRIPTION = (
+    "Check a link before you open it. Surface unwraps short links (t.co, bit.ly, "
+    "lnkd.in, youtu.be), follows redirects, and tells you whether the destination "
+    "is worth fetching ('fetch') or should be skipped ('skip'), plus where the "
+    "link really goes. It never returns the page itself."
+)
+
+def preflight(url: str, api_key: Optional[str] = None, base_url: Optional[str] = None,
+              timeout: float = 15.0, headers: Optional[Dict[str, str]] = None, ua: str = "surface-python/0.1.0") -> Dict[str, Any]:
+    """Call Surface Preflight and return a compact verdict dict."""
+    base = (base_url or os.environ.get("SURFACE_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+    key = api_key or os.environ.get("SURFACE_API_KEY")
+    h = {"Content-Type": "application/json", "Accept": "application/json",
+         "User-Agent": ua}
+    if key:
+        h["Authorization"] = "Bearer " + key
+    if headers:
+        h.update(headers)
+    req = urllib.request.Request(base + "/v1/preflight", data=json.dumps({"url": url}).encode(),
+                                 headers=h, method="POST")
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        data = json.loads(r.read().decode())
+    nxt = data.get("next") or data.get("verdict")
+    return {
+        "next": nxt,
+        "fetch": nxt == "fetch",
+        "url": data.get("url", url),
+        "final_url": data.get("final_url"),
+        "final_host": data.get("final_host"),
+        "status": data.get("status"),
+        "redirects": data.get("redirects"),
+        "shortener": data.get("shortener"),
+        "reason": data.get("reason"),
+    }
+
+def preflight_text(url: str, **kw: Any) -> str:
+    """Same as preflight() but returns a JSON string, handy for LLM tool output."""
+    try:
+        return json.dumps(preflight(url, **kw))
+    except Exception as e:  # tool output should never crash the agent loop
+        return json.dumps({"next": "skip", "fetch": False, "url": url, "error": str(e)})

google_adk_surface-0.1.0.dist-info/METADATA

@@ -0,0 +1,51 @@
+Metadata-Version: 2.5
+Name: google-adk-surface
+Version: 0.1.0
+Summary: Surface for Google ADK: the link-safety layer between an AI agent and the open web. One tool, surface_preflight, that tells your agent whether a link is worth fetching.
+Project-URL: Homepage, https://otter-sand-wolf-spring.grok.me
+Project-URL: Documentation, https://nova-otter-delta-cloud.grok.me/docs
+Project-URL: API reference, https://nova-otter-delta-cloud.grok.me/llms.txt
+Project-URL: MCP server, https://nova-otter-delta-cloud.grok.me/mcp
+Author-email: Canada Site Ops <canada.site.ops@gmail.com>
+Maintainer-email: Canada Site Ops <canada.site.ops@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: adk,ai-agents,gemini,google-adk,link-safety,mcp,preflight,surface,tools,url
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: google-adk>=1.0
+Description-Content-Type: text/markdown
+
+# google-adk-surface
+
+Surface is the link-safety layer between an AI agent and the open web. One tool, `surface_preflight`: give it a URL, get `fetch` or `skip` plus where the link really goes (unwraps t.co, bit.ly, redirects).
+
+```python
+from google.adk.agents import Agent
+from google_adk_surface import surface_preflight
+
+agent = Agent(name="web", model="gemini-2.0-flash", tools=[surface_preflight])
+```
+
+## Free to start
+
+The first 1M requests a month are free. It works with no key at all (shared demo limit), or grab your own free key in one call, with no email and no card:
+
+```bash
+curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
+export SURFACE_API_KEY=...
+```
+
+After the free tier: $0.25 USD per 1,000 preflights.
+
+## Prefer MCP?
+
+Point any MCP client at `https://nova-otter-delta-cloud.grok.me/mcp` (tool `preflight_url`).
+
+- Website: https://otter-sand-wolf-spring.grok.me
+- Docs: https://nova-otter-delta-cloud.grok.me/docs
+- LLM reference: https://nova-otter-delta-cloud.grok.me/llms.txt
+
+Made by Canada Site Ops. MIT licensed.

google_adk_surface-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+google_adk_surface/__init__.py,sha256=Nwq3EiTq65oQc4YgOuB0oX7nS-YhtgwD00GYsuuN4Fc,656
+google_adk_surface/_core.py,sha256=qatbSQobIepBZit1YIbTIgb01gXRe-STlwVWohtjJ3Q,2300
+google_adk_surface-0.1.0.dist-info/METADATA,sha256=85JL7-5Db7QQYHzOsDnn_GHLJoEMuQItzT3P9zedTiw,2053
+google_adk_surface-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+google_adk_surface-0.1.0.dist-info/licenses/LICENSE,sha256=fNLwqKpxzMvMZQTP1NQeJcBxAGsliU7T10uGRDcQeNo,675
+google_adk_surface-0.1.0.dist-info/RECORD,,

google_adk_surface-0.1.0.dist-info/WHEEL

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

google_adk_surface-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Canada Site Ops
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.