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.
