specstream-client 1.2.0__tar.gz → 1.3.0__tar.gz

{specstream_client-1.2.0 → specstream_client-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: specstream-client
-Version: 1.2.0
+Version: 1.3.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
@@ -29,9 +29,12 @@ Description-Content-Type: text/markdown
 
 `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.
+Python client and command line for [SpecStream](https://specstream.ai), the live web data engine. One platform to build, search, extract, enrich, map, and monitor data across the entire web.
 
-Source URL and read time on every value.
+Ask for any dataset in plain words, and SpecStream builds it from the entire live web: every match found, extracted and enriched into structured records, then monitored for change.
+
+- Source URL and read time on every value.
+- You pay for each row delivered.
 
 The client has no dependencies and needs Python 3.12 or newer. It uses the same account, permissions, projects and balance as the workspace.
 
@@ -92,7 +95,7 @@ If the response is lost, `get_capacity_request(saved_request_key)` returns the s
 
 - `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.
+- `create_capacity_schedule` keeps a request up to date, 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.
 
@@ -101,7 +104,7 @@ Kinds of thing include local businesses, companies, people, creators, products,
 ## Command line
 
 ```sh
-specstream compile "Food banks in Texas, with their annual revenue."
+specstream compile "Open-source vector databases on GitHub with more than 5,000 stars, with their license."
 specstream get-capacity-balance
 specstream quote-capacity-work --body quote-request.json
 specstream authorize-capacity-work --body approved-execution.json
@@ -112,7 +115,7 @@ specstream rows --find-id FIND_ID
 
 ## 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).
+New accounts start with $10 of credit for 30 days, no card. A delivered result costs 5 cents, 15 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
 

{specstream_client-1.2.0 → specstream_client-1.3.0}/README.md

@@ -2,9 +2,12 @@
 
 `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.
+Python client and command line for [SpecStream](https://specstream.ai), the live web data engine. One platform to build, search, extract, enrich, map, and monitor data across the entire web.
 
-Source URL and read time on every value.
+Ask for any dataset in plain words, and SpecStream builds it from the entire live web: every match found, extracted and enriched into structured records, then monitored for change.
+
+- Source URL and read time on every value.
+- You pay for each row delivered.
 
 The client has no dependencies and needs Python 3.12 or newer. It uses the same account, permissions, projects and balance as the workspace.
 
@@ -65,7 +68,7 @@ If the response is lost, `get_capacity_request(saved_request_key)` returns the s
 
 - `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.
+- `create_capacity_schedule` keeps a request up to date, 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.
 
@@ -74,7 +77,7 @@ Kinds of thing include local businesses, companies, people, creators, products,
 ## Command line
 
 ```sh
-specstream compile "Food banks in Texas, with their annual revenue."
+specstream compile "Open-source vector databases on GitHub with more than 5,000 stars, with their license."
 specstream get-capacity-balance
 specstream quote-capacity-work --body quote-request.json
 specstream authorize-capacity-work --body approved-execution.json
@@ -85,7 +88,7 @@ specstream rows --find-id FIND_ID
 
 ## 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).
+New accounts start with $10 of credit for 30 days, no card. A delivered result costs 5 cents, 15 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
 

{specstream_client-1.2.0 → specstream_client-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "specstream-client"
-version = "1.2.0"
+version = "1.3.0"
 description = "Python client for building lead lists and company lists from the live web. Every match comes with its source, priced before it runs."
 readme = "README.md"
 requires-python = ">=3.12"

{specstream_client-1.2.0 → specstream_client-1.3.0}/specstream_client/__init__.py

@@ -11,4 +11,4 @@ __all__ = [
     "SpecstreamError",
     "assert_family",
 ]
-__version__ = "1.2.0"
+__version__ = "1.3.0"

{specstream_client-1.2.0 → specstream_client-1.3.0}/specstream_client/client.py

@@ -15,7 +15,7 @@ from specstream_client.authorization import require_work_authorization
 from specstream_client.families import FAMILIES
 
 DEFAULT_BASE_URL = "https://api.specstream.ai"
-USER_AGENT = "specstream-python/1.2.0"
+USER_AGENT = "specstream-python/1.3.0"
 
 OpenFn = Callable[[urllib.request.Request, float], Any]
 
@@ -268,6 +268,64 @@ class Client:
             path += "?" + encoded
         return self._request("GET", path, None)
 
+    def web_search(self, *, q: str, passages: bool | None = None) -> dict[str, Any]:
+        """
+        Fast search: answer a question from the live web in seconds, each value with its source.
+        """
+        path = "/v1/web-search"
+        query: dict[str, Any] = {
+            "q": q,
+            "passages": passages,
+        }
+        encoded = urlencode(
+            {
+                key: str(value).lower() if isinstance(value, bool) else value
+                for key, value in query.items()
+                if value is not None
+            }
+        )
+        if encoded:
+            path += "?" + encoded
+        return self._request("GET", path, None)
+
+    def extract_pages(self, request: dict[str, Any]) -> dict[str, Any]:
+        """
+        Read up to 20 pages live: each page's main text as Markdown or plain text, its title and
+        its published date. Only a page read is charged.
+        """
+        path = "/v1/extract"
+        return self._request("POST", path, request)
+
+    def web_search_answers(
+        self,
+        *,
+        q: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> dict[str, Any]:
+        """List your web search history: each question, its answer and its sources, newest first."""
+        path = "/v1/web-search/answers"
+        query: dict[str, Any] = {
+            "q": q,
+            "limit": limit,
+            "cursor": cursor,
+        }
+        encoded = urlencode(
+            {
+                key: str(value).lower() if isinstance(value, bool) else value
+                for key, value in query.items()
+                if value is not None
+            }
+        )
+        if encoded:
+            path += "?" + encoded
+        return self._request("GET", path, None)
+
+    def web_search_answer(self, answer_id: str) -> dict[str, Any]:
+        """Open one kept web search answer as it was given."""
+        path = f"/v1/web-search/answers/{quote_path(answer_id, safe='')}"
+        return self._request("GET", path, None)
+
     def workspace_list_notifications(
         self,
         *,
@@ -710,6 +768,7 @@ class Client:
         project_id: str | None = None,
         cursor: str | None = None,
         limit: int | None = None,
+        format: str | None = None,
     ) -> dict[str, Any]:
         """Read where the request asked with this key stands and the rows it found so far."""
         path = f"/v1/capacity/requests/{quote_path(request_key, safe='')}/rows"
@@ -717,6 +776,7 @@ class Client:
             "project_id": project_id,
             "cursor": cursor,
             "limit": limit,
+            "format": format,
         }
         encoded = urlencode(
             {

{specstream_client-1.2.0 → specstream_client-1.3.0}/specstream_client/lifecycle_commands.py

@@ -28,6 +28,34 @@ COMMANDS = {'get-vocabulary': {'method': 'get_vocabulary',
                       'body_required': False,
                       'query': {'q': 'string', 'limit': 'integer', 'cursor': 'string'},
                       'summary': 'Search the requests, lists and sources you can open'},
+ 'web-search': {'method': 'web_search',
+                'arguments': [],
+                'body': False,
+                'body_required': False,
+                'query': {'q': 'string', 'passages': 'boolean'},
+                'summary': 'Fast search: answer a question from the live web in seconds, each '
+                           'value with its source'},
+ 'extract-pages': {'method': 'extract_pages',
+                   'arguments': [],
+                   'body': True,
+                   'body_required': True,
+                   'query': {},
+                   'summary': "Read up to 20 pages live: each page's main text as Markdown or "
+                              'plain text, its title and its published date. Only a page read is '
+                              'charged'},
+ 'web-search-answers': {'method': 'web_search_answers',
+                        'arguments': [],
+                        'body': False,
+                        'body_required': False,
+                        'query': {'q': 'string', 'limit': 'integer', 'cursor': 'string'},
+                        'summary': 'List your web search history: each question, its answer and '
+                                   'its sources, newest first'},
+ 'web-search-answer': {'method': 'web_search_answer',
+                       'arguments': ['answer_id'],
+                       'body': False,
+                       'body_required': False,
+                       'query': {},
+                       'summary': 'Open one kept web search answer as it was given'},
  'workspace-list-notifications': {'method': 'workspace_list_notifications',
                                   'arguments': [],
                                   'body': False,
@@ -342,7 +370,8 @@ COMMANDS = {'get-vocabulary': {'method': 'get_vocabulary',
                                'body_required': False,
                                'query': {'project_id': 'string',
                                          'cursor': 'string',
-                                         'limit': 'integer'},
+                                         'limit': 'integer',
+                                         'format': 'string'},
                                'summary': 'Read where the request asked with this key stands and '
                                           'the rows it found so far'},
  'get-capacity-execution': {'method': 'get_capacity_execution',

{specstream_client-1.2.0 → specstream_client-1.3.0}/tests/test_client.py

@@ -95,3 +95,23 @@ class ClientTests(unittest.TestCase):
         self.assertEqual(client.authorize_capacity_work(approval)["find_id"], "fnd_fixture")
         self.assertEqual(client.get_capacity_request("stable-review-001")["find_id"], "fnd_fixture")
         self.assertFalse(any("/funding" in path or "/run" in path for _, path, _ in calls))
+
+    def test_web_search_returns_the_answers_kind_and_sources(self):
+        page = {
+            "request_id": "call-1",
+            "kind": "list",
+            "answer": None,
+            "rows": [{"name": "A", "page": "https://example.org/a", "sources": [0]}],
+            "sources": [{"url": "https://example.org/a", "cited": True}],
+        }
+        urls = []
+
+        def opener(request, timeout):
+            urls.append((request.get_method(), request.full_url))
+            return _FakeResponse(page)
+
+        found = Client("fixture-key", opener=opener).web_search(q="roasters in Lyon")
+        self.assertEqual(urls, [("GET", urls[0][1])])
+        self.assertTrue(urls[0][1].endswith("/v1/web-search?q=roasters+in+Lyon"))
+        self.assertEqual((found["kind"], found["sources"]), (page["kind"], page["sources"]))
+        self.assertEqual(found["rows"][0]["sources"], [0])