langchain-specstream 0.1.0__tar.gz

langchain_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

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

langchain_specstream-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: langchain-specstream
+Version: 0.1.0
+Summary: Give a LangChain agent any list from the live web: ask in plain words, get every matching row with the page it came from, within a price you set in code.
+Project-URL: Homepage, https://specstream.ai
+Project-URL: Documentation, https://specstream.ai/docs/langchain
+Project-URL: Repository, https://github.com/Specstreamai/specstream-tools/tree/main/packages/langchain-specstream
+Project-URL: Issues, https://github.com/Specstreamai/specstream-tools/issues
+Project-URL: Pricing, https://specstream.ai/pricing
+Author-email: SpecStream <support@specstream.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,langchain,lead-lists,live-web,research,retriever,specstream,tools,web-data
+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: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: langchain-core<2.0.0,>=0.3.0
+Provides-Extra: test
+Requires-Dist: langchain-tests>=0.3; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-specstream
+
+Give your LangChain agent any list from the live web. It asks in plain words – "dental clinics in Lisbon with online booking", "US startups that filed a $5M+ Form D this week" – and gets back every matching row, each with the page it was read from. The list starts only within a price you set in code, and the model can't raise it.
+
+```bash
+pip install -U langchain-specstream
+export SPECSTREAM_API_KEY=ss_live_...   # Agents & API in your SpecStream workspace
+```
+
+A free account comes with $10 of work to use within 30 days and needs no card: [specstream.ai](https://specstream.ai/signup).
+
+## An agent that can find lists
+
+```python
+from langchain.agents import create_agent
+from langchain_specstream import specstream_tools
+
+agent = create_agent(
+    "anthropic:claude-sonnet-5-5",
+    tools=specstream_tools(max_price_usd=5),
+)
+agent.invoke({"messages": [{"role": "user", "content":
+    "Find US startups that raised $5M or more in a Form D filed after October 8, 2026. Which industries lead?"}]})
+```
+
+The agent writes the request and picks how many rows. You decide what one list may cost.
+
+## What comes back
+
+One flat row per match: the list's own columns, then where the row was read. This is a real row from the request above.
+
+```json
+{
+  "list_id": "fnd_gk5y3d0r97bvyz0t08zzh75kr6",
+  "position": 26,
+  "Organization": "RapidCanvas Inc",
+  "Published address": "801 BARTON SPRINGS RD, AUSTIN, TEXAS, 78704",
+  "Source industry classification": "Other Technology",
+  "Amount sold (USD)": "28999988",
+  "Funding filing date": "2026-10-14",
+  "source_url": "https://www.sec.gov/Archives/edgar/data/2052031/000205203126000006/primary_doc.xml",
+  "checked_at": "2026-10-14T19:56:02.016693Z",
+  "list_link": "https://specstream.ai/workspace/collections/fnd_gk5y3d0r97bvyz0t08zzh75kr6"
+}
+```
+
+Columns follow the request. Ask for "breweries in Portland, Oregon that host events, with their website" and the rows carry the brewery and its website instead. A fact a source doesn't publish comes back empty, never guessed.
+
+## The two tools
+
+| Tool | The model gives | What happens | Cost |
+| --- | --- | --- | --- |
+| `specstream_find_list` | `request`, `max_results` | Reads the request, prices it, starts it only within `max_price_usd`, waits up to `wait_seconds` (5 minutes by default) and returns every row | Only the rows that match |
+| `specstream_get_list_results` | `list_id` | Every row found so far, for a list that was still running | Free |
+
+When the price is above your maximum, nothing runs: the tool returns the price, so the agent can ask for fewer rows or tell the user. When a request is too vague to price ("clinics"), it returns how SpecStream read it, so the agent can add the place or the conditions.
+
+Use the classes directly when you want different settings per tool:
+
+```python
+from langchain_specstream import SpecStreamFindList, SpecStreamGetListResults
+
+find = SpecStreamFindList(max_price_usd=20, wait_seconds=600)
+results = SpecStreamGetListResults()
+```
+
+## As a retriever
+
+```python
+from langchain_specstream import SpecStreamRetriever
+
+retriever = SpecStreamRetriever(max_price_usd=3, max_results=25)
+docs = retriever.invoke("Breweries in Portland, Oregon that host events, with their website")
+
+docs[0].page_content          # "Business location: Occidental Brewing Company\nPublished business website: http://occidentalbeers.com ..."
+docs[0].metadata["source_url"]  # the page that row was read from
+```
+
+One document per row, its facts as text and its source in the metadata, so a chain can cite every claim. Above the maximum, the retriever raises `SpecStreamError` and nothing runs.
+
+## Money, plainly
+
+- `max_price_usd` lives on the tool, in your code. The model never sees it and can't change it.
+- You pay for rows that match. Candidates SpecStream couldn't confirm are left out and aren't billed.
+- A retried step asking for the same list within the hour gets the list it already started, not a second bill.
+- Rates and plans: [specstream.ai/pricing](https://specstream.ai/pricing).
+
+## When to reach for it
+
+When the answer is many things that meet conditions: companies in a city, clinics with a service, funding filings, open grants, tenders, repositories, people in a role. For a single fact or a summary of one page, a search tool fits better.
+
+## More
+
+- [SpecStream docs](https://specstream.ai/docs) and the [LangChain page](https://specstream.ai/docs/langchain)
+- Agents outside LangChain: the [MCP server](https://specstream.ai/docs/mcp) at `https://api.specstream.ai/mcp`
+- The [Python SDK](https://pypi.org/project/specstream-client/) for everything else in the API
+- Questions: support@specstream.ai
+
+MIT licensed. Made by [SpecStream](https://specstream.ai), the live web data engine for teams and agents.

langchain_specstream-0.1.0/README.md

@@ -0,0 +1,99 @@
+# langchain-specstream
+
+Give your LangChain agent any list from the live web. It asks in plain words – "dental clinics in Lisbon with online booking", "US startups that filed a $5M+ Form D this week" – and gets back every matching row, each with the page it was read from. The list starts only within a price you set in code, and the model can't raise it.
+
+```bash
+pip install -U langchain-specstream
+export SPECSTREAM_API_KEY=ss_live_...   # Agents & API in your SpecStream workspace
+```
+
+A free account comes with $10 of work to use within 30 days and needs no card: [specstream.ai](https://specstream.ai/signup).
+
+## An agent that can find lists
+
+```python
+from langchain.agents import create_agent
+from langchain_specstream import specstream_tools
+
+agent = create_agent(
+    "anthropic:claude-sonnet-5-5",
+    tools=specstream_tools(max_price_usd=5),
+)
+agent.invoke({"messages": [{"role": "user", "content":
+    "Find US startups that raised $5M or more in a Form D filed after October 8, 2026. Which industries lead?"}]})
+```
+
+The agent writes the request and picks how many rows. You decide what one list may cost.
+
+## What comes back
+
+One flat row per match: the list's own columns, then where the row was read. This is a real row from the request above.
+
+```json
+{
+  "list_id": "fnd_gk5y3d0r97bvyz0t08zzh75kr6",
+  "position": 26,
+  "Organization": "RapidCanvas Inc",
+  "Published address": "801 BARTON SPRINGS RD, AUSTIN, TEXAS, 78704",
+  "Source industry classification": "Other Technology",
+  "Amount sold (USD)": "28999988",
+  "Funding filing date": "2026-10-14",
+  "source_url": "https://www.sec.gov/Archives/edgar/data/2052031/000205203126000006/primary_doc.xml",
+  "checked_at": "2026-10-14T19:56:02.016693Z",
+  "list_link": "https://specstream.ai/workspace/collections/fnd_gk5y3d0r97bvyz0t08zzh75kr6"
+}
+```
+
+Columns follow the request. Ask for "breweries in Portland, Oregon that host events, with their website" and the rows carry the brewery and its website instead. A fact a source doesn't publish comes back empty, never guessed.
+
+## The two tools
+
+| Tool | The model gives | What happens | Cost |
+| --- | --- | --- | --- |
+| `specstream_find_list` | `request`, `max_results` | Reads the request, prices it, starts it only within `max_price_usd`, waits up to `wait_seconds` (5 minutes by default) and returns every row | Only the rows that match |
+| `specstream_get_list_results` | `list_id` | Every row found so far, for a list that was still running | Free |
+
+When the price is above your maximum, nothing runs: the tool returns the price, so the agent can ask for fewer rows or tell the user. When a request is too vague to price ("clinics"), it returns how SpecStream read it, so the agent can add the place or the conditions.
+
+Use the classes directly when you want different settings per tool:
+
+```python
+from langchain_specstream import SpecStreamFindList, SpecStreamGetListResults
+
+find = SpecStreamFindList(max_price_usd=20, wait_seconds=600)
+results = SpecStreamGetListResults()
+```
+
+## As a retriever
+
+```python
+from langchain_specstream import SpecStreamRetriever
+
+retriever = SpecStreamRetriever(max_price_usd=3, max_results=25)
+docs = retriever.invoke("Breweries in Portland, Oregon that host events, with their website")
+
+docs[0].page_content          # "Business location: Occidental Brewing Company\nPublished business website: http://occidentalbeers.com ..."
+docs[0].metadata["source_url"]  # the page that row was read from
+```
+
+One document per row, its facts as text and its source in the metadata, so a chain can cite every claim. Above the maximum, the retriever raises `SpecStreamError` and nothing runs.
+
+## Money, plainly
+
+- `max_price_usd` lives on the tool, in your code. The model never sees it and can't change it.
+- You pay for rows that match. Candidates SpecStream couldn't confirm are left out and aren't billed.
+- A retried step asking for the same list within the hour gets the list it already started, not a second bill.
+- Rates and plans: [specstream.ai/pricing](https://specstream.ai/pricing).
+
+## When to reach for it
+
+When the answer is many things that meet conditions: companies in a city, clinics with a service, funding filings, open grants, tenders, repositories, people in a role. For a single fact or a summary of one page, a search tool fits better.
+
+## More
+
+- [SpecStream docs](https://specstream.ai/docs) and the [LangChain page](https://specstream.ai/docs/langchain)
+- Agents outside LangChain: the [MCP server](https://specstream.ai/docs/mcp) at `https://api.specstream.ai/mcp`
+- The [Python SDK](https://pypi.org/project/specstream-client/) for everything else in the API
+- Questions: support@specstream.ai
+
+MIT licensed. Made by [SpecStream](https://specstream.ai), the live web data engine for teams and agents.

langchain_specstream-0.1.0/langchain_specstream/__init__.py

@@ -0,0 +1,8 @@
+"""SpecStream for LangChain: ask for any list on the live web in plain words, within a price you set."""
+
+from langchain_specstream._api import SpecStreamError
+from langchain_specstream.retrievers import SpecStreamRetriever
+from langchain_specstream.tools import SpecStreamFindList, SpecStreamGetListResults, specstream_tools
+
+__all__ = ["SpecStreamError", "SpecStreamFindList", "SpecStreamGetListResults", "SpecStreamRetriever", "specstream_tools"]
+__version__ = "0.1.0"

langchain_specstream-0.1.0/langchain_specstream/_api.py

@@ -0,0 +1,197 @@
+"""The SpecStream REST calls the tools share: read a request, price it, start it within a maximum, read its rows."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable
+
+DEFAULT_BASE_URL = "https://api.specstream.ai"
+USER_AGENT = "langchain-specstream/0.1.0"
+FINISHED = {"completed", "partial"}
+STOPPED = {"failed", "cancelled", "canceled", "expired"}
+# Fields every row carries; a column with the same name is renamed so it can't overwrite them.
+RESERVED = {"list_id", "list_link", "position", "source_url", "checked_at"}
+
+Opener = Callable[[urllib.request.Request, float], Any]
+
+
+class SpecStreamError(RuntimeError):
+    """SpecStream refused a call or answered with something this package can't read."""
+
+
+def _dollars(cents: int) -> str:
+    return f"${cents / 100:.2f}"
+
+
+def list_link(find_id: str) -> str:
+    return f"https://specstream.ai/workspace/collections/{urllib.parse.quote(find_id, safe='')}"
+
+
+def flatten_row(find_id: str, record: dict[str, Any]) -> dict[str, Any]:
+    """One row as flat fields: each column's label holds what the list shows, plus where the row was read."""
+    row: dict[str, Any] = {"list_id": find_id, "position": record.get("ordinal")}
+    source: dict[str, Any] | None = None
+    for cell in record.get("details") or record.get("cells") or []:
+        label = str(cell.get("label") or cell.get("column_id") or "").strip()
+        if not label:
+            continue
+        if label in RESERVED:
+            label = f"{label} (column)"
+        if cell.get("absence"):
+            value: Any = ""
+        elif cell.get("display") is not None:
+            value = cell["display"]
+        else:
+            value = cell.get("value") if cell.get("value") is not None else ""
+        row[label] = value
+        provenance = cell.get("provenance") or {}
+        if source is None and str(provenance.get("source_url") or "").startswith("http"):
+            source = provenance
+    row["source_url"] = source.get("source_url", "") if source else ""
+    row["checked_at"] = source.get("observed_at", "") if source else ""
+    row["list_link"] = list_link(find_id)
+    return row
+
+
+@dataclass
+class SpecStreamAPI:
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = 30.0
+    opener: Opener | None = None
+    sleep: Callable[[float], None] = time.sleep
+    clock: Callable[[], float] = time.monotonic
+
+    def request(self, method: str, path: str, body: dict[str, Any] | None = None, *, allow_404: bool = False) -> dict[str, Any] | None:
+        key = (self.api_key or "").strip()
+        if not key:
+            raise SpecStreamError("Set SPECSTREAM_API_KEY or pass api_key. Create a key under Agents & API in your SpecStream workspace.")
+        request = urllib.request.Request(
+            self.base_url.rstrip("/") + path,
+            data=None if body is None else json.dumps(body).encode(),
+            method=method,
+            headers={
+                "Authorization": key if key.lower().startswith("bearer ") else f"Bearer {key}",
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                "User-Agent": USER_AGENT,
+            },
+        )
+        open_ = self.opener or (lambda req, timeout: urllib.request.urlopen(req, timeout=timeout))
+        try:
+            response = open_(request, self.timeout)
+            try:
+                raw = response.read()
+            finally:
+                response.close()
+        except urllib.error.HTTPError as error:
+            if allow_404 and error.code == 404:
+                return None
+            raise SpecStreamError(_error_message(error)) from None
+        except urllib.error.URLError as error:
+            raise SpecStreamError(f"Couldn't reach SpecStream: {error.reason}") from None
+        try:
+            payload = json.loads(raw or b"{}")
+        except ValueError:
+            payload = None
+        if not isinstance(payload, dict) or not isinstance(payload.get("data"), dict):
+            raise SpecStreamError("SpecStream returned a response this package couldn't read.")
+        return payload["data"]
+
+    def results(self, find_id: str) -> dict[str, Any]:
+        """Every row found so far for a list, following the pages."""
+        rows: list[dict[str, Any]] = []
+        cursor: str | None = None
+        status = "running"
+        while True:
+            query = {"limit": "100", **({"cursor": cursor} if cursor else {})}
+            page = self.request("GET", f"/v1/finds/{urllib.parse.quote(find_id, safe='')}/rows?{urllib.parse.urlencode(query)}") or {}
+            status = page.get("status") or status
+            rows.extend(flatten_row(find_id, record) for record in page.get("rows") or [])
+            cursor = page.get("next_cursor")
+            if not cursor:
+                break
+        return {"list_id": find_id, "status": status, "list_link": list_link(find_id), "row_count": len(rows), "rows": rows}
+
+    def find_list(
+        self,
+        request: str,
+        *,
+        max_results: int,
+        max_price_usd: float,
+        wait_seconds: float = 300.0,
+        poll_interval: float = 3.0,
+        locale: str = "en-US",
+        key_prefix: str = "langchain",
+    ) -> dict[str, Any]:
+        q = (request or "").strip()
+        if not q:
+            raise ValueError("Describe the list to find.")
+        if not isinstance(max_results, int) or max_results < 1:
+            raise ValueError("max_results must be 1 or more.")
+        max_cents = round(float(max_price_usd) * 100)
+        if max_cents <= 0:
+            raise ValueError("max_price_usd must be greater than 0.")
+
+        # The same request with the same limits within the same hour gets the run it already started,
+        # so a retried agent step never buys the list twice.
+        hour = time.strftime("%Y-%m-%dT%H", time.gmtime())
+        digest = hashlib.sha256(f"{q}|{max_results}|{max_cents}|{hour}".encode()).hexdigest()[:32]
+        request_key = f"{key_prefix}-{digest}"
+        existing = self.request("GET", f"/v1/capacity/requests/{urllib.parse.quote(request_key, safe='')}", allow_404=True)
+        if existing and existing.get("find_id"):
+            find_id = existing["find_id"]
+            maximum_cents = int(existing.get("maximum_cents") or max_cents)
+        else:
+            reading = self.request("POST", "/v1/parse", {"q": q, "locale": locale}) or {}
+            if reading.get("status") != "runnable":
+                read_as = reading.get("canonical_sentence") or q
+                return {
+                    "status": "needs_edit",
+                    "request": q,
+                    "message": f'SpecStream needs a clearer request before it can price it. It read: "{read_as}". Add the place or what every row must meet.',
+                }
+            quote = self.request(
+                "POST", "/v1/capacity/quotes", {"ast_hash": reading["ast_hash"], "operation": "find", "requested_units": max_results}
+            ) or {}
+            maximum_cents = int(quote.get("maximum_cents") or 0)
+            if maximum_cents > max_cents:
+                return {
+                    "status": "over_maximum",
+                    "request": q,
+                    "maximum_price_usd": maximum_cents / 100,
+                    "message": f"Nothing ran: this list can cost up to {_dollars(maximum_cents)}, above the maximum of {_dollars(max_cents)}. Ask for fewer results or raise max_price_usd.",
+                }
+            run = self.request(
+                "POST",
+                "/v1/capacity/executions",
+                {"quote_id": quote["quote_id"], "quote_hash": quote["quote_hash"], "confirm_max_cents": maximum_cents, "idempotency_key": request_key},
+            ) or {}
+            find_id = run["find_id"]
+
+        deadline = self.clock() + max(0.0, wait_seconds)
+        while True:
+            result = self.results(find_id)
+            if result["status"] in FINISHED | STOPPED or self.clock() >= deadline:
+                break
+            self.sleep(poll_interval)
+        result.update({"request": q, "maximum_price_usd": maximum_cents / 100})
+        if result["status"] not in FINISHED | STOPPED:
+            result["message"] = "Still running. Call specstream_get_list_results with this list_id for the rest."
+        return result
+
+
+def _error_message(error: urllib.error.HTTPError) -> str:
+    try:
+        payload = json.loads(error.read() or b"{}")
+    except ValueError:
+        payload = {}
+    detail = payload.get("error") if isinstance(payload, dict) else None
+    message = detail.get("message") if isinstance(detail, dict) else detail if isinstance(detail, str) else None
+    return f"SpecStream answered {error.code}: {message or error.reason}"

langchain_specstream-0.1.0/langchain_specstream/retrievers.py

@@ -0,0 +1,54 @@
+"""A retriever whose documents are the rows of a SpecStream list."""
+
+from __future__ import annotations
+
+from langchain_core.callbacks import CallbackManagerForRetrieverRun
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from langchain_core.utils import secret_from_env
+from pydantic import Field, SecretStr
+
+from langchain_specstream._api import DEFAULT_BASE_URL, SpecStreamAPI, SpecStreamError
+
+# Row fields that describe where the row came from rather than what it says.
+_META = ("list_id", "list_link", "position", "source_url", "checked_at")
+
+
+class SpecStreamRetriever(BaseRetriever):
+    """Turn a plain-English request into documents, one per matching row, with its source in the metadata.
+
+    Example:
+        .. code-block:: python
+
+            from langchain_specstream import SpecStreamRetriever
+
+            retriever = SpecStreamRetriever(max_price_usd=3, max_results=25)
+            docs = retriever.invoke("Breweries in Portland, Oregon that host events, with their website")
+    """
+
+    api_key: SecretStr = Field(default_factory=secret_from_env("SPECSTREAM_API_KEY"))
+    base_url: str = DEFAULT_BASE_URL
+    max_price_usd: float = Field(gt=0)
+    """The most one list may cost, in US dollars. If the price is higher, the retriever raises and nothing runs."""
+    max_results: int = Field(default=25, ge=1, le=1000)
+    wait_seconds: float = 300.0
+    poll_interval: float = 3.0
+    locale: str = "en-US"
+
+    def _get_relevant_documents(self, query: str, *, run_manager: CallbackManagerForRetrieverRun) -> list[Document]:
+        result = SpecStreamAPI(self.api_key.get_secret_value(), self.base_url).find_list(
+            query,
+            max_results=self.max_results,
+            max_price_usd=self.max_price_usd,
+            wait_seconds=self.wait_seconds,
+            poll_interval=self.poll_interval,
+            locale=self.locale,
+            key_prefix="langchain-retriever",
+        )
+        if result["status"] in ("needs_edit", "over_maximum"):
+            raise SpecStreamError(result["message"])
+        documents = []
+        for row in result["rows"]:
+            facts = "\n".join(f"{label}: {value}" for label, value in row.items() if label not in _META and value not in ("", None))
+            documents.append(Document(page_content=facts, metadata={key: row.get(key) for key in _META} | {"request": result.get("request")}))
+        return documents

langchain_specstream-0.1.0/langchain_specstream/tools.py

@@ -0,0 +1,102 @@
+"""LangChain tools that ask SpecStream for a list on the live web and read its rows."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from langchain_core.utils import secret_from_env
+from pydantic import BaseModel, Field, SecretStr
+
+from langchain_specstream._api import DEFAULT_BASE_URL, SpecStreamAPI
+
+
+class FindListInput(BaseModel):
+    """What the model fills in. The price ceiling is not here: the developer sets it on the tool."""
+
+    request: str = Field(
+        description=(
+            "The list to find, in plain words: what every row must be or meet, and the details to bring back. "
+            "Example: 'Roofing companies in Columbus, Ohio with their website and phone'."
+        )
+    )
+    max_results: int = Field(default=25, ge=1, le=1000, description="How many matching rows to find.")
+
+
+class GetListResultsInput(BaseModel):
+    list_id: str = Field(description="The list_id returned by specstream_find_list.")
+
+
+class _SpecStreamTool(BaseTool):
+    api_key: SecretStr = Field(default_factory=secret_from_env("SPECSTREAM_API_KEY"))
+    """A SpecStream API key. Read from SPECSTREAM_API_KEY when not passed."""
+    base_url: str = DEFAULT_BASE_URL
+
+    def _api(self) -> SpecStreamAPI:
+        return SpecStreamAPI(self.api_key.get_secret_value(), self.base_url)
+
+
+class SpecStreamFindList(_SpecStreamTool):
+    """Ask for a list in plain words and get every matching row, each with the page it was read from.
+
+    The list starts only if its price is within ``max_price_usd``, which you set here, in code. The model
+    chooses the request and how many rows; it can't raise the price ceiling.
+
+    Example:
+        .. code-block:: python
+
+            from langchain_specstream import SpecStreamFindList
+
+            tool = SpecStreamFindList(max_price_usd=5)
+            tool.invoke({"request": "Dental clinics in Lisbon with online booking", "max_results": 20})
+    """
+
+    name: str = "specstream_find_list"
+    description: str = (
+        "Find a list of real organizations, people, places or records on the live web from a plain-English "
+        "request, and get back every matching row with the page it was read from. Use it when the answer is "
+        "many items that meet conditions (companies in a city, clinics with a service, funding filings, open "
+        "grants, tenders, repositories), not a single fact. Results cost money: the list starts only if its "
+        "price is within the maximum the developer set, and only matching rows are paid for."
+    )
+    args_schema: type[BaseModel] = FindListInput
+
+    max_price_usd: float = Field(gt=0)
+    """The most one list may cost, in US dollars. If the price is higher, nothing runs."""
+    wait_seconds: float = 300.0
+    """How long to wait for the list to finish before returning the rows found so far."""
+    poll_interval: float = 3.0
+    locale: str = "en-US"
+
+    def _run(self, request: str, max_results: int = 25, run_manager: Optional[CallbackManagerForToolRun] = None) -> str:
+        result = self._api().find_list(
+            request,
+            max_results=max_results,
+            max_price_usd=self.max_price_usd,
+            wait_seconds=self.wait_seconds,
+            poll_interval=self.poll_interval,
+            locale=self.locale,
+        )
+        return json.dumps(result, ensure_ascii=False, default=str)
+
+
+class SpecStreamGetListResults(_SpecStreamTool):
+    """Read every row found so far for a list. Reading a list you already have costs nothing."""
+
+    name: str = "specstream_get_list_results"
+    description: str = (
+        "Get every row found so far for a SpecStream list, each with the page it was read from. Use it with "
+        "the list_id from specstream_find_list when that list was still running. Costs nothing."
+    )
+    args_schema: type[BaseModel] = GetListResultsInput
+
+    def _run(self, list_id: str, run_manager: Optional[CallbackManagerForToolRun] = None) -> str:
+        return json.dumps(self._api().results(list_id), ensure_ascii=False, default=str)
+
+
+def specstream_tools(max_price_usd: float, **kwargs: Any) -> list[BaseTool]:
+    """Both tools, sharing one key and base URL: the usual way to give an agent SpecStream."""
+    shared = {key: kwargs.pop(key) for key in ("api_key", "base_url") if key in kwargs}
+    return [SpecStreamFindList(max_price_usd=max_price_usd, **shared, **kwargs), SpecStreamGetListResults(**shared)]

langchain_specstream-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "langchain-specstream"
+version = "0.1.0"
+description = "Give a LangChain agent any list from the live web: ask in plain words, get every matching row with the page it came from, within a price you set in code."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "SpecStream", email = "support@specstream.ai" }]
+keywords = ["langchain", "specstream", "agents", "tools", "retriever", "web-data", "live-web", "lead-lists", "research"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+dependencies = ["langchain-core>=0.3.0,<2.0.0"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "langchain-tests>=0.3"]
+
+[project.urls]
+Homepage = "https://specstream.ai"
+Documentation = "https://specstream.ai/docs/langchain"
+Repository = "https://github.com/Specstreamai/specstream-tools/tree/main/packages/langchain-specstream"
+Issues = "https://github.com/Specstreamai/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 = ["langchain_specstream"]
+
+[tool.hatch.build.targets.sdist]
+include = ["langchain_specstream", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

langchain_specstream-0.1.0/tests/test_langchain_specstream.py

@@ -0,0 +1,173 @@
+import io
+import json
+import urllib.error
+import urllib.parse
+
+import pytest
+
+from langchain_specstream import (
+    SpecStreamError,
+    SpecStreamFindList,
+    SpecStreamGetListResults,
+    SpecStreamRetriever,
+    specstream_tools,
+)
+
+KEY = "ss_live_test_key"
+
+
+def cell(label, value, source=None):
+    provenance = {"source_url": source, "observed_at": "2026-10-14T08:00:00Z"} if source else None
+    return {"label": label, "value": value, "display": value, "absence": None, "provenance": provenance}
+
+
+ROWS = [
+    {"ordinal": 1, "cells": [cell("Organization", "Clínica Sorriso", "https://sorriso.pt/marcacoes"), cell("Website", "https://sorriso.pt")]},
+    {"ordinal": 2, "cells": [cell("Organization", "Dentes de Lisboa", "https://dentesdelisboa.pt"), cell("Website", None) | {"absence": "Not published"}]},
+]
+
+
+class FakeSpecStream:
+    """Answers like the SpecStream API: the request, its quote, the run, then rows over two polls and two pages."""
+
+    def __init__(self, maximum_cents=250, runnable=True, existing=None):
+        self.maximum_cents = maximum_cents
+        self.runnable = runnable
+        self.existing = existing
+        self.calls = []
+        self.polls = 0
+
+    def __call__(self, request, timeout=None):
+        url = urllib.parse.urlsplit(request.full_url)
+        body = json.loads(request.data) if request.data else None
+        self.calls.append((request.get_method(), url.path, body, dict(request.header_items())))
+        query = dict(urllib.parse.parse_qsl(url.query))
+        if url.path.startswith("/v1/capacity/requests/"):
+            if self.existing:
+                return self.reply(self.existing)
+            raise urllib.error.HTTPError(request.full_url, 404, "Not Found", {}, io.BytesIO(b"{}"))
+        if url.path == "/v1/parse":
+            return self.reply({"status": "runnable" if self.runnable else "needs_input", "ast_hash": "a" * 64, "canonical_sentence": "25 dental clinics in Lisbon"})
+        if url.path == "/v1/capacity/quotes":
+            return self.reply({"quote_id": "cqt_1", "quote_hash": "b" * 64, "maximum_cents": self.maximum_cents})
+        if url.path == "/v1/capacity/executions":
+            return self.reply({"find_id": "fnd_1", "state": "running"})
+        if url.path == "/v1/finds/fnd_1/rows":
+            if query.get("cursor") == "page-2":
+                return self.reply({"status": "completed", "rows": ROWS[1:], "next_cursor": None})
+            self.polls += 1
+            if self.polls == 1:
+                return self.reply({"status": "running", "rows": [], "next_cursor": None})
+            return self.reply({"status": "completed", "rows": ROWS[:1], "next_cursor": "page-2"})
+        raise AssertionError(f"unexpected call {request.get_method()} {url.path}")
+
+    @staticmethod
+    def reply(data):
+        return io.BytesIO(json.dumps({"data": data}).encode())
+
+    def paths(self):
+        return [path for _, path, _, _ in self.calls]
+
+
+@pytest.fixture
+def api(monkeypatch):
+    def install(**kwargs):
+        fake = FakeSpecStream(**kwargs)
+        monkeypatch.setattr("urllib.request.urlopen", fake)
+        return fake
+
+    return install
+
+
+def test_finds_a_list_within_the_maximum_and_returns_every_row(api):
+    fake = api()
+    tool = SpecStreamFindList(api_key=KEY, max_price_usd=5, poll_interval=0)
+    result = json.loads(tool.invoke({"request": "Dental clinics in Lisbon with online booking", "max_results": 25}))
+
+    assert result["status"] == "completed"
+    assert result["row_count"] == 2
+    assert result["list_link"] == "https://specstream.ai/workspace/collections/fnd_1"
+    first, second = result["rows"]
+    assert first["Organization"] == "Clínica Sorriso"
+    assert first["source_url"] == "https://sorriso.pt/marcacoes"
+    assert second["Website"] == ""
+    run = next(body for method, path, body, _ in fake.calls if path == "/v1/capacity/executions")
+    assert run["confirm_max_cents"] == 250
+    assert run["idempotency_key"].startswith("langchain-")
+
+
+def test_nothing_runs_when_the_price_is_above_the_maximum(api):
+    fake = api(maximum_cents=900)
+    result = json.loads(SpecStreamFindList(api_key=KEY, max_price_usd=5).invoke({"request": "Dental clinics in Lisbon"}))
+
+    assert result["status"] == "over_maximum"
+    assert "$9.00" in result["message"] and "$5.00" in result["message"]
+    assert "/v1/capacity/executions" not in fake.paths()
+
+
+def test_an_unclear_request_comes_back_with_how_it_was_read(api):
+    fake = api(runnable=False)
+    result = json.loads(SpecStreamFindList(api_key=KEY, max_price_usd=5).invoke({"request": "clinics"}))
+
+    assert result["status"] == "needs_edit"
+    assert "25 dental clinics in Lisbon" in result["message"]
+    assert "/v1/capacity/quotes" not in fake.paths()
+
+
+def test_the_model_cannot_set_the_price():
+    tool = SpecStreamFindList(api_key=KEY, max_price_usd=2)
+    assert set(tool.args) == {"request", "max_results"}
+
+
+def test_a_retried_step_reuses_the_run_it_already_started(api):
+    fake = api(existing={"find_id": "fnd_1", "maximum_cents": 250})
+    result = json.loads(SpecStreamFindList(api_key=KEY, max_price_usd=5, poll_interval=0).invoke({"request": "Dental clinics in Lisbon"}))
+
+    assert result["row_count"] == 2
+    assert "/v1/parse" not in fake.paths() and "/v1/capacity/executions" not in fake.paths()
+
+
+def test_reading_results_follows_every_page(api):
+    fake = api()
+    fake.polls = 1
+    result = json.loads(SpecStreamGetListResults(api_key=KEY).invoke({"list_id": "fnd_1"}))
+
+    assert [row["position"] for row in result["rows"]] == [1, 2]
+
+
+def test_the_key_goes_in_the_authorization_header_and_never_in_the_result(api):
+    fake = api()
+    output = SpecStreamFindList(api_key=KEY, max_price_usd=5, poll_interval=0).invoke({"request": "Dental clinics in Lisbon"})
+
+    headers = fake.calls[0][3]
+    assert headers["Authorization"] == f"Bearer {KEY}"
+    assert headers["User-agent"].startswith("langchain-specstream/")
+    assert KEY not in output
+
+
+def test_the_retriever_returns_one_document_per_row_with_its_source(api):
+    api()
+    docs = SpecStreamRetriever(api_key=KEY, max_price_usd=5, poll_interval=0).invoke("Dental clinics in Lisbon")
+
+    assert len(docs) == 2
+    assert docs[0].page_content == "Organization: Clínica Sorriso\nWebsite: https://sorriso.pt"
+    assert docs[0].metadata["source_url"] == "https://sorriso.pt/marcacoes"
+    assert docs[1].page_content == "Organization: Dentes de Lisboa"
+
+
+def test_the_retriever_raises_instead_of_spending_above_the_maximum(api):
+    api(maximum_cents=900)
+    with pytest.raises(SpecStreamError, match="above the maximum"):
+        SpecStreamRetriever(api_key=KEY, max_price_usd=5).invoke("Dental clinics in Lisbon")
+
+
+def test_both_tools_share_the_key(api):
+    find, results = specstream_tools(max_price_usd=5, api_key=KEY)
+    assert find.name == "specstream_find_list" and results.name == "specstream_get_list_results"
+    assert results.api_key.get_secret_value() == KEY
+
+
+def test_a_missing_key_says_where_to_get_one(monkeypatch):
+    monkeypatch.delenv("SPECSTREAM_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="SPECSTREAM_API_KEY"):
+        SpecStreamFindList(max_price_usd=5)

langchain_specstream-0.1.0/tests/test_standard.py

@@ -0,0 +1,43 @@
+"""LangChain's own standard tests for tools, run against both SpecStream tools."""
+
+from langchain_tests.unit_tests import ToolsUnitTests
+
+from langchain_specstream import SpecStreamFindList, SpecStreamGetListResults
+
+KEY = "ss_live_test_key"
+
+
+class TestFindListStandard(ToolsUnitTests):
+    @property
+    def tool_constructor(self):
+        return SpecStreamFindList
+
+    @property
+    def tool_constructor_params(self):
+        return {"api_key": KEY, "max_price_usd": 5}
+
+    @property
+    def tool_invoke_params_example(self):
+        return {"request": "Dental clinics in Lisbon with online booking", "max_results": 25}
+
+    @property
+    def init_from_env_params(self):
+        return {"SPECSTREAM_API_KEY": KEY}, {"max_price_usd": 5}, {"api_key": KEY}
+
+
+class TestGetListResultsStandard(ToolsUnitTests):
+    @property
+    def tool_constructor(self):
+        return SpecStreamGetListResults
+
+    @property
+    def tool_constructor_params(self):
+        return {"api_key": KEY}
+
+    @property
+    def tool_invoke_params_example(self):
+        return {"list_id": "fnd_gk5y3d0r97bvyz0t08zzh75kr6"}
+
+    @property
+    def init_from_env_params(self):
+        return {"SPECSTREAM_API_KEY": KEY}, {}, {"api_key": KEY}