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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. {specstream_client-1.1.0 → specstream_client-1.2.0}/PKG-INFO +11 -7
  2. {specstream_client-1.1.0 → specstream_client-1.2.0}/README.md +6 -2
  3. {specstream_client-1.1.0 → specstream_client-1.2.0}/pyproject.toml +8 -4
  4. {specstream_client-1.1.0 → specstream_client-1.2.0}/specstream_client/__init__.py +1 -1
  5. {specstream_client-1.1.0 → specstream_client-1.2.0}/specstream_client/cli.py +3 -1
  6. {specstream_client-1.1.0 → specstream_client-1.2.0}/specstream_client/client.py +41 -1
  7. {specstream_client-1.1.0 → specstream_client-1.2.0}/specstream_client/families.py +7 -5
  8. {specstream_client-1.1.0 → specstream_client-1.2.0}/specstream_client/lifecycle_commands.py +23 -0
  9. {specstream_client-1.1.0 → specstream_client-1.2.0}/tests/test_client.py +7 -1
  10. {specstream_client-1.1.0 → specstream_client-1.2.0}/.gitignore +0 -0
  11. {specstream_client-1.1.0 → specstream_client-1.2.0}/LICENSE +0 -0
  12. {specstream_client-1.1.0 → specstream_client-1.2.0}/specstream_client/__main__.py +0 -0
  13. {specstream_client-1.1.0 → specstream_client-1.2.0}/specstream_client/authorization.py +0 -0
  14. {specstream_client-1.1.0 → specstream_client-1.2.0}/specstream_client/py.typed +0 -0
  15. {specstream_client-1.1.0 → specstream_client-1.2.0}/tests/__init__.py +0 -0
  16. {specstream_client-1.1.0 → specstream_client-1.2.0}/tests/test_cli.py +0 -0
  17. {specstream_client-1.1.0 → specstream_client-1.2.0}/tests/test_convergence.py +0 -0
  18. {specstream_client-1.1.0 → specstream_client-1.2.0}/tests/test_http_boundary.py +0 -0
  19. {specstream_client-1.1.0 → specstream_client-1.2.0}/tests/test_m16_exports.py +0 -0
@@ -1,17 +1,17 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: specstream-client
3
- Version: 1.1.0
4
- 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.
3
+ Version: 1.2.0
4
+ Summary: Python client for building lead lists and company lists from the live web. Every match comes with its source, priced before it runs.
5
5
  Project-URL: Homepage, https://specstream.ai
6
6
  Project-URL: Documentation, https://specstream.ai/docs/sdk
7
7
  Project-URL: API, https://api.specstream.ai
8
8
  Project-URL: Changelog, https://specstream.ai/changelog
9
- Project-URL: Repository, https://github.com/Specstreamai/specstream-tools
10
- Project-URL: Issues, https://github.com/Specstreamai/specstream-tools/issues
9
+ Project-URL: Repository, https://github.com/specstream/specstream-tools
10
+ Project-URL: Issues, https://github.com/specstream/specstream-tools/issues
11
11
  Author-email: SpecStream <support@specstream.ai>
12
12
  License-Expression: MIT
13
13
  License-File: LICENSE
14
- Keywords: ai-agents,api-client,enrichment,lead-lists,live-web,mcp,monitoring,specstream,web-data
14
+ Keywords: ai-agents,api-client,company-list,enrichment,grants,lead-generation,lead-list,lead-lists,live-web,mcp,monitoring,specstream,web-data
15
15
  Classifier: Development Status :: 5 - Production/Stable
16
16
  Classifier: Environment :: Console
17
17
  Classifier: Intended Audience :: Developers
@@ -27,7 +27,11 @@ Description-Content-Type: text/markdown
27
27
 
28
28
  # specstream-client
29
29
 
30
- 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.
30
+ `pip install specstream-client` (the `specstream` package on PyPI is a different project)
31
+
32
+ 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.
33
+
34
+ Source URL and read time on every value.
31
35
 
32
36
  The client has no dependencies and needs Python 3.12 or newer. It uses the same account, permissions, projects and balance as the workspace.
33
37
 
@@ -113,7 +117,7 @@ New accounts start with $10 of work for 30 days, no card. A delivered result cos
113
117
  ## Links
114
118
 
