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.
@@ -0,0 +1,251 @@
1
+ Metadata-Version: 2.5
2
+ Name: entitybind
3
+ Version: 0.1.0
4
+ Summary: EntityBind command-line client: log in, wire EntityBind into Claude Code, Codex, Gemini CLI, Cursor or VS Code, and call the Core API.
5
+ Project-URL: Homepage, https://app.entitybind.com
6
+ Project-URL: Documentation, https://app.entitybind.com/api/docs
7
+ Project-URL: Source, https://github.com/Tenhaw/entity-resolution/tree/main/clients/python
8
+ Author: EntityBind
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: cli,company-data,entity-resolution,entitybind,kyc,mcp
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Topic :: Utilities
23
+ Classifier: Typing :: Typed
24
+ Requires-Python: >=3.10
25
+ Requires-Dist: httpx<1,>=0.27
26
+ Provides-Extra: keyring
27
+ Requires-Dist: keyring>=24; extra == 'keyring'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # entitybind
31
+
32
+ The command-line client for [EntityBind](https://app.entitybind.com). It signs
33
+ a person or a coding agent in, wires EntityBind's MCP servers into Claude Code,
34
+ Codex, Gemini CLI, Cursor or VS Code, and calls the Entity Bind - Core API:
35
+ resolve, quote, registry discovery, batch jobs, usage, billing, keys and
36
+ decision receipts.
37
+
38
+ It has one runtime dependency (`httpx`), needs Python 3.10 or later, and talks
39
+ only to the EntityBind origins you point it at.
40
+
41
+ ## Install
42
+
43
+ ```sh
44
+ uvx entitybind --help # run without installing
45
+ pipx install entitybind # or install it as a tool
46
+ pipx install 'entitybind[keyring]' # store credentials in the OS keyring
47
+ ```
48
+
49
+ The npm package of the same name provides `login`, `logout`, `whoami` and
50
+ `mcp add` for machines without Python: `npx entitybind login`.
51
+
52
+ ## Sign in
53
+
54
+ ```sh
55
+ entitybind login # Entity Bind - Core
56
+ entitybind login --product aml # AML Onboard
57
+ ```
58
+
59
+ `login` uses the OAuth device flow (RFC 8628). It prints a link and a short
60
+ code, opens your browser, and waits while you approve the request as the
61
+ workspace owner. The resulting key is stored:
62
+
63
+ - in the OS keyring, when `entitybind[keyring]` is installed and a keyring
64
+ backend works; otherwise
65
+ - in `$XDG_CONFIG_HOME/entitybind/credentials.json` (default `~/.config`),
66
+ mode 0600 in a 0700 directory.
67
+
68
+ Credentials are kept per product and base URL. `entitybind whoami` shows which
69
+ credential is in use; `entitybind logout` removes it. `--revoke` revokes the
70
+ key on the server first and removes the local copy only once the server
71
+ confirms the key no longer works; otherwise it exits non-zero
72
+ (`revocation_unconfirmed`), keeps the local copy and names the key id.
73
+
74
+ AML device login is for sandbox workspaces and needs an MFA administrator's
75
+ approval. In a self-serve workspace it reports `simulated_checks_only: true`
76
+ in JSON and explains that checks use synthetic providers only.
77
+
78
+ Useful options: `--scope` (Core: `read`, `resolve`, `review` or `admin`,
79
+ default `resolve`; AML: `agent`, the default, `partner`, or AML scope names),
80
+ `--name` (a suggested key label; current servers ignore it and the key is
81
+ named when it is approved), `--no-browser`, `--print-key` (print the key
82
+ once on stdout, for a secret manager), and `--no-store` (only with
83
+ `--print-key`, so the key is never discarded). The browser is opened only for
84
+ an `https` link.
85
+
86
+ ### Signing in from a coding agent
87
+
88
+ An agent's tool call may time out before a person approves. Use a time limit
89
+ and resume:
90
+
91
+ ```sh
92
+ entitybind login --no-browser --timeout 50 --json # exits 9 while waiting
93
+ entitybind login --resume --timeout 50 --json # repeat until it exits 0
94
+ ```
95
+
96
+ With `--json`, the link and code are printed on stderr as a JSON event for the
97
+ agent to relay to the person; stdout carries one JSON result. A started sign-in
98
+ is saved (mode 0600) until it is approved, denied or expires.
99
+
100
+ ## Wire EntityBind into your agent
101
+
102
+ ```sh
103
+ entitybind mcp add claude-code # print the entry for ./.mcp.json
104
+ entitybind mcp add claude-code --write # merge it into ./.mcp.json
105
+ entitybind mcp add codex --write # ~/.codex/config.toml
106
+ entitybind mcp add gemini --write # ./.gemini/settings.json
107
+ entitybind mcp add cursor --write # ./.cursor/mcp.json
108
+ entitybind mcp add vscode --write # ./.vscode/mcp.json
109
+ entitybind mcp add claude-code --product aml --write
110
+ ```
111
+
112
+ `--auth key` (the default) sends `Authorization: Bearer` with the key taken
113
+ from an environment variable, `ENTITYBIND_API_KEY` for Core or
114
+ `ENTITYBIND_AML_KEY` for AML, so no key is written to disk. A plain `login`
115
+ never prints the stored key, so get one for the agent with `--print-key`, and
116
+ set the variable for that agent's process or project only, not in your shell
117
+ profile:
118
+
119
+ ```sh
120
+ export ENTITYBIND_API_KEY="$(entitybind login --print-key --no-store)" # this shell only
121
+ claude
122
+ ```
123
+
124
+ Headless agents such as `claude -p` load a repository's committed `.mcp.json`
125
+ without asking, so a hostile repository could name the same variable for its
126
+ own server and receive an exported key. `--inline-key` writes the raw key instead (with a
127
+ warning, mode 0600), and only into a user-scope file: it is refused for
128
+ project files such as `./.mcp.json`, which are usually committed, so add
129
+ `--scope user`.
130
+
131
+ `--auth oauth` (Core only) configures just the URL. The client registers
132
+ itself and the workspace owner approves the connection in the browser: run
133
+ `/mcp` in Claude Code, `codex mcp login entitybind`, or `/mcp auth entitybind`
134
+ in Gemini CLI.
135
+
136
+ Other options: `--scope project|user` (Codex defaults to `user`, the others to
137
+ `project`), `--dir`, `--server-name`, and `--force` to update the URL and
138
+ credential settings of an existing entry of the same name. Settings you added
139
+ to the entry yourself (timeouts, trust, tool filters, Codex approval modes)
140
+ are never a conflict and are kept, with or without `--force`. Merging keeps everything else in the file, writes
141
+ atomically, and refuses files it cannot rewrite safely (for example JSON with
142
+ comments) rather than reformatting them. Claude Code's user scope is written by
143
+ running `claude mcp add-json` for you.
144
+
145
+ Gemini CLI blanks environment variables whose names contain `KEY` when it
146
+ expands headers, so `mcp add gemini` also adds the variable to
147
+ `security.environmentVariableRedaction.allowed`.
148
+ With `--json`, the `configuration` field contains the complete JSON fragment,
149
+ including that allowlist, for an agent to apply.
150
+
151
+ ## Use the Core API
152
+
153
+ ```sh
154
+ entitybind resolve --name "Acme Ltd" --country GB --postcode "SW1A 1AA"
155
+ entitybind resolve --input record.json --async --wait --json
156
+ entitybind quote --csv suppliers.csv --map name="Company Name" --default-country GB
157
+ entitybind discover --name "Acme" --country GB
158
+ entitybind jobs submit --csv suppliers.csv --map name="Company Name" \
159
+ --key-column "Supplier ID" --default-country GB --wait
160
+ entitybind jobs list
161
+ entitybind jobs results job_... --format csv --output results.csv
162
+ entitybind usage --since 2026-11-01
163
+ entitybind billing status
164
+ entitybind billing checkout --plan starter # prints a link for a person to pay
165
+ entitybind keys create --name ci --scope resolve --expires-in 30d # admin key
166
+ entitybind decisions get dec_...
167
+ ```
168
+
169
+ `jobs submit` maps CSV columns the same way as the repository's
170
+ `resolvd import-csv`: `--map field=Column` (repeatable, comma-separable), and
171
+ columns already named after a field map automatically. Rows without a name or
172
+ country are refused unless you pass `--skip-invalid` (in `quote --csv` too, so
173
+ a quote never silently covers fewer rows than the file). Large files are split
174
+ into jobs of `--chunk-size` records (default 500, Core's default batch limit;
175
+ `GET /v1/reference/limits` reports a deployment's `max_batch_size`). A
176
+ workspace may have only a limited number of jobs pending at once (ten by
177
+ default), so very large files may need `--wait` between runs.
178
+
179
+ `keys` commands need an admin-scoped key. Core scopes do not overlap, so keep
180
+ your everyday key stored and pass an admin key through the environment for key
181
+ management:
182
+
183
+ ```sh
184
+ export ENTITYBIND_ADMIN_KEY="$(entitybind login --scope admin --print-key --no-store)"
185
+ ```
186
+
187
+ Signing in with a different scope would replace the stored key and leave it
188
+ active, so `login` refuses that (`scope_change`) until you run
189
+ `entitybind logout --revoke`. Signing in again with the same scope replaces the
190
+ stored key and names the key it replaced, which stays active until it expires
191
+ or is revoked.
192
+
193
+ ## Non-interactive use (CI)
194
+
195
+ Create a key once, keep it in your secret store, and pass it through the
196
+ environment. Nothing is stored on the runner.
197
+
198
+ ```sh
199
+ entitybind login --scope resolve --print-key --no-store | your-secret-manager put entitybind
200
+ ```
201
+
202
+ ```yaml
203
+ - run: uvx entitybind@0.1.0 resolve --name "Acme Ltd" --country GB --json
204
+ env:
205
+ ENTITYBIND_API_KEY: ${{ secrets.ENTITYBIND_API_KEY }}
206
+ ```
207
+
208
+ Pin the version in automation (`uvx entitybind@0.1.0`), so CI never runs a
209
+ release, or anything published under the name, that nobody reviewed.
210
+ `ENTITYBIND_API_KEY` and `ENTITYBIND_AML_KEY` override any stored credential.
211
+ `ENTITYBIND_BASE_URL` and `ENTITYBIND_AML_BASE_URL` (or `--base-url`) point the
212
+ client elsewhere; plain `http` is accepted only for `localhost`.
213
+
214
+ ## Output and exit codes
215
+
216
+ Every command accepts `--json`. Successful API commands print the server's
217
+ JSON body; errors print `{"error": {...}, "status": ..., "exit_code": ...}` on
218
+ stdout, including any `remediation` the server returned. Progress goes to
219
+ stderr.
220
+
221
+ | Code | Meaning |
222
+ |---:|---|
223
+ | 0 | ok |
224
+ | 2 | usage error or invalid request |
225
+ | 3 | authentication or permission |
226
+ | 4 | payment or entitlement |
227
+ | 5 | not found |
228
+ | 6 | conflict |
229
+ | 7 | rate limited |
230
+ | 8 | server or network error |
231
+ | 9 | still pending or timed out |
232
+
233
+ `jobs wait` exits 0 for `succeeded`, 8 for `failed` or
234
+ `reconciliation_required`, 6 for `cancelled` and 5 for `erased`.
235
+
236
+ Requests carry `User-Agent: entitybind-cli/<version>` and
237
+ `X-EntityBind-Client: cli`. Mutating requests carry an `Idempotency-Key`
238
+ (pass `--idempotency-key` to choose it), and an error names the key it was
239
+ sent with; 429 and 503 responses are retried after the server's
240
+ `Retry-After`.
241
+
242
+ If `jobs submit` stops part-way (for example at the workspace's limit on
243
+ pending jobs), the error lists the jobs already accepted. Rerunning the same
244
+ command within 24 hours resumes the submission: it reuses the remembered
245
+ idempotency key, so the accepted jobs are recovered rather than queued again.
246
+ `--timeout` covers the whole `--wait`, and a passing 5xx or network failure
247
+ while waiting does not end it.
248
+
249
+ ## Licence
250
+
251
+ MIT.
@@ -0,0 +1,23 @@
1
+ entitybind/__init__.py,sha256=ZLlp4OpAGG0UqqP_FwmTZbnyp68SFXoWk-fwPuPSIBw,304
2
+ entitybind/__main__.py,sha256=023rwcJWUam-VTkQpSs5uZhUZldoMJJ_qajsp5fkHDA,58
3
+ entitybind/cli.py,sha256=S8ofcE9GrTOjXCx26X7G1FsNgNQsKPp87DKObmjiIqY,20019
4
+ entitybind/commands_api.py,sha256=VBzpwe3hkFZ4Cr-__5ME7MrcTQmiYknOPKBPcyjMd6w,33274
5
+ entitybind/commands_auth.py,sha256=zxeTLTerTZr6iECCj9oirMv1RBkpOnmPdVaQloSAkBw,15700
6
+ entitybind/commands_mcp.py,sha256=-APgS26BIJ3a2IlLSlwuio80Z4QpsqHxNkC-He5_O5Q,8718
7
+ entitybind/context.py,sha256=6BT5FloW_FUxg0KMDy-0_VX4tM_OloPjJJ-dwha9br8,3859
8
+ entitybind/credentials.py,sha256=bR28ggpezXXFZj7HxQzspR-NGx519mZXmEEXPK-bJrg,13117
9
+ entitybind/device.py,sha256=xsxLs9DAsr7LE7cPoNLvn_RCfad8albky_x2SIe8W60,15744
10
+ entitybind/errors.py,sha256=7uSWpvxBoYJblG_wLHBrEqcQ0UNcAnHjt0mV_ZZFCJA,5100
11
+ entitybind/files.py,sha256=OOYvVIhLxBFCsivnkg0S8eTPYBg2d8H3AUn9U0edWqI,2299
12
+ entitybind/http.py,sha256=qHaAZrCJdeQJIN_3xA-3hWrJJwanzcQ4pB5rt9PCI7M,11388
13
+ entitybind/mcpconfig.py,sha256=LGuRTZP6GoMYTclQUWcLVa4mlFs9Bd7Tp9T4wp1zBQo,28798
14
+ entitybind/products.py,sha256=YPJUjUO9kdR2kKHHJeegzBbHB6VJqfQP9UZi1DA7bSU,4171
15
+ entitybind/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
16
+ entitybind/records.py,sha256=D_ulXg_R2FUYj9-UAWfbH8ef6w2-g5vFArJY7zgdPBo,8102
17
+ entitybind/runtime.py,sha256=yUSoyFvZYM-Ygjz_nAqdlXyeDCThE8YxlxLEFuEtFkM,5390
18
+ entitybind/submissions.py,sha256=ZJkEQyEdCePO5322l1zUeZLAb6GI9ZF4591vq44y_Hg,3389
19
+ entitybind-0.1.0.dist-info/METADATA,sha256=bjNPXnGz-0lVJrUjMIsPsLByqDqiqeDL7Rb9kBBq3Mk,10908
20
+ entitybind-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
21
+ entitybind-0.1.0.dist-info/entry_points.txt,sha256=LW53lfhZ72Gn1u8Xl8A4c0vcwMvMSDL9XEFnhpq24xU,51
22
+ entitybind-0.1.0.dist-info/licenses/LICENSE,sha256=C_c1G4EGzGBqm9kCgYU5K8aHSboWuNd-pm7xWH9SAw4,1063
23
+ entitybind-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ entitybind = entitybind.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Tenhaw
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.