Metadata-Version: 2.5
Name: specstream-client
Version: 1.2.0
Summary: Python client for building lead lists and company lists from the live web. Every match comes with its source, priced before it 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/specstream/specstream-tools
Project-URL: Issues, https://github.com/specstream/specstream-tools/issues
Author-email: SpecStream <support@specstream.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,api-client,company-list,enrichment,grants,lead-generation,lead-list,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

`pip install specstream-client` (the `specstream` package on PyPI is a different project)

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, and you pay for each result delivered.

Source URL and read time on every value.

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/specstream/specstream-tools)
- [TypeScript client](https://www.npmjs.com/package/@specstream/sdk)
- Support: support@specstream.ai

MIT license.
