specstream-client 1.0.0__tar.gz

specstream_client-1.0.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

specstream_client-1.0.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.

specstream_client-1.0.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: specstream-client
+Version: 1.0.0
+Summary: Python client and command line for SpecStream: ask for any list in plain words and get every match with its source, priced before anything runs.
+Project-URL: Homepage, https://specstream.ai
+Project-URL: Documentation, https://specstream.ai/docs/sdk
+Project-URL: API, https://api.specstream.ai
+Project-URL: Changelog, https://specstream.ai/changelog
+Project-URL: Repository, https://github.com/Specstreamai/specstream-tools
+Project-URL: Issues, https://github.com/Specstreamai/specstream-tools/issues
+Author-email: SpecStream <support@specstream.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,api-client,enrichment,lead-lists,live-web,mcp,monitoring,specstream,web-data
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# specstream-client
+
+Python client and command line for [SpecStream](https://specstream.ai), the live web data engine for teams and agents. Describe the list you need in plain words; SpecStream reads the web where those things live, hands back only the matches, each with the page it came from, and you pay only for the matches.
+
+The client has no dependencies and needs Python 3.12 or newer. It uses the same account, permissions, projects and balance as the workspace.
+
+```sh
+pip install specstream-client
+```
+
+The package installs the import name `specstream` and the command `specstream`.
+
+Create an API key under **Agents & API** in your SpecStream workspace and keep it in the environment:
+
+```sh
+export SPECSTREAM_API_KEY="ss_live_..."
+```
+
+## Read a request, get the price
+
+```python
+import os
+from specstream_client import Client
+
+client = Client(os.environ["SPECSTREAM_API_KEY"])
+
+read = client.compile("Open-source document-signing tools I can self-host. Include the license and latest release.")
+offer = client.quote_capacity_work({
+    "ast_hash": read["ast_hash"],
+    "operation": "find",
+    "requested_units": read["ast"]["limit"]["max"],
+})
+print(offer["maximum_cents"], offer["expires_at"])
+```
+
+Nothing has run yet. Review the quote: what will be found, the facts that come back, the most the work can cost, and when the price expires. A price lasts 30 minutes.
+
+## Approve it, then read the results
+
+After a person approves, send the approved maximum in cents and a request key you saved first:
+
+```python
+run = client.authorize_capacity_work({
+    "quote_id": offer["quote_id"],
+    "quote_hash": offer["quote_hash"],
+    "confirm_max_cents": approved_maximum_cents,
+    "idempotency_key": saved_request_key,
+})
+find_id = run["find_id"]
+
+page = client.rows(find_id)
+for row in page["rows"]:
+    print(row)
+```
+
+If the response is lost, `get_capacity_request(saved_request_key)` returns the same work. Keep the original key when you retry, and you will not pay twice. `get_find` reports progress, and `rows` pages through results with `next_cursor`. Reading, exporting and sharing results you own cost nothing.
+
+`authorize_capacity_work` refuses to send anything unless the quote, its signature, the maximum and the key are all present.
+
+## More than a first request
+
+- `quote_capacity_work` also prices `extend` (more results), `add_facts` and `refresh` (a recheck, at half price) on a finished run. Pass the original `parent_find_id`.
+- `spec_options(kind)` lists the facts you can ask for, per kind of thing. `edit_spec` changes a request without rereading it.
+- `create_capacity_schedule` keeps a request current, hourly to yearly, inside per-run and per-period limits.
+- `export` and `download_export` give CSV, XLSX, JSON or HTML. `create_customer_webhook` sends signed events.
+- Projects, members, shares and starred items have their own methods.
+
+Kinds of thing include local businesses, companies, people, creators, products, apps, job postings, papers, clinical trials, grants, tenders, regulations, vulnerabilities, software packages, repositories, datasets, books and podcasts.
+
+## Command line
+
+```sh
+specstream compile "Food banks in Texas, with their annual revenue."
+specstream get-capacity-balance
+specstream quote-capacity-work --body quote-request.json
+specstream authorize-capacity-work --body approved-execution.json
+specstream rows --find-id FIND_ID
+```
+
+`--body` takes a JSON file or `-` for stdin. Every command's `--help` describes its parameters. The command line exposes the same operations as the client.
+
+## Pricing
+
+New accounts start with $10 of work for 30 days, no card. A delivered result costs 10 cents, 30 cents or $1 depending on how many facts it carries. No result, no charge. Rechecks cost half. People and agents share one balance. See [pricing](https://specstream.ai/pricing).
+
+## Links
+
+- [SDK docs](https://specstream.ai/docs/sdk) and [API docs](https://specstream.ai/docs/api)
+- [Source and issues](https://github.com/Specstreamai/specstream-tools)
+- [TypeScript client](https://www.npmjs.com/package/@specstream/sdk)
+- Support: support@specstream.ai
+
+MIT license.

specstream_client-1.0.0/README.md

@@ -0,0 +1,93 @@
+# specstream-client
+
+Python client and command line for [SpecStream](https://specstream.ai), the live web data engine for teams and agents. Describe the list you need in plain words; SpecStream reads the web where those things live, hands back only the matches, each with the page it came from, and you pay only for the matches.
+
+The client has no dependencies and needs Python 3.12 or newer. It uses the same account, permissions, projects and balance as the workspace.
+
+```sh
+pip install specstream-client
+```
+
+The package installs the import name `specstream` and the command `specstream`.
+
+Create an API key under **Agents & API** in your SpecStream workspace and keep it in the environment:
+
+```sh
+export SPECSTREAM_API_KEY="ss_live_..."
+```
+
+## Read a request, get the price
+
+```python
+import os
+from specstream_client import Client
+
+client = Client(os.environ["SPECSTREAM_API_KEY"])
+
+read = client.compile("Open-source document-signing tools I can self-host. Include the license and latest release.")
+offer = client.quote_capacity_work({
+    "ast_hash": read["ast_hash"],
+    "operation": "find",
+    "requested_units": read["ast"]["limit"]["max"],
+})
+print(offer["maximum_cents"], offer["expires_at"])
+```
+
+Nothing has run yet. Review the quote: what will be found, the facts that come back, the most the work can cost, and when the price expires. A price lasts 30 minutes.
+
+## Approve it, then read the results
+
+After a person approves, send the approved maximum in cents and a request key you saved first:
+
+```python
+run = client.authorize_capacity_work({
+    "quote_id": offer["quote_id"],
+    "quote_hash": offer["quote_hash"],
+    "confirm_max_cents": approved_maximum_cents,
+    "idempotency_key": saved_request_key,
+})
+find_id = run["find_id"]
+
+page = client.rows(find_id)
+for row in page["rows"]:
+    print(row)
+```
+
+If the response is lost, `get_capacity_request(saved_request_key)` returns the same work. Keep the original key when you retry, and you will not pay twice. `get_find` reports progress, and `rows` pages through results with `next_cursor`. Reading, exporting and sharing results you own cost nothing.
+
+`authorize_capacity_work` refuses to send anything unless the quote, its signature, the maximum and the key are all present.
+
+## More than a first request
+
+- `quote_capacity_work` also prices `extend` (more results), `add_facts` and `refresh` (a recheck, at half price) on a finished run. Pass the original `parent_find_id`.
+- `spec_options(kind)` lists the facts you can ask for, per kind of thing. `edit_spec` changes a request without rereading it.
+- `create_capacity_schedule` keeps a request current, hourly to yearly, inside per-run and per-period limits.
+- `export` and `download_export` give CSV, XLSX, JSON or HTML. `create_customer_webhook` sends signed events.
+- Projects, members, shares and starred items have their own methods.
+
+Kinds of thing include local businesses, companies, people, creators, products, apps, job postings, papers, clinical trials, grants, tenders, regulations, vulnerabilities, software packages, repositories, datasets, books and podcasts.
+
+## Command line
+
+```sh
+specstream compile "Food banks in Texas, with their annual revenue."
+specstream get-capacity-balance
+specstream quote-capacity-work --body quote-request.json
+specstream authorize-capacity-work --body approved-execution.json
+specstream rows --find-id FIND_ID
+```
+
+`--body` takes a JSON file or `-` for stdin. Every command's `--help` describes its parameters. The command line exposes the same operations as the client.
+
+## Pricing
+
+New accounts start with $10 of work for 30 days, no card. A delivered result costs 10 cents, 30 cents or $1 depending on how many facts it carries. No result, no charge. Rechecks cost half. People and agents share one balance. See [pricing](https://specstream.ai/pricing).
+
+## Links
+
+- [SDK docs](https://specstream.ai/docs/sdk) and [API docs](https://specstream.ai/docs/api)
+- [Source and issues](https://github.com/Specstreamai/specstream-tools)
+- [TypeScript client](https://www.npmjs.com/package/@specstream/sdk)
+- Support: support@specstream.ai
+
+MIT license.

specstream_client-1.0.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "specstream-client"
+version = "1.0.0"
+description = "Python client and command line for SpecStream: ask for any list in plain words and get every match with its source, priced before anything runs."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "SpecStream", email = "support@specstream.ai" }]
+keywords = [
+  "specstream",
+  "web-data",
+  "live-web",
+  "lead-lists",
+  "enrichment",
+  "monitoring",
+  "mcp",
+  "ai-agents",
+  "api-client",
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://specstream.ai"
+Documentation = "https://specstream.ai/docs/sdk"
+API = "https://api.specstream.ai"
+Changelog = "https://specstream.ai/changelog"
+Repository = "https://github.com/Specstreamai/specstream-tools"
+Issues = "https://github.com/Specstreamai/specstream-tools/issues"
+
+[project.scripts]
+specstream = "specstream_client.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["specstream_client"]
+
+[tool.hatch.build.targets.sdist]
+include = ["specstream_client", "tests", "README.md", "LICENSE"]

specstream_client-1.0.0/specstream_client/__init__.py

@@ -0,0 +1,14 @@
+"""SPECSTREAM Python SDK generated against finder.cross-source.v1 OpenAPI."""
+
+from specstream_client.client import DEFAULT_BASE_URL, Client, SpecstreamError
+from specstream_client.families import FAMILIES, FAMILY_SET, assert_family
+
+__all__ = [
+    "Client",
+    "DEFAULT_BASE_URL",
+    "FAMILIES",
+    "FAMILY_SET",
+    "SpecstreamError",
+    "assert_family",
+]
+__version__ = "1.0.0"

specstream_client-1.0.0/specstream_client/__main__.py

@@ -0,0 +1,3 @@
+from specstream_client.cli import main
+
+raise SystemExit(main())

specstream_client-1.0.0/specstream_client/authorization.py

@@ -0,0 +1,32 @@
+"""Require an explicit signed-work authorization before any client HTTP call."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+def require_work_authorization(value: Any) -> None:
+    required = {"quote_id", "quote_hash", "idempotency_key", "confirm_max_cents"}
+    if (
+        not isinstance(value, dict)
+        or not required <= value.keys()
+        or set(value) - required - {"authority_id"}
+    ):
+        raise ValueError(
+            "Provide the exact quote identity, signature, maximum cents and request key"
+        )
+    if not isinstance(value["quote_id"], str) or not value["quote_id"]:
+        raise ValueError("An explicit quote identity is required")
+    if not isinstance(value["quote_hash"], str) or not re.fullmatch(
+        r"[0-9a-f]{64}", value["quote_hash"]
+    ):
+        raise ValueError("The reviewed quote signature is required")
+    key = value["idempotency_key"]
+    if not isinstance(key, str) or not 8 <= len(key) <= 128:
+        raise ValueError("Use a stable request key containing 8 to 128 characters")
+    maximum = value["confirm_max_cents"]
+    if type(maximum) is not int or maximum < 0:
+        raise ValueError("The approved maximum must be an explicit nonnegative integer in cents")
+    if value.get("authority_id") is not None and not isinstance(value["authority_id"], str):
+        raise ValueError("Authority must be an explicit existing identifier")

specstream_client-1.0.0/specstream_client/cli.py

@@ -0,0 +1,139 @@
+"""SPECSTREAM console: inspect a Spec, prepare a Find, and read its Delivery."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Sequence
+from typing import Any, TextIO
+
+from specstream_client.client import DEFAULT_BASE_URL, Client, SpecstreamError
+from specstream_client.families import FAMILIES
+from specstream_client.lifecycle_commands import COMMANDS
+
+PROG = "specstream"
+DESC = (
+    "The web. To your spec. Compile the request, quote-capacity-work, then "
+    "authorize-capacity-work with the exact approved maximum and a stable key. "
+    "Read the same work, evidence and balance from every interface. "
+)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog=PROG, description=DESC)
+    parser.add_argument(
+        "--base-url", default=os.environ.get("SPECSTREAM_BASE_URL", DEFAULT_BASE_URL)
+    )
+    parser.add_argument("--api-key", default=os.environ.get("SPECSTREAM_API_KEY", ""))
+    sub = parser.add_subparsers(dest="cmd")
+    compile_cmd = sub.add_parser("compile", help="Interpret a brief as an editable Spec")
+    compile_cmd.add_argument("q")
+    compile_cmd.add_argument("--locale", default="en-US")
+    edit = sub.add_parser(
+        "edit-spec", help="Validate exact edited AST JSON, including required facts"
+    )
+    edit.add_argument(
+        "--ast", required=True, type=argparse.FileType("r"), help="AST JSON file or -"
+    )
+    options = sub.add_parser("spec-options", help="Read supported conditions and return facts")
+    options.add_argument("target", choices=FAMILIES)
+    for command, help_text in (
+        ("get", "Inspect an owned Find"),
+        ("rows", "Read Matches with evidence"),
+        ("revisit", "Read one page of retained-target outcomes"),
+        ("export", "Request a Delivery download link"),
+    ):
+        item = sub.add_parser(command, help=help_text)
+        item.add_argument("--find-id", required=True)
+        if command == "rows":
+            item.add_argument("--cursor", default=None)
+            item.add_argument("--limit", type=int, default=100)
+        if command == "revisit":
+            item.add_argument("--after", default="")
+            item.add_argument("--limit", type=int, default=100)
+        if command == "export":
+            item.add_argument("--format", default="csv", choices=("csv", "xlsx", "json", "html"))
+    sub.add_parser("families", help="Print supported public targets")
+    for name, contract in COMMANDS.items():
+        command = sub.add_parser(name, help=contract["summary"])
+        for argument in contract["arguments"]:
+            command.add_argument("--" + argument.replace("_", "-"), required=True)
+        if contract["body"]:
+            command.add_argument(
+                "--request",
+                required=contract["body_required"],
+                type=argparse.FileType("r"),
+                help="Exact request JSON file or - for stdin",
+            )
+        for parameter, kind in contract["query"].items():
+            options: dict[str, Any] = {"default": None}
+            if kind == "boolean":
+                options["action"] = argparse.BooleanOptionalAction
+            else:
+                options["type"] = int if kind == "integer" else str
+            command.add_argument("--" + parameter.replace("_", "-"), **options)
+    return parser
+
+
+def _dump(payload: Any, out: TextIO) -> None:
+    json.dump(payload, out, indent=2, sort_keys=True)
+    out.write("\n")
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    out: TextIO | None = None,
+    err: TextIO | None = None,
+) -> int:
+    stdout, stderr = out or sys.stdout, err or sys.stderr
+    parser = _parser()
+    ns = parser.parse_args(list(argv) if argv is not None else None)
+    if not ns.cmd:
+        parser.print_help(stdout)
+        return 0
+    try:
+        if ns.cmd == "families":
+            result: Any = list(FAMILIES)
+        else:
+            client = Client(api_key=ns.api_key, base_url=ns.base_url)
+            if ns.cmd in COMMANDS:
+                contract = COMMANDS[ns.cmd]
+                arguments = [getattr(ns, argument) for argument in contract["arguments"]]
+                if contract["body"]:
+                    body = None
+                    if ns.request is not None:
+                        with ns.request as source:
+                            body = json.load(source)
+                        if not isinstance(body, dict):
+                            raise ValueError("Request must be a JSON object")
+                    arguments.append(body)
+                options = {name: getattr(ns, name) for name in contract["query"]}
+                result = getattr(client, contract["method"])(*arguments, **options)
+            elif ns.cmd == "compile":
+                result = client.compile(ns.q, locale=ns.locale)
+            elif ns.cmd == "edit-spec":
+                with ns.ast as source:
+                    ast = json.load(source)
+                if not isinstance(ast, dict):
+                    raise ValueError("AST must be a JSON object")
+                result = client.edit_spec(ast)
+            elif ns.cmd == "spec-options":
+                result = client.spec_options(ns.target)
+            elif ns.cmd == "get":
+                result = client.get_find(ns.find_id)
+            elif ns.cmd == "rows":
+                result = client.rows(ns.find_id, cursor=ns.cursor, limit=ns.limit)
+            elif ns.cmd == "revisit":
+                result = client.revisit(ns.find_id, after=ns.after, limit=ns.limit)
+            else:
+                result = client.export(ns.find_id, format=ns.format)
+        _dump(result, stdout)
+        return 0
+    except SpecstreamError as exc:
+        print(str(exc), file=stderr)
+        return 1
+    except (ValueError, OSError) as exc:
+        print(str(exc), file=stderr)
+        return 2