115
119
  - [SDK docs](https://specstream.ai/docs/sdk) and [API docs](https://specstream.ai/docs/api)
116
- - [Source and issues](https://github.com/Specstreamai/specstream-tools)
120
+ - [Source and issues](https://github.com/specstream/specstream-tools)
117
121
  - [TypeScript client](https://www.npmjs.com/package/@specstream/sdk)
118
122
  - Support: support@specstream.ai
119
123
 
@@ -1,6 +1,10 @@
1
1
  # specstream-client
2
2
 
3
- 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.
3
+ `pip install specstream-client` (the `specstream` package on PyPI is a different project)
4
+
5
+ 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.
6
+
7
+ Source URL and read time on every value.
4
8
 
5
9
  The client has no dependencies and needs Python 3.12 or newer. It uses the same account, permissions, projects and balance as the workspace.
6
10
 
@@ -86,7 +90,7 @@ New accounts start with $10 of work for 30 days, no card. A delivered result cos
86
90
  ## Links
87
91
 
88
92
  - [SDK docs](https://specstream.ai/docs/sdk) and [API docs](https://specstream.ai/docs/api)
89
- - [Source and issues](https://github.com/Specstreamai/specstream-tools)
93
+ - [Source and issues](https://github.com/specstream/specstream-tools)
90
94
  - [TypeScript client](https://www.npmjs.com/package/@specstream/sdk)
91
95
  - Support: support@specstream.ai
92
96
 
@@ -1,7 +1,7 @@
1
1
  [project]
2
2
  name = "specstream-client"
3
- version = "1.1.0"
4
- 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."
3
+ version = "1.2.0"
4
+ description = "Python client for building lead lists and company lists from the live web. Every match comes with its source, priced before it runs."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
7
7
  license = "MIT"
@@ -17,6 +17,10 @@ keywords = [
17
17
  "mcp",
18
18
  "ai-agents",
19
19
  "api-client",
20
+ "lead-generation",
21
+ "lead-list",
22
+ "company-list",
23
+ "grants",
20
24
  ]
21
25
  classifiers = [
22
26
  "Development Status :: 5 - Production/Stable",
@@ -37,8 +41,8 @@ Homepage = "https://specstream.ai"
37
41
  Documentation = "https://specstream.ai/docs/sdk"
38
42
  API = "https://api.specstream.ai"
39
43
  Changelog = "https://specstream.ai/changelog"
40
- Repository = "https://github.com/Specstreamai/specstream-tools"
41
- Issues = "https://github.com/Specstreamai/specstream-tools/issues"
44
+ Repository = "https://github.com/specstream/specstream-tools"
45
+ Issues = "https://github.com/specstream/specstream-tools/issues"
42
46
 
43
47
  [project.scripts]
44
48
  specstream = "specstream_client.cli:main"
@@ -11,4 +11,4 @@ __all__ = [
11
11
  "SpecstreamError",
12
12
  "assert_family",
13
13
  ]
14
- __version__ = "1.1.0"
14
+ __version__ = "1.2.0"
@@ -38,7 +38,9 @@ def _parser() -> argparse.ArgumentParser:
38
38
  "--ast", required=True, type=argparse.FileType("r"), help="AST JSON file or -"
39
39
  )
40
40
  options = sub.add_parser("spec-options", help="Read supported conditions and return facts")
41
- options.add_argument("target", choices=FAMILIES)
41
+ options.add_argument(
42
+ "target", help="A record kind, for example: " + ", ".join(FAMILIES[:4])
43
+ )
42
44
  for command, help_text in (
43
45
  ("get", "Inspect an owned Find"),
44
46
  ("rows", "Read Matches with evidence"),
@@ -15,7 +15,7 @@ from specstream_client.authorization import require_work_authorization
15
15
  from specstream_client.families import FAMILIES
16
16
 
17
17
  DEFAULT_BASE_URL = "https://api.specstream.ai"
18
- USER_AGENT = "specstream-python/1.1.0"
18
+ USER_AGENT = "specstream-python/1.2.0"
19
19
 
20
20
  OpenFn = Callable[[urllib.request.Request, float], Any]
21
21
 
@@ -676,6 +676,11 @@ class Client:
676
676
  require_work_authorization(request)
677
677
  return self._request("POST", path, request)
678
678
 
679
+ def start_capacity_request(self, request: dict[str, Any]) -> dict[str, Any]:
680
+ """Ask for a list in plain words and run it within a maximum price, answering at once."""
681
+ path = "/v1/capacity/requests"
682
+ return self._request("POST", path, request)
683
+
679
684
  def get_capacity_request(
680
685
  self,
681
686
  request_key: str,
@@ -698,6 +703,32 @@ class Client:
698
703
  path += "?" + encoded
699
704
  return self._request("GET", path, None)
700
705
 
706
+ def get_capacity_request_rows(
707
+ self,
708
+ request_key: str,
709
+ *,
710
+ project_id: str | None = None,
711
+ cursor: str | None = None,
712
+ limit: int | None = None,
713
+ ) -> dict[str, Any]:
714
+ """Read where the request asked with this key stands and the rows it found so far."""
715
+ path = f"/v1/capacity/requests/{quote_path(request_key, safe='')}/rows"
716
+ query: dict[str, Any] = {
717
+ "project_id": project_id,
718
+ "cursor": cursor,
719
+ "limit": limit,
720
+ }
721
+ encoded = urlencode(
722
+ {
723
+ key: str(value).lower() if isinstance(value, bool) else value
724
+ for key, value in query.items()
725
+ if value is not None
726
+ }
727
+ )
728
+ if encoded:
729
+ path += "?" + encoded
730
+ return self._request("GET", path, None)
731
+
701
732
  def get_capacity_execution(self, find_id: str) -> dict[str, Any]:
702
733
  """Read a find's approved work, final charge and your access to its results."""
703
734
  path = f"/v1/capacity/executions/{quote_path(find_id, safe='')}"
@@ -1230,6 +1261,15 @@ class Client:
1230
1261
  path = f"/v1/workspace/collections/{quote_path(collection_id, safe='')}/relationships"
1231
1262
  return self._request("PUT", path, request)
1232
1263
 
1264
+ def workspace_share_collection(
1265
+ self,
1266
+ collection_id: str,
1267
+ request: dict[str, Any],
1268
+ ) -> dict[str, Any]:
1269
+ """Share a fixed copy of every record in a list through a link."""
1270
+ path = f"/v1/workspace/collections/{quote_path(collection_id, safe='')}/share"
1271
+ return self._request("POST", path, request)
1272
+
1233
1273
  def workspace_report_result(
1234
1274
  self,
1235
1275
  collection_id: str,
@@ -1,4 +1,8 @@
1
- """Lock result families from finder.cross-source.v1 OpenAPI EntityType."""
1
+ """Record kinds the service names today, from the finder.cross-source.v1 OpenAPI.
2
+
3
+ A record kind is an open string. FAMILIES lists the known kinds as examples; any
4
+ other non-empty kind name a reading gives is valid too.
5
+ """
2
6
 
3
7
  from __future__ import annotations
4
8
 
@@ -29,8 +33,6 @@ FAMILY_SET = frozenset(FAMILIES)
29
33
 
30
34
 
31
35
  def assert_family(entity_type: str) -> str:
32
- if entity_type not in FAMILY_SET:
33
- raise ValueError(
34
- f"unsupported entity_type {entity_type!r}; must be one of: {', '.join(FAMILIES)}"
35
- )
36
+ if not isinstance(entity_type, str) or not entity_type.strip():
37
+ raise ValueError("entity_type must be a non-empty string")
36
38
  return entity_type
@@ -323,12 +323,28 @@ COMMANDS = {'get-vocabulary': {'method': 'get_vocabulary',
323
323
  'summary': 'Approve the exact quote to start one find and reserve its '
324
324
  'maximum from your balance. Needs the specs:write, '
325
325
  'finds:write and finds:spend scopes'},
326
+ 'start-capacity-request': {'method': 'start_capacity_request',
327
+ 'arguments': [],
328
+ 'body': True,
329
+ 'body_required': True,
330
+ 'query': {},
331
+ 'summary': 'Ask for a list in plain words and run it within a maximum '
332
+ 'price, answering at once'},
326
333
  'get-capacity-request': {'method': 'get_capacity_request',
327
334
  'arguments': ['request_key'],
328
335
  'body': False,
329
336
  'body_required': False,
330
337
  'query': {'project_id': 'string'},
331
338
  'summary': 'Recover the find already started with this request key'},
339
+ 'get-capacity-request-rows': {'method': 'get_capacity_request_rows',
340
+ 'arguments': ['request_key'],
341
+ 'body': False,
342
+ 'body_required': False,
343
+ 'query': {'project_id': 'string',
344
+ 'cursor': 'string',
345
+ 'limit': 'integer'},
346
+ 'summary': 'Read where the request asked with this key stands and '
347
+ 'the rows it found so far'},
332
348
  'get-capacity-execution': {'method': 'get_capacity_execution',
333
349
  'arguments': ['find_id'],
334
350
  'body': False,
@@ -793,6 +809,13 @@ COMMANDS = {'get-vocabulary': {'method': 'get_vocabulary',
793
809
  'query': {},
794
810
  'summary': 'Save a personal relationship column with an expected '
795
811
  'version'},
812
+ 'workspace-share-collection': {'method': 'workspace_share_collection',
813
+ 'arguments': ['collection_id'],
814
+ 'body': True,
815
+ 'body_required': True,
816
+ 'query': {},
817
+ 'summary': 'Share a fixed copy of every record in a list through a '
818
+ 'link'},
796
819
  'workspace-report-result': {'method': 'workspace_report_result',
797
820
  'arguments': ['collection_id'],
798
821
  'body': True,
@@ -8,7 +8,7 @@ import unittest
8
8
  from typing import Any
9
9
 
10
10
  from specstream_client.client import Client
11
- from specstream_client.families import FAMILIES
11
+ from specstream_client.families import FAMILIES, assert_family
12
12
 
13
13
 
14
14
  class _FakeResponse:
@@ -33,6 +33,12 @@ class ClientTests(unittest.TestCase):
33
33
  self.assertIn(family, FAMILIES)
34
34
  self.assertNotIn("company", FAMILIES)
35
35
 
36
+ def test_any_kind_name_is_a_valid_entity_type(self):
37
+ self.assertEqual(assert_family("organization"), "organization")
38
+ self.assertEqual(assert_family("wine_estate"), "wine_estate")
39
+ with self.assertRaises(ValueError):
40
+ assert_family(" ")
41
+
36
42
  def test_no_obsolete_spending_or_sample_methods(self):
37
43
  client = Client("fixture-key")
38
44
  for name in ("quote", "confirm", "run", "create_find", "continue_find", "start_spec_find"):