crewai-surface 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,9 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Canada Site Ops
4
+
5
+ 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:
6
+
7
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
@@ -0,0 +1,66 @@
1
+ Metadata-Version: 2.5
2
+ Name: crewai-surface
3
+ Version: 0.1.0
4
+ Summary: Surface for crewai: 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.
5
+ Project-URL: Homepage, https://otter-sand-wolf-spring.grok.me
6
+ Project-URL: Documentation, https://nova-otter-delta-cloud.grok.me/docs
7
+ Project-URL: API reference, https://nova-otter-delta-cloud.grok.me/llms.txt
8
+ Project-URL: MCP server, https://nova-otter-delta-cloud.grok.me/mcp
9
+ Author-email: Canada Site Ops <canada.site.ops@gmail.com>
10
+ Maintainer-email: Canada Site Ops <canada.site.ops@gmail.com>
11
+ License: MIT
12
+ License-File: LICENSE
13
+ Keywords: ai-agents,crewai,link-safety,mcp,preflight,surface,tools,url
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Topic :: Internet :: WWW/HTTP
17
+ Requires-Python: >=3.9
18
+ Requires-Dist: crewai>=0.80
19
+ Description-Content-Type: text/markdown
20
+
21
+ # crewai-surface
22
+
23
+ **Surface is the link-safety layer between an AI agent and the open web.** Before your agent opens a link someone pasted, Surface checks it: it unwraps short links (t.co, bit.ly, lnkd.in, youtu.be), follows the redirects, and answers **fetch** or **skip**, along with where the link really goes. It never downloads the page for you, so it's fast and cheap.
24
+
25
+ This package gives crewai agents that check as one ready-made tool: `surface_preflight`.
26
+
27
+ ```bash
28
+ pip install crewai-surface
29
+ ```
30
+
31
+ ```python
32
+ from crewai import Agent
33
+ from crewai_surface import surface_preflight
34
+
35
+ researcher = Agent(role="Researcher", goal="...", backstory="...", tools=[surface_preflight])
36
+ ```
37
+
38
+ The tool returns:
39
+
40
+ ```json
41
+ {"next": "fetch", "fetch": true, "url": "https://youtu.be/jNQXAC9IVRw",
42
+ "final_url": "https://www.youtube.com/watch?v=jNQXAC9IVRw&feature=youtu.be",
43
+ "final_host": "youtube.com", "status": 200, "redirects": 1, "shortener": true,
44
+ "reason": "unwrapped youtu.be → youtube.com · alive, worth a fetch"}
45
+ ```
46
+
47
+ ## Free to start
48
+
49
+ 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:
50
+
51
+ ```bash
52
+ curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
53
+ export SURFACE_API_KEY=...
54
+ ```
55
+
56
+ After the free tier: $0.25 USD per 1,000 preflights.
57
+
58
+ ## Prefer MCP?
59
+
60
+ Point any MCP client at `https://nova-otter-delta-cloud.grok.me/mcp` (tool `preflight_url`).
61
+
62
+ - Website: https://otter-sand-wolf-spring.grok.me
63
+ - Docs: https://nova-otter-delta-cloud.grok.me/docs
64
+ - LLM reference: https://nova-otter-delta-cloud.grok.me/llms.txt
65
+
66
+ Made by Canada Site Ops. MIT licensed.
@@ -0,0 +1,46 @@
1
+ # crewai-surface
2
+
3
+ **Surface is the link-safety layer between an AI agent and the open web.** Before your agent opens a link someone pasted, Surface checks it: it unwraps short links (t.co, bit.ly, lnkd.in, youtu.be), follows the redirects, and answers **fetch** or **skip**, along with where the link really goes. It never downloads the page for you, so it's fast and cheap.
4
+
5
+ This package gives crewai agents that check as one ready-made tool: `surface_preflight`.
6
+
7
+ ```bash
8
+ pip install crewai-surface
9
+ ```
10
+
11
+ ```python
12
+ from crewai import Agent
13
+ from crewai_surface import surface_preflight
14
+
15
+ researcher = Agent(role="Researcher", goal="...", backstory="...", tools=[surface_preflight])
16
+ ```
17
+
18
+ The tool returns:
19
+
20
+ ```json
21
+ {"next": "fetch", "fetch": true, "url": "https://youtu.be/jNQXAC9IVRw",
22
+ "final_url": "https://www.youtube.com/watch?v=jNQXAC9IVRw&feature=youtu.be",
23
+ "final_host": "youtube.com", "status": 200, "redirects": 1, "shortener": true,
24
+ "reason": "unwrapped youtu.be → youtube.com · alive, worth a fetch"}
25
+ ```
26
+
27
+ ## Free to start
28
+
29
+ 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:
30
+
31
+ ```bash
32
+ curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
33
+ export SURFACE_API_KEY=...
34
+ ```
35
+
36
+ After the free tier: $0.25 USD per 1,000 preflights.
37
+
38
+ ## Prefer MCP?
39
+
40
+ Point any MCP client at `https://nova-otter-delta-cloud.grok.me/mcp` (tool `preflight_url`).
41
+
42
+ - Website: https://otter-sand-wolf-spring.grok.me
43
+ - Docs: https://nova-otter-delta-cloud.grok.me/docs
44
+ - LLM reference: https://nova-otter-delta-cloud.grok.me/llms.txt
45
+
46
+ Made by Canada Site Ops. MIT licensed.
@@ -0,0 +1,25 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "crewai-surface"
7
+ version = "0.1.0"
8
+ description = "Surface for crewai: 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."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = {text = "MIT"}
12
+ authors = [{name = "Canada Site Ops", email = "canada.site.ops@gmail.com"}]
13
+ maintainers = [{name = "Canada Site Ops", email = "canada.site.ops@gmail.com"}]
14
+ keywords = ["ai-agents","crewai","link-safety","url","preflight","mcp","surface","tools"]
15
+ dependencies = ["crewai>=0.80"]
16
+ classifiers = ["Programming Language :: Python :: 3","License :: OSI Approved :: MIT License","Topic :: Internet :: WWW/HTTP"]
17
+
18
+ [project.urls]
19
+ Homepage = "https://otter-sand-wolf-spring.grok.me"
20
+ Documentation = "https://nova-otter-delta-cloud.grok.me/docs"
21
+ "API reference" = "https://nova-otter-delta-cloud.grok.me/llms.txt"
22
+ "MCP server" = "https://nova-otter-delta-cloud.grok.me/mcp"
23
+
24
+ [tool.hatch.build.targets.wheel]
25
+ packages = ["src/crewai_surface"]
@@ -0,0 +1,10 @@
1
+ """Surface for crewai: the link-safety layer between an AI agent and the open web."""
2
+ from crewai.tools import tool as _tool
3
+ from ._core import preflight, preflight_text, TOOL_DESCRIPTION
4
+
5
+ @_tool("surface_preflight")
6
+ def surface_preflight(url: str) -> str:
7
+ """Check a link before opening it. Surface unwraps short links, follows redirects and answers fetch or skip with the real destination. It never returns the page."""
8
+ return preflight_text(url)
9
+
10
+ __all__ = ["surface_preflight", "preflight"]
@@ -0,0 +1,48 @@
1
+ """Surface Preflight client: the link-safety layer between an AI agent and the open web."""
2
+ from __future__ import annotations
3
+ import json, os, urllib.parse, urllib.request
4
+ from typing import Any, Dict, Optional
5
+
6
+ DEFAULT_BASE_URL = "https://nova-otter-delta-cloud.grok.me"
7
+ TOOL_NAME = "surface_preflight"
8
+ TOOL_DESCRIPTION = (
9
+ "Check a link before you open it. Surface unwraps short links (t.co, bit.ly, "
10
+ "lnkd.in, youtu.be), follows redirects, and tells you whether the destination "
11
+ "is worth fetching ('fetch') or should be skipped ('skip'), plus where the "
12
+ "link really goes. It never returns the page itself."
13
+ )
14
+
15
+ def preflight(url: str, api_key: Optional[str] = None, base_url: Optional[str] = None,
16
+ timeout: float = 15.0, headers: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
17
+ """Call Surface Preflight and return a compact verdict dict."""
18
+ base = (base_url or os.environ.get("SURFACE_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
19
+ key = api_key or os.environ.get("SURFACE_API_KEY")
20
+ h = {"Content-Type": "application/json", "Accept": "application/json",
21
+ "User-Agent": "crewai-surface/0.1.0"}
22
+ if key:
23
+ h["Authorization"] = "Bearer " + key
24
+ if headers:
25
+ h.update(headers)
26
+ req = urllib.request.Request(base + "/v1/preflight", data=json.dumps({"url": url}).encode(),
27
+ headers=h, method="POST")
28
+ with urllib.request.urlopen(req, timeout=timeout) as r:
29
+ data = json.loads(r.read().decode())
30
+ nxt = data.get("next") or data.get("verdict")
31
+ return {
32
+ "next": nxt,
33
+ "fetch": nxt == "fetch",
34
+ "url": data.get("url", url),
35
+ "final_url": data.get("final_url"),
36
+ "final_host": data.get("final_host"),
37
+ "status": data.get("status"),
38
+ "redirects": data.get("redirects"),
39
+ "shortener": data.get("shortener"),
40
+ "reason": data.get("reason"),
41
+ }
42
+
43
+ def preflight_text(url: str, **kw: Any) -> str:
44
+ """Same as preflight() but returns a JSON string, handy for LLM tool output."""
45
+ try:
46
+ return json.dumps(preflight(url, **kw))
47
+ except Exception as e: # tool output should never crash the agent loop
48
+ return json.dumps({"next": "skip", "fetch": False, "url": url, "error": str(e)})