entitybind 0.1.0__py3-none-any.whl

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.
entitybind/__init__.py ADDED
@@ -0,0 +1,8 @@
1
+ """A thin command-line client for EntityBind.
2
+
3
+ It logs a person or a coding agent in, wires EntityBind into Claude Code, Codex,
4
+ Gemini CLI, Cursor or VS Code, and calls the Entity Bind - Core REST API. It
5
+ has one runtime dependency (httpx) and imports nothing from the server.
6
+ """
7
+
8
+ __version__ = "0.1.0"
entitybind/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from entitybind.cli import main
2
+
3
+ raise SystemExit(main())
entitybind/cli.py ADDED
@@ -0,0 +1,510 @@
1
+ """The `entitybind` command line.
2
+
3
+ Run `entitybind --help` or `entitybind <command> --help`. Every command takes
4
+ --json for machine output and exits with a stable code (see EXIT CODES).
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import argparse
10
+ import contextlib
11
+ import sys
12
+ from collections.abc import Callable, Sequence
13
+ from datetime import date
14
+ from typing import NoReturn
15
+
16
+ from entitybind import __version__
17
+ from entitybind.commands_api import (
18
+ cmd_billing_checkout,
19
+ cmd_billing_status,
20
+ cmd_decisions_get,
21
+ cmd_discover,
22
+ cmd_jobs_cancel,
23
+ cmd_jobs_get,
24
+ cmd_jobs_list,
25
+ cmd_jobs_results,
26
+ cmd_jobs_submit,
27
+ cmd_jobs_wait,
28
+ cmd_keys_create,
29
+ cmd_keys_list,
30
+ cmd_keys_revoke,
31
+ cmd_keys_rotate,
32
+ cmd_quote,
33
+ cmd_resolve,
34
+ cmd_usage,
35
+ )
36
+ from entitybind.commands_auth import CORE_LOGIN_SCOPES, cmd_login, cmd_logout, cmd_whoami
37
+ from entitybind.commands_mcp import cmd_mcp_add
38
+ from entitybind.context import Context
39
+ from entitybind.errors import EXIT_CODES, CliError, ConflictError, UsageError
40
+ from entitybind.mcpconfig import AUTH_MODES, CLIENTS, SCOPES
41
+ from entitybind.records import DEFAULT_CHUNK_SIZE, DEPTHS, MAPPABLE_FIELDS
42
+ from entitybind.runtime import Output, Runtime
43
+
44
+ Handler = Callable[[Context], int]
45
+
46
+ EXIT_CODE_HELP = "exit codes:\n" + "\n".join(
47
+ f" {code} {meaning}" for code, meaning in sorted(EXIT_CODES.items())
48
+ )
49
+ ENVIRONMENT_HELP = """environment:
50
+ ENTITYBIND_API_KEY Core key; overrides any stored credential
51
+ ENTITYBIND_AML_KEY AML Onboard key; overrides any stored credential
52
+ ENTITYBIND_ADMIN_KEY admin-scoped Core key used by `keys` commands when set
53
+ ENTITYBIND_BASE_URL Core base URL (default https://app.entitybind.com)
54
+ ENTITYBIND_AML_BASE_URL AML base URL (default https://onboard.entitybind.com)
55
+ ENTITYBIND_NO_KEYRING set to store credentials in the file even if keyring works
56
+ XDG_CONFIG_HOME credentials live in $XDG_CONFIG_HOME/entitybind (default ~/.config)
57
+ """
58
+ ADMIN_KEY_SCOPES = ("read", "resolve", "review", "erase", "admin")
59
+
60
+
61
+ class _Parser(argparse.ArgumentParser):
62
+ def error(self, message: str) -> NoReturn:
63
+ raise UsageError(f"{self.prog}: {message}", hint=self.format_usage().strip())
64
+
65
+
66
+ def _number(value: str) -> float:
67
+ try:
68
+ number = float(value)
69
+ except ValueError:
70
+ raise argparse.ArgumentTypeError(f"expected a number, got {value!r}") from None
71
+ if number != number: # NaN
72
+ raise argparse.ArgumentTypeError(f"expected a number, got {value!r}")
73
+ return number
74
+
75
+
76
+ def _positive_float(value: str) -> float:
77
+ number = _number(value)
78
+ if number <= 0:
79
+ raise argparse.ArgumentTypeError("must be greater than zero")
80
+ return number
81
+
82
+
83
+ def _non_negative_float(value: str) -> float:
84
+ number = _number(value)
85
+ if number < 0:
86
+ raise argparse.ArgumentTypeError("must be zero or more")
87
+ return number
88
+
89
+
90
+ def _non_negative_int(value: str) -> int:
91
+ try:
92
+ number = int(value)
93
+ except ValueError:
94
+ raise argparse.ArgumentTypeError(f"expected a whole number, got {value!r}") from None
95
+ if number < 0:
96
+ raise argparse.ArgumentTypeError("must be zero or more")
97
+ return number
98
+
99
+
100
+ def _positive_int(value: str) -> int:
101
+ number = _non_negative_int(value)
102
+ if number == 0:
103
+ raise argparse.ArgumentTypeError("must be greater than zero")
104
+ return number
105
+
106
+
107
+ def _iso_date(value: str) -> str:
108
+ try:
109
+ date.fromisoformat(value)
110
+ except ValueError:
111
+ raise argparse.ArgumentTypeError(f"expected YYYY-MM-DD, got {value!r}") from None
112
+ return value
113
+
114
+
115
+ def _common() -> _Parser:
116
+ common = _Parser(add_help=False)
117
+ group = common.add_argument_group("common options")
118
+ group.add_argument(
119
+ "--json",
120
+ action="store_true",
121
+ default=argparse.SUPPRESS,
122
+ help="print machine-readable JSON on stdout (errors too)",
123
+ )
124
+ group.add_argument(
125
+ "--base-url",
126
+ metavar="URL",
127
+ default=argparse.SUPPRESS,
128
+ help="API origin (default https://app.entitybind.com, or https://onboard.entitybind.com "
129
+ "for --product aml)",
130
+ )
131
+ group.add_argument(
132
+ "--http-timeout",
133
+ type=_positive_float,
134
+ metavar="SECONDS",
135
+ default=argparse.SUPPRESS,
136
+ help="per-request timeout (default 60; 330 for a synchronous resolve)",
137
+ )
138
+ group.add_argument(
139
+ "--max-retries",
140
+ type=_non_negative_int,
141
+ metavar="N",
142
+ default=argparse.SUPPRESS,
143
+ help="retries on 429/503 and connection failures (default 3)",
144
+ )
145
+ return common
146
+
147
+
148
+ def _product(parser: argparse.ArgumentParser) -> None:
149
+ parser.add_argument(
150
+ "--product",
151
+ choices=("core", "aml"),
152
+ default=argparse.SUPPRESS,
153
+ help="Entity Bind - Core (default) or AML Onboard",
154
+ )
155
+
156
+
157
+ def _waiting(parser: argparse.ArgumentParser, default_timeout: float = 600.0) -> None:
158
+ parser.add_argument(
159
+ "--timeout",
160
+ type=_non_negative_float,
161
+ default=default_timeout,
162
+ metavar="SECONDS",
163
+ help=f"how long to wait in total before exiting 9 (default {default_timeout:g})",
164
+ )
165
+ parser.add_argument(
166
+ "--interval",
167
+ type=_positive_float,
168
+ default=2.0,
169
+ metavar="SECONDS",
170
+ help="first polling interval; backs off to 15s and honours Retry-After (default 2)",
171
+ )
172
+
173
+
174
+ def _idempotency(parser: argparse.ArgumentParser) -> None:
175
+ parser.add_argument(
176
+ "--idempotency-key",
177
+ metavar="KEY",
178
+ help="reuse to retry safely; a fresh key is generated otherwise",
179
+ )
180
+
181
+
182
+ def _record_flags(parser: argparse.ArgumentParser) -> None:
183
+ group = parser.add_argument_group("record")
184
+ group.add_argument("--name", help="company name")
185
+ group.add_argument("--country", help="country name or ISO code")
186
+ for flag in (
187
+ "--domain",
188
+ "--website",
189
+ "--registration-number",
190
+ "--jurisdiction",
191
+ "--lei",
192
+ "--vat-number",
193
+ "--duns",
194
+ "--ticker",
195
+ "--exchange",
196
+ "--email",
197
+ "--phone",
198
+ "--postcode",
199
+ "--city",
200
+ "--client-ref",
201
+ ):
202
+ group.add_argument(flag)
203
+ group.add_argument(
204
+ "--context", help="what you know about the company in plain words (an unverified clue)"
205
+ )
206
+ group.add_argument(
207
+ "--input", metavar="FILE", help="JSON record file ('-' for stdin); flags override it"
208
+ )
209
+ parser.add_argument("--depth", choices=DEPTHS, help="price and latency ceiling per record")
210
+ parser.add_argument(
211
+ "--no-enrich", action="store_true", help="no registry lookups (dedupe against your data)"
212
+ )
213
+ parser.add_argument("--fields", metavar="A,B", help="entity attributes to return")
214
+ parser.add_argument(
215
+ "--field-pack", action="append", metavar="PACK", help="named attribute group (repeatable)"
216
+ )
217
+
218
+
219
+ def _csv_flags(parser: argparse.ArgumentParser, *, key_column: bool) -> None:
220
+ parser.add_argument("--csv", metavar="FILE", help="CSV file with a header row")
221
+ parser.add_argument(
222
+ "--map",
223
+ action="append",
224
+ metavar="FIELD=COLUMN",
225
+ help="map a record field to a CSV column (repeatable, comma-separable). Columns already "
226
+ "named after a field map automatically. Fields: " + ", ".join(MAPPABLE_FIELDS),
227
+ )
228
+ parser.add_argument(
229
+ "--default-country", metavar="CC", help="country for rows that do not name one"
230
+ )
231
+ if key_column:
232
+ parser.add_argument(
233
+ "--key-column", metavar="COLUMN", help="your own row id, sent as client_ref"
234
+ )
235
+
236
+
237
+ def build_parser() -> argparse.ArgumentParser:
238
+ common = _common()
239
+ parser = _Parser(
240
+ prog="entitybind",
241
+ description="Log in to EntityBind, wire it into your coding agent, and call the Core API.",
242
+ epilog=f"{EXIT_CODE_HELP}\n\n{ENVIRONMENT_HELP}",
243
+ formatter_class=argparse.RawDescriptionHelpFormatter,
244
+ parents=[common],
245
+ )
246
+ parser.add_argument("--version", action="version", version=f"entitybind {__version__}")
247
+ commands = parser.add_subparsers(dest="command", metavar="<command>", parser_class=_Parser)
248
+ commands.required = True
249
+
250
+ def leaf(
251
+ group: argparse._SubParsersAction[_Parser],
252
+ name: str,
253
+ handler: Handler,
254
+ help_text: str,
255
+ ) -> argparse.ArgumentParser:
256
+ sub = group.add_parser(name, help=help_text, description=help_text, parents=[common])
257
+ sub.set_defaults(handler=handler)
258
+ return sub
259
+
260
+ login = leaf(commands, "login", cmd_login, "sign in with a browser approval (device flow)")
261
+ _product(login)
262
+ login.add_argument(
263
+ "--scope",
264
+ metavar="SCOPE",
265
+ help="Core: " + ", ".join(CORE_LOGIN_SCOPES) + " (default resolve); "
266
+ "AML: agent (default), partner, or AML scope names",
267
+ )
268
+ login.add_argument(
269
+ "--name",
270
+ help="suggested key label, sent with the request; current EntityBind servers ignore it "
271
+ "and the key is named when it is approved",
272
+ )
273
+ login.add_argument("--no-browser", action="store_true", help="print the link; do not open it")
274
+ login.add_argument(
275
+ "--print-key",
276
+ action="store_true",
277
+ help="print the key once on stdout, for a secret manager",
278
+ )
279
+ login.add_argument("--no-store", action="store_true", help="do not store the key locally")
280
+ login.add_argument(
281
+ "--timeout",
282
+ type=_non_negative_float,
283
+ metavar="SECONDS",
284
+ help="stop waiting after this long and exit 9; continue later with --resume",
285
+ )
286
+ login.add_argument(
287
+ "--no-wait", action="store_true", help="print the link and code, then exit 9 at once"
288
+ )
289
+ login.add_argument(
290
+ "--resume", action="store_true", help="keep waiting for a sign-in started earlier"
291
+ )
292
+
293
+ logout = leaf(commands, "logout", cmd_logout, "remove the stored credential")
294
+ _product(logout)
295
+ logout.add_argument(
296
+ "--revoke",
297
+ action="store_true",
298
+ help="revoke the key on the server first; the local record is kept unless the "
299
+ "revocation is confirmed",
300
+ )
301
+ logout.add_argument(
302
+ "--all", action="store_true", help="remove every stored credential (not with --revoke)"
303
+ )
304
+
305
+ whoami = leaf(commands, "whoami", cmd_whoami, "show the credential in use")
306
+ _product(whoami)
307
+
308
+ mcp = commands.add_parser("mcp", help="configure MCP clients")
309
+ mcp_commands = mcp.add_subparsers(
310
+ dest="mcp_command", metavar="<subcommand>", parser_class=_Parser
311
+ )
312
+ mcp_commands.required = True
313
+ mcp_add = leaf(mcp_commands, "add", cmd_mcp_add, "print or write an MCP client configuration")
314
+ mcp_add.add_argument("client", choices=CLIENTS)
315
+ _product(mcp_add)
316
+ mcp_add.add_argument(
317
+ "--auth",
318
+ choices=AUTH_MODES,
319
+ default="key",
320
+ help="key: Authorization header from an environment variable (default); oauth: URL only, "
321
+ "the client signs in and the workspace owner approves (Core only)",
322
+ )
323
+ mcp_add.add_argument(
324
+ "--scope",
325
+ choices=SCOPES,
326
+ help="project or user configuration (default: user for codex, project otherwise)",
327
+ )
328
+ mcp_add.add_argument("--write", action="store_true", help="merge the entry into the file")
329
+ mcp_add.add_argument(
330
+ "--inline-key", action="store_true", help="write the raw key into the file (not advised)"
331
+ )
332
+ mcp_add.add_argument("--server-name", metavar="NAME", help="entry name (default entitybind)")
333
+ mcp_add.add_argument("--dir", metavar="PATH", help="project directory (default: current)")
334
+ mcp_add.add_argument("--force", action="store_true", help="replace an existing entry")
335
+
336
+ resolve = leaf(commands, "resolve", cmd_resolve, "resolve one company record")
337
+ _record_flags(resolve)
338
+ resolve.add_argument(
339
+ "--async",
340
+ dest="async_",
341
+ action="store_true",
342
+ help="queue a durable job (POST /v1/resolve-jobs) instead of waiting on one request",
343
+ )
344
+ resolve.add_argument("--wait", action="store_true", help="with --async, wait for the result")
345
+ _waiting(resolve)
346
+ _idempotency(resolve)
347
+
348
+ quote = leaf(commands, "quote", cmd_quote, "estimate the credits a request would use")
349
+ _record_flags(quote)
350
+ _csv_flags(quote, key_column=False)
351
+ quote.add_argument(
352
+ "--skip-invalid",
353
+ action="store_true",
354
+ help="with --csv, leave out rows without a name or country (otherwise refused)",
355
+ )
356
+ _idempotency(quote)
357
+
358
+ discover = leaf(
359
+ commands, "discover", cmd_discover, "official registry candidates for a name and country"
360
+ )
361
+ discover.add_argument("--name", help="company name")
362
+ discover.add_argument("--country", help="country name or ISO code")
363
+ discover.add_argument("--website", help="optional website")
364
+ discover.add_argument("--input", metavar="FILE", help="JSON request file ('-' for stdin)")
365
+ _idempotency(discover)
366
+
367
+ jobs = commands.add_parser("jobs", help="durable batch jobs")
368
+ jobs_commands = jobs.add_subparsers(
369
+ dest="jobs_command", metavar="<subcommand>", parser_class=_Parser
370
+ )
371
+ jobs_commands.required = True
372
+ submit = leaf(jobs_commands, "submit", cmd_jobs_submit, "submit records as batch jobs")
373
+ _csv_flags(submit, key_column=True)
374
+ submit.add_argument(
375
+ "--records", metavar="FILE", help="JSON list, {records: [...]} or JSON lines"
376
+ )
377
+ submit.add_argument("--depth", choices=DEPTHS, help="depth for records that do not set one")
378
+ submit.add_argument(
379
+ "--chunk-size",
380
+ type=_positive_int,
381
+ default=DEFAULT_CHUNK_SIZE,
382
+ metavar="N",
383
+ help=f"records per job (default {DEFAULT_CHUNK_SIZE}, Core's default batch limit; "
384
+ "GET /v1/reference/limits shows a deployment's max_batch_size)",
385
+ )
386
+ submit.add_argument(
387
+ "--skip-invalid", action="store_true", help="skip rows without a name or country"
388
+ )
389
+ submit.add_argument("--wait", action="store_true", help="wait for every job to finish")
390
+ _waiting(submit)
391
+ _idempotency(submit)
392
+ jobs_list = leaf(jobs_commands, "list", cmd_jobs_list, "list your batch jobs")
393
+ jobs_list.add_argument("--limit", type=_positive_int, metavar="N")
394
+ jobs_list.add_argument("--cursor", metavar="CURSOR")
395
+ jobs_list.add_argument("--state", metavar="STATE")
396
+ jobs_get = leaf(jobs_commands, "get", cmd_jobs_get, "show one job")
397
+ jobs_get.add_argument("job_id")
398
+ jobs_wait = leaf(jobs_commands, "wait", cmd_jobs_wait, "wait until a job finishes")
399
+ jobs_wait.add_argument("job_id")
400
+ _waiting(jobs_wait)
401
+ jobs_results = leaf(jobs_commands, "results", cmd_jobs_results, "print or save a job's results")
402
+ jobs_results.add_argument("job_id")
403
+ jobs_results.add_argument("--format", choices=("json", "csv"), default="json")
404
+ jobs_results.add_argument("--output", metavar="FILE", help="write to a file (mode 600)")
405
+ jobs_results.add_argument("--wait", action="store_true", help="wait for the job first")
406
+ _waiting(jobs_results)
407
+ jobs_cancel = leaf(jobs_commands, "cancel", cmd_jobs_cancel, "cancel a queued job")
408
+ jobs_cancel.add_argument("job_id")
409
+
410
+ usage = leaf(commands, "usage", cmd_usage, "calls, credits and rates for a period")
411
+ usage.add_argument("--since", type=_iso_date, metavar="YYYY-MM-DD")
412
+ usage.add_argument("--until", type=_iso_date, metavar="YYYY-MM-DD")
413
+
414
+ billing = commands.add_parser("billing", help="plan and payment")
415
+ billing_commands = billing.add_subparsers(
416
+ dest="billing_command", metavar="<subcommand>", parser_class=_Parser
417
+ )
418
+ billing_commands.required = True
419
+ leaf(billing_commands, "status", cmd_billing_status, "plan, credits and payment state")
420
+ checkout = leaf(
421
+ billing_commands, "checkout", cmd_billing_checkout, "a checkout link for a person to pay"
422
+ )
423
+ checkout.add_argument("--plan", required=True, help="plan to buy, e.g. starter")
424
+ checkout.add_argument("--open", action="store_true", help="open the link in a browser")
425
+ _idempotency(checkout)
426
+
427
+ keys = commands.add_parser("keys", help="manage API keys (admin-scoped key)")
428
+ keys_commands = keys.add_subparsers(
429
+ dest="keys_command", metavar="<subcommand>", parser_class=_Parser
430
+ )
431
+ keys_commands.required = True
432
+ keys_list = leaf(keys_commands, "list", cmd_keys_list, "list a workspace's keys")
433
+ keys_list.add_argument("--tenant-id", metavar="ID", help="default: your own workspace")
434
+ keys_create = leaf(keys_commands, "create", cmd_keys_create, "create a key (shown once)")
435
+ keys_create.add_argument("--name", required=True, help="label for the key")
436
+ keys_create.add_argument("--scope", choices=ADMIN_KEY_SCOPES, default="resolve")
437
+ keys_create.add_argument("--plan", help="plan, capped at the workspace's own plan")
438
+ keys_create.add_argument("--tenant-id", metavar="ID", help="default: your own workspace")
439
+ keys_create.add_argument(
440
+ "--expires-in", metavar="DURATION", help="one hour to one year, e.g. 3600, 90m, 12h, 30d"
441
+ )
442
+ keys_create.add_argument(
443
+ "--expires-at", metavar="TIME", help="ISO 8601, e.g. 2027-01-31T00:00:00Z"
444
+ )
445
+ keys_create.add_argument(
446
+ "--credit-limit", type=int, metavar="N", help="credits this key may spend"
447
+ )
448
+ keys_create.add_argument(
449
+ "--max-depth", choices=DEPTHS, help="deepest resolution this key may run"
450
+ )
451
+ # No --idempotency-key: the admin key routes do not honour one, so a retry
452
+ # after a timeout could mint a second key whatever key was sent.
453
+ keys_rotate = leaf(
454
+ keys_commands, "rotate", cmd_keys_rotate, "replace a key (new key shown once)"
455
+ )
456
+ keys_rotate.add_argument("key_id")
457
+ keys_rotate.add_argument(
458
+ "--grace-seconds", type=int, metavar="N", help="old key keeps working this long (0: now)"
459
+ )
460
+ keys_revoke = leaf(keys_commands, "revoke", cmd_keys_revoke, "revoke a key immediately")
461
+ keys_revoke.add_argument("key_id")
462
+
463
+ decisions = commands.add_parser("decisions", help="decision receipts")
464
+ decisions_commands = decisions.add_subparsers(
465
+ dest="decisions_command", metavar="<subcommand>", parser_class=_Parser
466
+ )
467
+ decisions_commands.required = True
468
+ decisions_get = leaf(decisions_commands, "get", cmd_decisions_get, "show one decision receipt")
469
+ decisions_get.add_argument("decision_id")
470
+ return parser
471
+
472
+
473
+ def main(argv: Sequence[str] | None = None, runtime: Runtime | None = None) -> int:
474
+ runtime = runtime or Runtime.system()
475
+ arguments = list(sys.argv[1:] if argv is None else argv)
476
+ parser = build_parser()
477
+ try:
478
+ with contextlib.redirect_stdout(runtime.stdout), contextlib.redirect_stderr(runtime.stderr):
479
+ args = parser.parse_args(arguments)
480
+ except UsageError as error:
481
+ Output(runtime, json_mode="--json" in arguments).error(error)
482
+ return error.exit_code
483
+ except SystemExit as stop: # --help and --version
484
+ return stop.code if isinstance(stop.code, int) else 0
485
+ context = Context(runtime, args)
486
+ handler: Handler = args.handler
487
+ try:
488
+ return int(handler(context))
489
+ except CliError as error:
490
+ context.output.error(error)
491
+ return error.exit_code
492
+ except KeyboardInterrupt:
493
+ context.output.info("interrupted")
494
+ return 130
495
+ except (OSError, UnicodeDecodeError) as exc:
496
+ failure = local_failure(exc)
497
+ context.output.error(failure)
498
+ return failure.exit_code
499
+
500
+
501
+ def local_failure(exc: OSError | UnicodeDecodeError) -> CliError:
502
+ """A local file failure no command anticipated, kept to the published exit codes."""
503
+ if isinstance(exc, UnicodeDecodeError):
504
+ return ConflictError(f"a file is not UTF-8 text ({exc.reason})", code="file_error")
505
+ where = f": {exc.filename}" if exc.filename else ""
506
+ return ConflictError(f"{exc.strerror or type(exc).__name__}{where}", code="file_error")
507
+
508
+
509
+ if __name__ == "__main__": # pragma: no cover
510
+ raise SystemExit(main())