surface-haystack 0.1.0__tar.gz → 0.1.1__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.
- surface_haystack-0.1.1/PKG-INFO +83 -0
- surface_haystack-0.1.1/README.md +63 -0
- {surface_haystack-0.1.0 → surface_haystack-0.1.1}/pyproject.toml +2 -2
- {surface_haystack-0.1.0 → surface_haystack-0.1.1}/src/surface_haystack/__init__.py +2 -2
- {surface_haystack-0.1.0 → surface_haystack-0.1.1}/src/surface_haystack/_core.py +1 -1
- surface_haystack-0.1.0/PKG-INFO +0 -57
- surface_haystack-0.1.0/README.md +0 -37
- {surface_haystack-0.1.0 → surface_haystack-0.1.1}/LICENSE +0 -0
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: surface-haystack
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Surface for Haystack: 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://nova-otter-delta-cloud.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,haystack,haystack-ai,haystack-component,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.10
|
|
18
|
+
Requires-Dist: haystack-ai>=2.0
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
|
|
21
|
+
# surface-haystack
|
|
22
|
+
|
|
23
|
+
Surface checks a short link before your agent opens it. The answer is fetch or skip. It never returns the page. A hop or a 1×1 pixel counts the same way, with no install. Free for the first million requests a month. https://nova-otter-delta-cloud.grok.me
|
|
24
|
+
|
|
25
|
+
This package gives Haystack agents that check as one ready-made tool: `surface_preflight` / `SurfacePreflight`.
|
|
26
|
+
|
|
27
|
+
Surface by Canada Site Ops. Ontario, Canada.
|
|
28
|
+
|
|
29
|
+
## Get a free API key in about 10 seconds
|
|
30
|
+
|
|
31
|
+
No email, no card. Then set `SURFACE_API_KEY`. The tool sends it as `Authorization: Bearer <key>`.
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
|
|
35
|
+
# returns {"key","created_at","free_monthly":1000000,"usage_url"}
|
|
36
|
+
export SURFACE_API_KEY=... # paste the key value
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
A key gets its own million free requests a month. The tool also runs without a key on a shared demo limit.
|
|
40
|
+
|
|
41
|
+
## Install
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
pip install surface-haystack
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
from surface_haystack import SurfacePreflight, surface_preflight
|
|
49
|
+
|
|
50
|
+
print(SurfacePreflight().run(url="https://youtu.be/jNQXAC9IVRw"))
|
|
51
|
+
# or give the Tool to a Haystack Agent / ToolInvoker: tools=[surface_preflight]
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
The tool returns `next: fetch` or `next: skip`, plus where the link really goes (unwraps t.co, bit.ly, lnkd.in, youtu.be). It never downloads the page. On any error it answers `skip`.
|
|
55
|
+
|
|
56
|
+
## Prefer MCP?
|
|
57
|
+
|
|
58
|
+
Mint a key first, then paste this into your MCP settings (tool `preflight_url`):
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"mcpServers": {
|
|
63
|
+
"surface": {
|
|
64
|
+
"type": "http",
|
|
65
|
+
"url": "https://nova-otter-delta-cloud.grok.me/mcp",
|
|
66
|
+
"headers": {
|
|
67
|
+
"Authorization": "Bearer REPLACE_WITH_YOUR_KEY"
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Also listed
|
|
75
|
+
|
|
76
|
+
- Official MCP Registry: `me.grok.nova-otter-delta-cloud/surface`
|
|
77
|
+
- https://www.curatedmcp.com/marketplace/surface
|
|
78
|
+
- https://www.npmjs.com/package/@surfaceapi/surface
|
|
79
|
+
- https://pypi.org/project/surface-haystack/
|
|
80
|
+
- https://pypi.org/project/surfaceapi/
|
|
81
|
+
- https://huggingface.co/spaces/surfaceapi/surface-preflight
|
|
82
|
+
|
|
83
|
+
CLI and GitHub Action are coming soon.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# surface-haystack
|
|
2
|
+
|
|
3
|
+
Surface checks a short link before your agent opens it. The answer is fetch or skip. It never returns the page. A hop or a 1×1 pixel counts the same way, with no install. Free for the first million requests a month. https://nova-otter-delta-cloud.grok.me
|
|
4
|
+
|
|
5
|
+
This package gives Haystack agents that check as one ready-made tool: `surface_preflight` / `SurfacePreflight`.
|
|
6
|
+
|
|
7
|
+
Surface by Canada Site Ops. Ontario, Canada.
|
|
8
|
+
|
|
9
|
+
## Get a free API key in about 10 seconds
|
|
10
|
+
|
|
11
|
+
No email, no card. Then set `SURFACE_API_KEY`. The tool sends it as `Authorization: Bearer <key>`.
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
|
|
15
|
+
# returns {"key","created_at","free_monthly":1000000,"usage_url"}
|
|
16
|
+
export SURFACE_API_KEY=... # paste the key value
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
A key gets its own million free requests a month. The tool also runs without a key on a shared demo limit.
|
|
20
|
+
|
|
21
|
+
## Install
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pip install surface-haystack
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
from surface_haystack import SurfacePreflight, surface_preflight
|
|
29
|
+
|
|
30
|
+
print(SurfacePreflight().run(url="https://youtu.be/jNQXAC9IVRw"))
|
|
31
|
+
# or give the Tool to a Haystack Agent / ToolInvoker: tools=[surface_preflight]
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The tool returns `next: fetch` or `next: skip`, plus where the link really goes (unwraps t.co, bit.ly, lnkd.in, youtu.be). It never downloads the page. On any error it answers `skip`.
|
|
35
|
+
|
|
36
|
+
## Prefer MCP?
|
|
37
|
+
|
|
38
|
+
Mint a key first, then paste this into your MCP settings (tool `preflight_url`):
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"mcpServers": {
|
|
43
|
+
"surface": {
|
|
44
|
+
"type": "http",
|
|
45
|
+
"url": "https://nova-otter-delta-cloud.grok.me/mcp",
|
|
46
|
+
"headers": {
|
|
47
|
+
"Authorization": "Bearer REPLACE_WITH_YOUR_KEY"
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Also listed
|
|
55
|
+
|
|
56
|
+
- Official MCP Registry: `me.grok.nova-otter-delta-cloud/surface`
|
|
57
|
+
- https://www.curatedmcp.com/marketplace/surface
|
|
58
|
+
- https://www.npmjs.com/package/@surfaceapi/surface
|
|
59
|
+
- https://pypi.org/project/surface-haystack/
|
|
60
|
+
- https://pypi.org/project/surfaceapi/
|
|
61
|
+
- https://huggingface.co/spaces/surfaceapi/surface-preflight
|
|
62
|
+
|
|
63
|
+
CLI and GitHub Action are coming soon.
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "surface-haystack"
|
|
7
|
-
version = "0.1.
|
|
7
|
+
version = "0.1.1"
|
|
8
8
|
description = "Surface for Haystack: 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
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.10"
|
|
@@ -16,7 +16,7 @@ dependencies = ["haystack-ai>=2.0"]
|
|
|
16
16
|
classifiers = ["Programming Language :: Python :: 3","License :: OSI Approved :: MIT License","Topic :: Internet :: WWW/HTTP"]
|
|
17
17
|
|
|
18
18
|
[project.urls]
|
|
19
|
-
Homepage = "https://otter-
|
|
19
|
+
Homepage = "https://nova-otter-delta-cloud.grok.me"
|
|
20
20
|
Documentation = "https://nova-otter-delta-cloud.grok.me/docs"
|
|
21
21
|
"API reference" = "https://nova-otter-delta-cloud.grok.me/llms.txt"
|
|
22
22
|
"MCP server" = "https://nova-otter-delta-cloud.grok.me/mcp"
|
|
@@ -10,14 +10,14 @@ class SurfacePreflight:
|
|
|
10
10
|
@component.output_types(next=str, fetch=bool, final_url=str, reason=str, result=dict)
|
|
11
11
|
def run(self, url: str) -> Dict[str, Any]:
|
|
12
12
|
try:
|
|
13
|
-
r = preflight(url, ua="surface-haystack/0.1.
|
|
13
|
+
r = preflight(url, ua="surface-haystack/0.1.1")
|
|
14
14
|
except Exception as e:
|
|
15
15
|
r = {"next": "skip", "fetch": False, "url": url, "final_url": None, "reason": str(e)}
|
|
16
16
|
return {"next": r["next"], "fetch": bool(r["fetch"]), "final_url": r.get("final_url") or "",
|
|
17
17
|
"reason": r.get("reason") or "", "result": r}
|
|
18
18
|
|
|
19
19
|
def _fn(url: str) -> str:
|
|
20
|
-
return preflight_text(url, ua="surface-haystack/0.1.
|
|
20
|
+
return preflight_text(url, ua="surface-haystack/0.1.1")
|
|
21
21
|
|
|
22
22
|
surface_preflight = Tool(name="surface_preflight", description=TOOL_DESCRIPTION,
|
|
23
23
|
parameters={"type": "object", "properties": {"url": {"type": "string", "description": "The link to check"}}, "required": ["url"]},
|
|
@@ -13,7 +13,7 @@ TOOL_DESCRIPTION = (
|
|
|
13
13
|
)
|
|
14
14
|
|
|
15
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, ua: str = "surface-python/0.1.
|
|
16
|
+
timeout: float = 15.0, headers: Optional[Dict[str, str]] = None, ua: str = "surface-python/0.1.1") -> Dict[str, Any]:
|
|
17
17
|
"""Call Surface Preflight and return a compact verdict dict."""
|
|
18
18
|
base = (base_url or os.environ.get("SURFACE_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
|
|
19
19
|
key = api_key or os.environ.get("SURFACE_API_KEY")
|
surface_haystack-0.1.0/PKG-INFO
DELETED
|
@@ -1,57 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.5
|
|
2
|
-
Name: surface-haystack
|
|
3
|
-
Version: 0.1.0
|
|
4
|
-
Summary: Surface for Haystack: 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,haystack,haystack-ai,haystack-component,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.10
|
|
18
|
-
Requires-Dist: haystack-ai>=2.0
|
|
19
|
-
Description-Content-Type: text/markdown
|
|
20
|
-
|
|
21
|
-
# surface-haystack
|
|
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. If Surface can't be reached, the tool answers skip, so your agent stays safe.
|
|
24
|
-
|
|
25
|
-
This package gives Haystack agents that check as one ready-made tool: `surface_preflight`.
|
|
26
|
-
|
|
27
|
-
```bash
|
|
28
|
-
pip install surface-haystack
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
```python
|
|
32
|
-
from surface_haystack import SurfacePreflight, surface_preflight
|
|
33
|
-
|
|
34
|
-
print(SurfacePreflight().run(url="https://youtu.be/jNQXAC9IVRw"))
|
|
35
|
-
# or give the Tool to a Haystack Agent / ToolInvoker: tools=[surface_preflight]
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
## Free to start
|
|
39
|
-
|
|
40
|
-
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:
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
|
|
44
|
-
export SURFACE_API_KEY=...
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
After the free tier: $0.25 USD per 1,000 preflights.
|
|
48
|
-
|
|
49
|
-
## Prefer MCP?
|
|
50
|
-
|
|
51
|
-
Point any MCP client at `https://nova-otter-delta-cloud.grok.me/mcp` (tool `preflight_url`).
|
|
52
|
-
|
|
53
|
-
- Website: https://otter-sand-wolf-spring.grok.me
|
|
54
|
-
- Docs: https://nova-otter-delta-cloud.grok.me/docs
|
|
55
|
-
- LLM reference: https://nova-otter-delta-cloud.grok.me/llms.txt
|
|
56
|
-
|
|
57
|
-
Made by Canada Site Ops. MIT licensed.
|
surface_haystack-0.1.0/README.md
DELETED
|
@@ -1,37 +0,0 @@
|
|
|
1
|
-
# surface-haystack
|
|
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. If Surface can't be reached, the tool answers skip, so your agent stays safe.
|
|
4
|
-
|
|
5
|
-
This package gives Haystack agents that check as one ready-made tool: `surface_preflight`.
|
|
6
|
-
|
|
7
|
-
```bash
|
|
8
|
-
pip install surface-haystack
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
```python
|
|
12
|
-
from surface_haystack import SurfacePreflight, surface_preflight
|
|
13
|
-
|
|
14
|
-
print(SurfacePreflight().run(url="https://youtu.be/jNQXAC9IVRw"))
|
|
15
|
-
# or give the Tool to a Haystack Agent / ToolInvoker: tools=[surface_preflight]
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
## Free to start
|
|
19
|
-
|
|
20
|
-
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:
|
|
21
|
-
|
|
22
|
-
```bash
|
|
23
|
-
curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
|
|
24
|
-
export SURFACE_API_KEY=...
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
After the free tier: $0.25 USD per 1,000 preflights.
|
|
28
|
-
|
|
29
|
-
## Prefer MCP?
|
|
30
|
-
|
|
31
|
-
Point any MCP client at `https://nova-otter-delta-cloud.grok.me/mcp` (tool `preflight_url`).
|
|
32
|
-
|
|
33
|
-
- Website: https://otter-sand-wolf-spring.grok.me
|
|
34
|
-
- Docs: https://nova-otter-delta-cloud.grok.me/docs
|
|
35
|
-
- LLM reference: https://nova-otter-delta-cloud.grok.me/llms.txt
|
|
36
|
-
|
|
37
|
-
Made by Canada Site Ops. MIT licensed.
|
|
File without changes
|