Metadata-Version: 2.5
Name: dspy-surface
Version: 0.1.2
Summary: Surface for DSPy: 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://nova-otter-delta-cloud.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: ai-agents,dspy,dspy-tool,link-safety,mcp,preflight,react,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: dspy>=2.5
Description-Content-Type: text/markdown

# dspy-surface

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

This package gives DSPy agents that check as one ready-made tool: `surface_preflight`.

Surface by Canada Site Ops. Ontario, Canada.

## Get a free API key in about 10 seconds

No email, no card. Then set `SURFACE_KEY` or `SURFACE_API_KEY`. The tool sends it as `Authorization: Bearer <key>`.

```bash
curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
# returns {"key","created_at","free_monthly":1000000,"usage_url"}
export SURFACE_KEY=...       # or SURFACE_API_KEY; paste the key value
```

A key gets its own million free requests a month. The tool also runs without a key on a shared demo limit.

## Install

```bash
pip install dspy-surface
```

```python
import dspy
from dspy_surface import surface_preflight

react = dspy.ReAct("question -> answer", tools=[surface_preflight])
```

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`.

## Prefer MCP?

Mint a key first, then paste this into your MCP settings (tool `preflight_url`):

```json
{
  "mcpServers": {
    "surface": {
      "type": "http",
      "url": "https://nova-otter-delta-cloud.grok.me/mcp",
      "headers": {
        "Authorization": "Bearer REPLACE_WITH_YOUR_KEY"
      }
    }
  }
}
```

## Also listed

- Official MCP Registry: `me.grok.nova-otter-delta-cloud/surface`
- https://www.curatedmcp.com/marketplace/surface
- https://www.npmjs.com/package/@surfaceapi/surface
- https://pypi.org/project/dspy-surface/
- https://pypi.org/project/surfaceapi/
- https://huggingface.co/spaces/surfaceapi/surface-preflight

CLI and GitHub Action are coming soon.
