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.
Project-URL: Homepage, https://specstream.ai
Project-URL: API, https://api.specstream.ai
Author-email: SpecStream <support@specstream.ai>
License: Proprietary
Keywords: app_listing,creator,cross-source,grant,job_posting,local_business,organization,scholarly_work,specstream,storefront_product,tender
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.12
Description-Content-Type: text/plain

SpecStream Python and CLI

Find records in everyday language, work with saved results, and connect SpecStream
to your own code. The client uses the same account, permissions, projects, and
balance as the workspace.

Install the downloaded wheel with pip, or install this package directory. Public
package downloads and instructions are at https://specstream.ai/docs/sdk.
Set SPECSTREAM_API_KEY in your environment to a key from Agents & API.

Interpret a request and get a quote:

    from specstream_client import Client
    import os

    client = Client(os.environ["SPECSTREAM_API_KEY"])
    parsed = client.compile("Open-source document-signing tools I can self-host. Include the license and latest release.")
    offer = client.quote_capacity_work({
        "ast_hash": parsed["ast_hash"], "operation": "find",
        "requested_units": parsed["ast"]["limit"]["max"],
    })
    print(offer)

Review the quote's scope, useful minimum, completion terms, expiry, and maximum.
After approval, submit the approved maximum in cents and a saved unique request key:

    result = client.authorize_capacity_work({
        "quote_id": offer["quote_id"], "quote_hash": offer["quote_hash"],
        "confirm_max_cents": approved_maximum_cents,
        "idempotency_key": persisted_request_key,
    })

If the response is uncertain, get_capacity_request(persisted_request_key) recovers
that same work. Keep the original key when retrying. get_capacity_quote retrieves
the original quote. get_find reports progress; list_find_rows retrieves records.
Use get_delivery and export_find to retrieve saved results without buying them again.

Work beyond the first request

Use spec_options to inspect the supported fields for a record type. Save requests
with create_spec, browse revisions with list_spec_revisions, and inspect their
connections with get_find_lineage. Projects organize work and member permissions.
Request links and result shares have separate access controls.

quote_capacity_work also accepts extend, add_facts, and refresh with the original
parent_find_id and exact revised request where required. create_capacity_schedule
accepts scope, cadence, validity, and spending limits. list_capacity_occurrences
shows what ran and which occurrences were blocked or missed.

Supported types include companies, local businesses, creators, products, apps, jobs,
papers, tenders, grants, software repositories, packages, datasets, clinical trials,
regulatory documents, vulnerabilities, books, and podcasts. Supported fields vary
by type. Missing and conflicting information stays explicit, with observation times
and source evidence available in saved results.

Command line

    specstream compile "your request"
    specstream get-capacity-catalog
    specstream get-capacity-balance
    specstream quote-capacity-work --body quote-request.json
    specstream authorize-capacity-work --body approved-execution.json
    specstream get-capacity-request --help
    specstream create-capacity-schedule --body approved-schedule.json

--body accepts a JSON file or '-' for stdin. Each command's --help describes its
path and query parameters. The CLI exposes the same public operations as the client.
Funding and membership administration require an owner browser session.

Pricing

Start with $10 of work for 30 days, once, with no card required.
Top-ups start at $10 and do not expire. Pro costs $19/month with $19 of work, Scale $99/month with $99 of work;
Team costs $499/month with $499 of work. EU visitors see the same numbers in euros.
An account pays in the currency of its first payment. Upgrades apply after payment,
prorated; downgrades take effect at renewal. No seat fees or automatic overages.
Every plan has the same rates; Pro adds schedules and sheet sync, Scale adds CRM sync.

Matching rows cost 10 cents, 30 cents or $1 depending on the details.
No result, no charge. Rechecks cost half. People and agents share one work balance.

Use quote_capacity_work and authorize_capacity_work for new integrations.
Older client method names remain for compatibility.

Documentation: https://specstream.ai/docs/api
