pydantic-ai-specstream 0.1.0__tar.gz

pydantic_ai_specstream-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.venv/
+.pytest_cache/
+*.tsbuildinfo
+*.tgz
+*.whl
+.env
+.env.*
+!.env.example
+.DS_Store

pydantic_ai_specstream-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpecStream SAS
+
+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, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pydantic_ai_specstream-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.5
+Name: pydantic-ai-specstream
+Version: 0.1.0
+Summary: The live web data engine for Pydantic AI: Search API ($5 per 1,000 searches), Extract API ($0.80 per 1,000 pages) and Deep Search.
+Project-URL: Homepage, https://specstream.ai
+Project-URL: Documentation, https://specstream.ai/docs/api
+Project-URL: Repository, https://github.com/specstream/specstream-tools/tree/main/packages/pydantic-ai-specstream
+Project-URL: Issues, https://github.com/specstream/specstream-tools/issues
+Project-URL: Pricing, https://specstream.ai/pricing
+Author-email: SpecStream <support@specstream.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,extract-api,live-web,pydantic-ai,search-api,specstream,tools,toolset,web-data,web-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-ai-slim>=2.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pydantic-ai-specstream
+
+[SpecStream](https://specstream.ai) is the live web data engine for teams and agents. One platform to build, search, extract, enrich, map, and monitor data across the entire web.
+
+Ask for any dataset in plain words, and SpecStream builds it from the entire live web: every match found, extracted and enriched into structured records, then monitored for change. It runs through the API and MCP, and inside Sheets, CRMs, Slack, n8n, Zapier and the other tools teams already use.
+
+Source URL and read time on every value.
+
+Three products:
+
+1. Search API: `GET /v1/web-search`, $5 per 1,000 searches. The most accurate web search API in the world (scores and method: https://specstream.ai/benchmarks).
+2. Extract API: `POST /v1/extract`, up to 20 URLs a call (web pages, PDF, Word, Excel), $0.80 per 1,000 pages. A page with no text is not charged.
+3. Deep Search: Ask in plain words. Get every match on the live web, in structured rows. Priced per row.
+
+## Install
+
+```bash
+pip install pydantic-ai-specstream
+export SPECSTREAM_API_KEY=ss_live_...   # Agents & API in your SpecStream workspace
+```
+
+A free account comes with $10 of credit to use within 30 days and needs no card: [specstream.ai](https://specstream.ai/signup).
+
+## What it adds
+
+| Function | What it gives the agent | Cost |
+| --- | --- | --- |
+| `specstream_search_tool()` | A `specstream_search` tool: calls `GET /v1/web-search` and returns the answer, matching rows and ranked sources, with page passages when `passages=True` | $5 per 1,000 searches |
+| `specstream_extract_tool()` | A `specstream_extract` tool: calls `POST /v1/extract` and returns the main text, title and published date of 1 to 20 web pages, PDF, Word or Excel files | $0.80 per 1,000 pages (pages with no text are free) |
+| `specstream_toolset()` | A `FunctionToolset` with both tools, for `Agent(toolsets=[...])` | |
+
+Each function takes `api_key` (default: the `SPECSTREAM_API_KEY` environment variable), `base_url` and a shared `httpx.AsyncClient` as `client`. A failed call raises `SpecStreamError` with the API message.
+
+MIT licensed.

pydantic_ai_specstream-0.1.0/README.md

@@ -0,0 +1,34 @@
+# pydantic-ai-specstream
+
+[SpecStream](https://specstream.ai) is the live web data engine for teams and agents. One platform to build, search, extract, enrich, map, and monitor data across the entire web.
+
+Ask for any dataset in plain words, and SpecStream builds it from the entire live web: every match found, extracted and enriched into structured records, then monitored for change. It runs through the API and MCP, and inside Sheets, CRMs, Slack, n8n, Zapier and the other tools teams already use.
+
+Source URL and read time on every value.
+
+Three products:
+
+1. Search API: `GET /v1/web-search`, $5 per 1,000 searches. The most accurate web search API in the world (scores and method: https://specstream.ai/benchmarks).
+2. Extract API: `POST /v1/extract`, up to 20 URLs a call (web pages, PDF, Word, Excel), $0.80 per 1,000 pages. A page with no text is not charged.
+3. Deep Search: Ask in plain words. Get every match on the live web, in structured rows. Priced per row.
+
+## Install
+
+```bash
+pip install pydantic-ai-specstream
+export SPECSTREAM_API_KEY=ss_live_...   # Agents & API in your SpecStream workspace
+```
+
+A free account comes with $10 of credit to use within 30 days and needs no card: [specstream.ai](https://specstream.ai/signup).
+
+## What it adds
+
+| Function | What it gives the agent | Cost |
+| --- | --- | --- |
+| `specstream_search_tool()` | A `specstream_search` tool: calls `GET /v1/web-search` and returns the answer, matching rows and ranked sources, with page passages when `passages=True` | $5 per 1,000 searches |
+| `specstream_extract_tool()` | A `specstream_extract` tool: calls `POST /v1/extract` and returns the main text, title and published date of 1 to 20 web pages, PDF, Word or Excel files | $0.80 per 1,000 pages (pages with no text are free) |
+| `specstream_toolset()` | A `FunctionToolset` with both tools, for `Agent(toolsets=[...])` | |
+
+Each function takes `api_key` (default: the `SPECSTREAM_API_KEY` environment variable), `base_url` and a shared `httpx.AsyncClient` as `client`. A failed call raises `SpecStreamError` with the API message.
+
+MIT licensed.

pydantic_ai_specstream-0.1.0/pydantic_ai_specstream/__init__.py

@@ -0,0 +1,124 @@
+"""SpecStream Search API and Extract API as Pydantic AI tools and a toolset."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+from pydantic_ai import FunctionToolset, Tool
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://api.specstream.ai"
+MAX_EXTRACT_URLS = 20
+TIMEOUT_SECONDS = 60.0
+USER_AGENT = f"pydantic-ai-specstream/{__version__}"
+
+__all__ = [
+    "SpecStreamError",
+    "specstream_extract_tool",
+    "specstream_search_tool",
+    "specstream_toolset",
+]
+
+
+class SpecStreamError(RuntimeError):
+    """A SpecStream call failed. The message is the API error message or the HTTP status."""
+
+
+class _Client:
+    def __init__(self, api_key: str | None, base_url: str | None, client: httpx.AsyncClient | None) -> None:
+        self._api_key = (api_key or os.environ.get("SPECSTREAM_API_KEY") or "").strip()
+        self._base_url = (base_url or os.environ.get("SPECSTREAM_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._client = client
+
+    async def call(self, method: str, path: str, *, params: dict[str, Any] | None = None, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        if not self._api_key:
+            raise SpecStreamError("Set SPECSTREAM_API_KEY or pass api_key. Create a key under Agents & API in your SpecStream workspace.")
+        headers = {"Authorization": f"Bearer {self._api_key}", "Accept": "application/json", "User-Agent": USER_AGENT}
+        client = self._client or httpx.AsyncClient(timeout=TIMEOUT_SECONDS)
+        try:
+            response = await client.request(method, self._base_url + path, params=params, json=json, headers=headers)
+        finally:
+            if self._client is None:
+                await client.aclose()
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = {}
+        data = payload.get("data") if isinstance(payload, dict) else None
+        if response.is_error or not isinstance(data, dict):
+            error = payload.get("error") if isinstance(payload, dict) else None
+            message = error.get("message") if isinstance(error, dict) else None
+            raise SpecStreamError(str(message or f"SpecStream HTTP {response.status_code}"))
+        return data
+
+
+def specstream_search_tool(
+    api_key: str | None = None,
+    *,
+    base_url: str | None = None,
+    client: httpx.AsyncClient | None = None,
+    passages: bool = False,
+) -> Tool[Any]:
+    """A Pydantic AI tool for the Search API (`GET /v1/web-search`, $5 per 1,000 searches).
+
+    `passages=True` adds the text of the top pages to every search. The reply holds `kind`, `answer`,
+    `rows`, `sources` and, with passages, `passages`.
+    """
+    api = _Client(api_key, base_url, client)
+
+    async def specstream_search(q: str) -> dict[str, Any]:
+        """Search the live web with SpecStream and return the answer, matching rows and ranked sources.
+
+        Args:
+            q: The question or request in everyday words, 1 to 2,000 characters.
+        """
+        params: dict[str, Any] = {"q": q.strip()[:2000]}
+        if passages:
+            params["passages"] = "true"
+        return await api.call("GET", "/v1/web-search", params=params)
+
+    return Tool(specstream_search, name="specstream_search")
+
+
+def specstream_extract_tool(
+    api_key: str | None = None,
+    *,
+    base_url: str | None = None,
+    client: httpx.AsyncClient | None = None,
+) -> Tool[Any]:
+    """A Pydantic AI tool for the Extract API (`POST /v1/extract`, $0.80 per 1,000 pages, a page with no text is free)."""
+    api = _Client(api_key, base_url, client)
+
+    async def specstream_extract(urls: list[str], format: str = "markdown") -> dict[str, Any]:
+        """Read the main text of web pages, PDF, Word and Excel files live with SpecStream.
+
+        Args:
+            urls: 1 to 20 http or https URLs to read.
+            format: "markdown" (default) or "text".
+        """
+        cleaned = [url.strip() for url in urls if url and url.strip()][:MAX_EXTRACT_URLS]
+        if not cleaned:
+            raise SpecStreamError("Send 1 to 20 http or https URLs.")
+        body = {"urls": cleaned, "format": "text" if format == "text" else "markdown"}
+        return await api.call("POST", "/v1/extract", json=body)
+
+    return Tool(specstream_extract, name="specstream_extract")
+
+
+def specstream_toolset(
+    api_key: str | None = None,
+    *,
+    base_url: str | None = None,
+    client: httpx.AsyncClient | None = None,
+    passages: bool = False,
+) -> FunctionToolset[Any]:
+    """A Pydantic AI toolset with `specstream_search` and `specstream_extract`."""
+    return FunctionToolset(
+        [
+            specstream_search_tool(api_key, base_url=base_url, client=client, passages=passages),
+            specstream_extract_tool(api_key, base_url=base_url, client=client),
+        ]
+    )

pydantic_ai_specstream-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "pydantic-ai-specstream"
+version = "0.1.0"
+description = "The live web data engine for Pydantic AI: Search API ($5 per 1,000 searches), Extract API ($0.80 per 1,000 pages) and Deep Search."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "SpecStream", email = "support@specstream.ai" }]
+keywords = ["pydantic-ai", "specstream", "agents", "tools", "toolset", "web-search", "search-api", "extract-api", "web-data", "live-web"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+dependencies = ["pydantic-ai-slim>=2.0", "httpx>=0.27"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[project.urls]
+Homepage = "https://specstream.ai"
+Documentation = "https://specstream.ai/docs/api"
+Repository = "https://github.com/specstream/specstream-tools/tree/main/packages/pydantic-ai-specstream"
+Issues = "https://github.com/specstream/specstream-tools/issues"
+Pricing = "https://specstream.ai/pricing"
+
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pydantic_ai_specstream"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

pydantic_ai_specstream-0.1.0/tests/test_specstream.py

@@ -0,0 +1,72 @@
+import json
+
+import httpx
+import pytest
+from pydantic_ai import Agent
+from pydantic_ai.models.test import TestModel
+
+from pydantic_ai_specstream import (
+    SpecStreamError,
+    specstream_extract_tool,
+    specstream_search_tool,
+    specstream_toolset,
+)
+
+SEARCH = {"data": {"kind": "fact", "answer": {"value": "42", "page": "https://a.example"}, "rows": [], "sources": []}}
+EXTRACT = {"data": {"results": [{"url": "https://a.example", "status": "ok", "text": "page"}], "price_usd": 0.0008}}
+
+
+def make_client(handler):
+    seen: list[httpx.Request] = []
+
+    def record(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        return handler(request)
+
+    return httpx.AsyncClient(transport=httpx.MockTransport(record)), seen
+
+
+def ok(request: httpx.Request) -> httpx.Response:
+    return httpx.Response(200, json=EXTRACT if request.url.path == "/v1/extract" else SEARCH)
+
+
+async def test_search_tool_sends_the_question_with_the_key():
+    client, seen = make_client(ok)
+    tool = specstream_search_tool("ss_test", client=client, passages=True)
+    result = await tool.function(q="  a question  ")
+    assert result["answer"]["value"] == "42"
+    request = seen[0]
+    assert request.method == "GET"
+    assert request.headers["authorization"] == "Bearer ss_test"
+    assert request.url.params["q"] == "a question"
+    assert request.url.params["passages"] == "true"
+
+
+async def test_extract_tool_posts_at_most_twenty_urls():
+    client, seen = make_client(ok)
+    tool = specstream_extract_tool("ss_test", client=client)
+    urls = [f"https://a.example/{i}" for i in range(25)]
+    result = await tool.function(urls=urls, format="text")
+    assert result["results"][0]["status"] == "ok"
+    body = json.loads(seen[0].content)
+    assert seen[0].method == "POST" and seen[0].url.path == "/v1/extract"
+    assert body["urls"] == urls[:20] and body["format"] == "text"
+
+
+async def test_errors_carry_the_api_message_or_the_status(monkeypatch):
+    client, _ = make_client(lambda r: httpx.Response(402, json={"error": {"message": "Balance is empty."}}))
+    with pytest.raises(SpecStreamError, match="Balance is empty."):
+        await specstream_search_tool("ss_test", client=client).function(q="x")
+    client, _ = make_client(lambda r: httpx.Response(503, text="busy"))
+    with pytest.raises(SpecStreamError, match="HTTP 503"):
+        await specstream_extract_tool("ss_test", client=client).function(urls=["https://a.example"])
+    monkeypatch.delenv("SPECSTREAM_API_KEY", raising=False)
+    with pytest.raises(SpecStreamError, match="SPECSTREAM_API_KEY"):
+        await specstream_search_tool().function(q="x")
+
+
+async def test_agent_calls_both_tools_through_the_toolset():
+    client, seen = make_client(ok)
+    agent = Agent(TestModel(), toolsets=[specstream_toolset("ss_test", client=client)])
+    await agent.run("go")
+    assert {r.url.path for r in seen} == {"/v1/web-search", "/v1/extract"}