liquilens 0.1.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 (65) hide show
  1. liquilens-0.1.0/.gitignore +26 -0
  2. liquilens-0.1.0/CHANGELOG.md +69 -0
  3. liquilens-0.1.0/CITATION.cff +22 -0
  4. liquilens-0.1.0/LICENSE +21 -0
  5. liquilens-0.1.0/PKG-INFO +320 -0
  6. liquilens-0.1.0/README.md +284 -0
  7. liquilens-0.1.0/SECURITY.md +42 -0
  8. liquilens-0.1.0/pyproject.toml +103 -0
  9. liquilens-0.1.0/src/liquilens/__init__.py +78 -0
  10. liquilens-0.1.0/src/liquilens/_http.py +226 -0
  11. liquilens-0.1.0/src/liquilens/_version.py +1 -0
  12. liquilens-0.1.0/src/liquilens/bundle/__init__.py +35 -0
  13. liquilens-0.1.0/src/liquilens/bundle/build.py +239 -0
  14. liquilens-0.1.0/src/liquilens/bundle/data/bundle-manifest.schema.json +50 -0
  15. liquilens-0.1.0/src/liquilens/bundle/data/rights-rule.json +9 -0
  16. liquilens-0.1.0/src/liquilens/bundle/manifest.py +163 -0
  17. liquilens-0.1.0/src/liquilens/bundle/tables.py +131 -0
  18. liquilens-0.1.0/src/liquilens/bundle/writers.py +119 -0
  19. liquilens-0.1.0/src/liquilens/cli.py +161 -0
  20. liquilens-0.1.0/src/liquilens/client.py +315 -0
  21. liquilens-0.1.0/src/liquilens/errors.py +189 -0
  22. liquilens-0.1.0/src/liquilens/ids.py +80 -0
  23. liquilens-0.1.0/src/liquilens/models.py +413 -0
  24. liquilens-0.1.0/src/liquilens/odata.py +105 -0
  25. liquilens-0.1.0/src/liquilens/py.typed +0 -0
  26. liquilens-0.1.0/src/liquilens_join/__init__.py +87 -0
  27. liquilens-0.1.0/src/liquilens_join/__main__.py +99 -0
  28. liquilens-0.1.0/src/liquilens_join/bundle_check.py +81 -0
  29. liquilens-0.1.0/src/liquilens_join/data/SCOWL-Copyright.txt +248 -0
  30. liquilens-0.1.0/src/liquilens_join/data/common_words.txt.gz +0 -0
  31. liquilens-0.1.0/src/liquilens_join/dates.py +65 -0
  32. liquilens-0.1.0/src/liquilens_join/evaluate.py +332 -0
  33. liquilens-0.1.0/src/liquilens_join/kit.py +310 -0
  34. liquilens-0.1.0/src/liquilens_join/linker.py +913 -0
  35. liquilens-0.1.0/src/liquilens_join/mention.py +276 -0
  36. liquilens-0.1.0/src/liquilens_join/normalize.py +55 -0
  37. liquilens-0.1.0/src/liquilens_join/profile.py +99 -0
  38. liquilens-0.1.0/src/liquilens_join/resolver.py +376 -0
  39. liquilens-0.1.0/src/liquilens_join/textkey.py +347 -0
  40. liquilens-0.1.0/src/liquilens_join/validators.py +129 -0
  41. liquilens-0.1.0/tests/__init__.py +0 -0
  42. liquilens-0.1.0/tests/conftest.py +67 -0
  43. liquilens-0.1.0/tests/fake_api.py +432 -0
  44. liquilens-0.1.0/tests/fixtures/census.json +183 -0
  45. liquilens-0.1.0/tests/fixtures/object_bank_of_baroda.json +42 -0
  46. liquilens-0.1.0/tests/fixtures/object_dena_bank.json +30 -0
  47. liquilens-0.1.0/tests/fixtures/object_not_found_404.json +7 -0
  48. liquilens-0.1.0/tests/fixtures/release_identity.json +8 -0
  49. liquilens-0.1.0/tests/fixtures/resolve_ambiguous.json +9 -0
  50. liquilens-0.1.0/tests/fixtures/resolve_not_found.json +6 -0
  51. liquilens-0.1.0/tests/fixtures/resolve_resolved.json +6 -0
  52. liquilens-0.1.0/tests/test_as_of.py +195 -0
  53. liquilens-0.1.0/tests/test_bundle.py +321 -0
  54. liquilens-0.1.0/tests/test_cli.py +107 -0
  55. liquilens-0.1.0/tests/test_client.py +210 -0
  56. liquilens-0.1.0/tests/test_errors.py +103 -0
  57. liquilens-0.1.0/tests/test_feed.py +202 -0
  58. liquilens-0.1.0/tests/test_http.py +231 -0
  59. liquilens-0.1.0/tests/test_ids.py +55 -0
  60. liquilens-0.1.0/tests/test_join.py +278 -0
  61. liquilens-0.1.0/tests/test_linker.py +301 -0
  62. liquilens-0.1.0/tests/test_live.py +51 -0
  63. liquilens-0.1.0/tests/test_mention.py +140 -0
  64. liquilens-0.1.0/tests/test_mention_precision.py +80 -0
  65. liquilens-0.1.0/tests/test_package.py +95 -0
@@ -0,0 +1,26 @@
1
+ # Environments and caches
2
+ .venv*/
3
+ __pycache__/
4
+ *.py[cod]
5
+ .pytest_cache/
6
+ .mypy_cache/
7
+ .ruff_cache/
8
+
9
+ # Build output
10
+ build/
11
+ dist/
12
+ *.egg-info/
13
+
14
+ # Bundles built while trying the client locally
15
+ *.duckdb
16
+ *.duckdb.wal
17
+ /bundle*/
18
+
19
+ # Editors and OS
20
+ .DS_Store
21
+ .idea/
22
+ .vscode/
23
+
24
+ # Never commit credentials
25
+ .env
26
+ .env.*
@@ -0,0 +1,69 @@
1
+ # Changelog
2
+
3
+ All notable changes to this repository are recorded here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and both distributions use
5
+ [semantic versioning](https://semver.org/). Each distribution is versioned and released on its own
6
+ tag: `liquilens-vX.Y.Z` and `openbb-liquilens-vX.Y.Z`.
7
+
8
+ ## Repository (not part of either distribution)
9
+
10
+ ### Added
11
+
12
+ - `examples/`: two notebooks, committed without outputs. One resolves a list of Indian lender names
13
+ to canonical ids; the other runs NoiseFloor's change tests on a public Seiche money-market spread
14
+ and shows how they apply to LiquiLens lender panels with a key.
15
+ - `datasets/`: draft Hugging Face and Kaggle metadata for the identity bundle. Nothing is uploaded;
16
+ the drafts wait on the owner's terms per source, the owner's accounts and the identity feed.
17
+
18
+ ## liquilens 0.1.0 (2026-11-12)
19
+
20
+ ### Added
21
+
22
+ - `Client` for the LiquiLens public API: `resolve`, `describe`, `links`, `current_identity`,
23
+ `census`, `release`, and the OData identity feed through `feed` and `feed_entity`.
24
+ - Typed results (`Resolution`, `OntologyObject`, `Links`, `CurrentIdentity`, `Census`,
25
+ `FeedResult`, `AccessNote`) that keep the decoded response in `raw`.
26
+ - Typed errors: `KeyRequired` (401), `PaidKeyRequired` (402), `RateLimited` (429), `ObjectNotFound`,
27
+ `NotFound`, `InvalidRequest`, `ServerError`, `TransportError` and `UnexpectedResponse`, read from
28
+ every refusal shape the API sends.
29
+ - Retries with exponential backoff for timeouts, network errors, 429 and 5xx, honouring
30
+ `Retry-After` up to `max_retry_wait`.
31
+ - Identity bundles: `liquilens bundle build` writes the objects, keys, aliases and links tables as
32
+ CSV, Parquet or DuckDB with a manifest validated against the published bundle-manifest schema,
33
+ and labels a keyless build as partial. `liquilens bundle verify` checks every file's sha256 and
34
+ row count.
35
+ - The `liquilens` command: `resolve`, `describe`, `current-identity`, `census` and `bundle`.
36
+ - The merge kit, `liquilens_join` (also `liquilens join`): join your own file to the ontology on your
37
+ own machine. Standard-library only, it imports nothing from the client and opens no connection. It
38
+ profiles columns by check digits (LEI, CIN, GSTIN, IFSC; a PAN column is flagged and never read),
39
+ resolves offline in the public resolver's order, never picks between two candidates, sends
40
+ unmatched rows to a review queue with reasons and labelled suggestions, and learns from dated
41
+ review decisions stored locally. It refuses a bundle whose files differ from the manifest.
42
+ - Ranked, explained suggestions in the merge kit (`liquilens_join.linker`): nine Indian scripts,
43
+ a lending-name lexicon, a sign-constrained logistic regression fitted on the bundle and on the
44
+ reviewer's own decisions, bands with reasons, and CIN registration hints. Suggestions never
45
+ match a row; a reviewer decides. `liquilens join evaluate` measures them on held-out names
46
+ against the first suggester, and `liquilens join duplicates` lists records that may name one
47
+ institution twice. `isin_valid` and `cin_stem` join the validators.
48
+ - Dated joins: `--as-of` or `--date-column` decide what a reused name meant on a row's date
49
+ (the RRB names taken over on 1 May 2025) and fill `liquilens_id_on_date` from successions
50
+ in force on that date; the public resolver's answer for undated rows does not change. Reviewed
51
+ short forms (`text_aliases`) join after every server rule when low risk and valid on the
52
+ date; initials that need context only feed suggestions.
53
+ - Names in free text: `Linker.mention(span, context)` and `Mentions`. A key is exact; a span
54
+ inside a listed non-target name never matches; an everyday phrase (SCOWL common words) needs a
55
+ legal suffix, or name casing beside a finance word and then never ranks strong; a foreign bank
56
+ needs an India cue, else it is a group mention; context-risk initials need a finance word.
57
+ `liquilens join evaluate --mention` scores labelled mentions. Matching also improves for
58
+ district banks, head-office cities, renamed city spellings and RBI's "till" rows.
59
+ - The source distribution now includes `liquilens_join`.
60
+ - Optional extras: `pandas`, `parquet` (pyarrow) and `duckdb`.
61
+
62
+ ## openbb-liquilens 0.1.0 (unreleased)
63
+
64
+ ### Added
65
+
66
+ - OpenBB provider and router with `obb.liquilens.institution_lookup` and
67
+ `obb.liquilens.institution_profile`, backed by the `liquilens` client.
68
+ - The `note` column shows an object's type code and registered city or state, leaving out
69
+ research labels, as the identity feed does.
@@ -0,0 +1,22 @@
1
+ cff-version: 1.2.0
2
+ message: "If you use this software, please cite it as below."
3
+ type: software
4
+ title: "liquilens: Python client for the LiquiLens public API"
5
+ abstract: >-
6
+ A Python client for the LiquiLens public API. It reads the free identity layer of the LiquiLens
7
+ ontology (canonical ids, keys and typed links for Indian lenders, places and publishers) and
8
+ builds portable identity bundles in CSV, Parquet or DuckDB.
9
+ authors:
10
+ - name: "LiquiLens Private Limited"
11
+ version: "0.1.0"
12
+ license: MIT
13
+ url: "https://liquilens.in"
14
+ repository-code: "https://github.com/beepboop2025/liquilens-python"
15
+ keywords:
16
+ - liquilens
17
+ - ontology
18
+ - entity resolution
19
+ - India
20
+ - banks
21
+ - NBFC
22
+ - OData
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 LiquiLens Private Limited
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.
@@ -0,0 +1,320 @@
1
+ Metadata-Version: 2.5
2
+ Name: liquilens
3
+ Version: 0.1.0
4
+ Summary: Python client for the LiquiLens public API: canonical ids for Indian lenders, places and publishers, and portable identity bundles.
5
+ Project-URL: Homepage, https://liquilens.in
6
+ Project-URL: Repository, https://github.com/beepboop2025/liquilens-python
7
+ Project-URL: Issues, https://github.com/beepboop2025/liquilens-python/issues
8
+ Project-URL: Changelog, https://github.com/beepboop2025/liquilens-python/blob/main/CHANGELOG.md
9
+ Author: LiquiLens Private Limited
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: banks,entity-resolution,financial-data,india,liquilens,nbfc,odata,ontology
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: Financial and Insurance Industry
16
+ Classifier: Intended Audience :: Science/Research
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3 :: Only
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Topic :: Office/Business :: Financial
25
+ Classifier: Typing :: Typed
26
+ Requires-Python: >=3.10
27
+ Requires-Dist: httpx<1,>=0.27
28
+ Requires-Dist: jsonschema<5,>=4.18
29
+ Provides-Extra: duckdb
30
+ Requires-Dist: duckdb>=1.0; extra == 'duckdb'
31
+ Provides-Extra: pandas
32
+ Requires-Dist: pandas>=1.5; extra == 'pandas'
33
+ Provides-Extra: parquet
34
+ Requires-Dist: pyarrow>=14; extra == 'parquet'
35
+ Description-Content-Type: text/markdown
36
+
37
+ # liquilens
38
+
39
+ Python client for the LiquiLens public API.
40
+
41
+ LiquiLens publishes research screens over public records about Indian lenders. Every institution,
42
+ place and publisher it describes has one canonical id, such as `inst:in/rbi/dena-bank`, with the
43
+ keys each dataset uses for it (a CIN, an RBI label, a geography id) and typed links between them.
44
+ This package reads that free identity layer, follows succession links to the identity that carries
45
+ an institution today, and builds portable identity bundles in CSV, Parquet or DuckDB that join to
46
+ your own data on the same ids.
47
+
48
+ The package holds no scoring or engine logic. Every answer comes from the public HTTP API at
49
+ `https://api.liquilens.in`, and the package keeps nothing on disk unless you ask it to build a
50
+ bundle.
51
+
52
+ - Typed results for `resolve`, `describe`, `links`, `current_identity` and `census`
53
+ - Typed errors: `KeyRequired` (401), `PaidKeyRequired` (402), `RateLimited` (429) and more
54
+ - Retries with exponential backoff for 429 and 5xx, honouring `Retry-After`
55
+ - An OData identity feed reader that follows every page
56
+ - `liquilens bundle build`, with a manifest validated against the published bundle schema
57
+
58
+ An OpenBB provider lives in [`integrations/openbb`](integrations/openbb) as the separate
59
+ distribution `openbb-liquilens`.
60
+
61
+ ## Install
62
+
63
+ ```bash
64
+ pip install liquilens
65
+ ```
66
+
67
+ Optional extras keep the core install light (httpx and jsonschema only):
68
+
69
+ ```bash
70
+ pip install "liquilens[pandas]" # FeedResult.to_pandas()
71
+ pip install "liquilens[parquet]" # Parquet bundles (pyarrow)
72
+ pip install "liquilens[duckdb]" # DuckDB bundles
73
+ ```
74
+
75
+ Python 3.10 or later. To install from a checkout instead: `pip install .`
76
+
77
+ ## Quickstart
78
+
79
+ ```python
80
+ from liquilens import Client
81
+
82
+ with Client() as ll: # reads LIQUILENS_API_KEY when it is set
83
+ hit = ll.resolve("Dena Bank")
84
+ hit.status, hit.id, hit.rule # ('resolved', 'inst:in/rbi/dena-bank', 'rbi_label')
85
+
86
+ ll.resolve("Aurangabad").candidates # two districts share the name: ambiguous, never guessed
87
+ ll.resolve("No Such Lender").status # 'not_found': nothing is minted for an unknown name
88
+
89
+ dena = ll.describe(hit.id)
90
+ dena.label, dict(dena.keys) # ('Dena Bank', {'rbi_label': 'Dena Bank'})
91
+ for link in dena.links_in: # links are src -> dst, each with its basis in note
92
+ print(link.src, link.kind, link.dst, link.note)
93
+
94
+ today = ll.current_identity(hit.id)
95
+ today.id, today.chain # follows the dated 'succeeds' link to Bank of Baroda
96
+ today.stopped # 'no_successor'
97
+
98
+ census = ll.census() # counts the API generates, by kind and key space
99
+ census.by_kind, census.key_spaces
100
+ ```
101
+
102
+ Resolution never guesses. `status` is `resolved`, `ambiguous` (the candidates are listed and none is
103
+ picked) or `not_found`; the last two are results, not errors. `current_identity` stops and returns
104
+ the candidates when a predecessor has more than one successor, and says so in `stopped` when the
105
+ API capped the links it could check.
106
+
107
+ A predecessor keeps its own id and every figure printed under its name. Join on canonical ids or
108
+ keys, never on labels.
109
+
110
+ `OntologyObject.note` is the API's free-text context exactly as served. The identity feed, the
111
+ bundles and the OpenBB provider show only its type code and registered city or state.
112
+
113
+ ### The OData identity feed
114
+
115
+ ```python
116
+ from liquilens import Client, quote_literal
117
+
118
+ with Client() as ll:
119
+ banks = ll.feed("Institutions", filter=f"Category eq {quote_literal('Small finance bank (SFB)')}")
120
+ banks.rows[0]["Id"], banks.total, banks.complete
121
+ frame = banks.to_pandas() # needs liquilens[pandas]
122
+ ```
123
+
124
+ The feed has four entity sets: `Institutions`, `Places`, `Publishers` and `Links`. `feed()` follows
125
+ every `@odata.nextLink`, always from your configured origin, so a key is never sent to a host named
126
+ inside a response. Build string literals with `quote_literal`, never by pasting text into a filter.
127
+
128
+ ### Identity bundles
129
+
130
+ ```bash
131
+ liquilens bundle build ./ll-identity # CSV
132
+ liquilens bundle build ./ll-identity --format parquet --format duckdb --overwrite
133
+ liquilens bundle verify ./ll-identity
134
+ ```
135
+
136
+ ```python
137
+ from liquilens.bundle import build_bundle, verify_bundle
138
+
139
+ result = build_bundle("./ll-identity", formats=["csv", "duckdb"])
140
+ result.partial, result.reasons
141
+ verify_bundle(result.path).ok
142
+ ```
143
+
144
+ A bundle folder holds:
145
+
146
+ | File | Contents |
147
+ | --- | --- |
148
+ | `objects` | One row per object: `id`, `kind`, `label`, `jurisdiction`, `authority`, `note` |
149
+ | `keys` | One row per `(object_id, space, key)` |
150
+ | `aliases` | One row per `(object_id, alias)` |
151
+ | `links` | One row per link: `src`, `kind`, `dst`, `note` (the link's basis) |
152
+ | `manifest.json` | Build time, the API's source commit, transaction-time horizon, row counts and the sha256 of every file |
153
+ | `rights-rule.json` | The rights rule the bundle applied; its sha256 is the manifest's `register_sha256` |
154
+ | `NOTICE.txt` | What the bundle is, whether it is complete, and how to verify it |
155
+
156
+ The tables follow the bundle layout of the LiquiLens ontology specification (version 1, section
157
+ 9.2), with the same ids the API serves. CSV writes one file per table, Parquet one file per table,
158
+ DuckDB one `liquilens.duckdb` database with all four tables and primary keys that enforce their
159
+ invariants.
160
+
161
+ Notes on the columns:
162
+
163
+ - `jurisdiction` and `authority` are the id's own lowercase segments (`in`, `rbi`), as the id
164
+ grammar defines them.
165
+ - `note` is the feed's plain-English category for an institution and the level (`state`,
166
+ `district`) for a place.
167
+ - The feed joins aliases with `"; "`, and the builder splits them on that separator.
168
+ - The feed leaves out every object, key and link known only through a source that may not be
169
+ redistributed in bulk. `describe` still serves those one at a time.
170
+
171
+ The manifest validates against the published `bundle-manifest.schema.json`, which the package
172
+ vendors. It records `spec_version` 1.0, because the bundle section of the specification is a
173
+ proposal for version 1.1 that has not been released. `source_commit` comes from the API's
174
+ `GET /api/v1/release/identity`; if the API releases a new version while a bundle is being read,
175
+ the build stops rather than mix two versions. A bundle holds identity only, no facts, so
176
+ `commercial_only` is false and no source verdict was applied; `rights-rule.json` states that rule.
177
+
178
+ **Without a key a bundle is partial, and says so.** The feed gives a caller without a key the first
179
+ 50 positions of any query and a daily budget of 500 rows, so a keyless build is a sample of each
180
+ entity set. The manifest sets `scope.partial` with a reason per entity set, `NOTICE.txt` opens with
181
+ `Status: PARTIAL`, and the command prints the same. With a key, every page is followed and the
182
+ bundle is complete. The API key is never written to a bundle.
183
+
184
+ ## What is free and what needs a key
185
+
186
+ **Free, without a key** (within rate limits): the identity layer. Canonical ids, names, keys,
187
+ aliases, typed links and the census, through `resolve`, `describe`, `links`, `current_identity` and
188
+ `census`, plus the OData identity feed for lookups: the first 50 positions of any query and 500 rows
189
+ a day, with no range comparisons or ordered walks.
190
+
191
+ **Needs an API key:**
192
+
193
+ - The whole identity feed in bulk, every row and every query option: a free key.
194
+ - Facts, point-in-time (as-of) history and bulk depth on the research routes: a free or a paid key,
195
+ depending on the sources a response cites.
196
+ - The source link behind each figure: a paid key.
197
+
198
+ Version 0.1.0 of this client reads only the identity layer. The API names anything it withholds:
199
+ `OntologyObject.access`, `Census.access` and `FeedResult.access` carry its note, and a refused
200
+ request raises `KeyRequired` or `PaidKeyRequired` with the API's own `how_to_get_access` text. The
201
+ limits above are the API's at the time of writing; the API's notes are authoritative. For a key, see
202
+ [liquilens.in](https://liquilens.in).
203
+
204
+ Set the key in the environment rather than in code:
205
+
206
+ ```bash
207
+ export LIQUILENS_API_KEY=llk_v1_...
208
+ ```
209
+
210
+ ## Examples
211
+
212
+ Two notebooks in [`examples/`](examples) call the live free endpoints. They are committed without
213
+ outputs, so this repository redistributes no figures; run them to see results.
214
+
215
+ - [`01_resolve_your_institution_list.ipynb`](examples/01_resolve_your_institution_list.ipynb):
216
+ resolve a list of Indian lender names to canonical ids, keep ambiguous and unknown names as
217
+ results, follow succession links, and see where point-in-time facts need a key.
218
+ - [`02_real_signal_or_noise.ipynb`](examples/02_real_signal_or_noise.ipynb): ask whether a public
219
+ money-market spread from Seiche really changed, with NoiseFloor's change tests, and how the same
220
+ tests apply to LiquiLens lender panels named by canonical id.
221
+
222
+ ```bash
223
+ pip install . noisefloor jupyterlab # from a checkout
224
+ jupyter lab examples/
225
+ ```
226
+
227
+ Without a key neither notebook calls a route that needs one. Drafts for publishing the identity
228
+ bundle on Hugging Face and Kaggle are in [`datasets/`](datasets); nothing has been uploaded.
229
+
230
+ ## Excel and Power BI
231
+
232
+ The identity feed is an OData v4 service, so Excel and Power BI read it without an add-in.
233
+
234
+ Feed URL:
235
+
236
+ ```
237
+ https://api.liquilens.in/api/experimental/v1/ontology/odata
238
+ ```
239
+
240
+ **Excel (Microsoft 365, Windows):** Data > Get Data > From Other Sources > From OData Feed. Paste
241
+ the feed URL, choose Anonymous, then pick `Institutions`, `Places`, `Publishers` or `Links` in the
242
+ Navigator and load them. Excel for Mac offers the OData feed source only in some builds; check yours
243
+ before relying on it.
244
+
245
+ **Power BI Desktop:** Get data > OData feed, paste the feed URL, choose Anonymous, and pick the tables.
246
+
247
+ Join your sheets on the `Id` column. To attach your own list of lenders, resolve each name or CIN once
248
+ (`liquilens resolve "Dena Bank"`) and keep the returned id.
249
+
250
+ Without a key each table loads its first 50 rows. To load every row with a key, add the header in
251
+ Power Query's Advanced Editor, keeping the key in a Power Query parameter rather than in the query
252
+ text:
253
+
254
+ ```
255
+ OData.Feed(
256
+ "https://api.liquilens.in/api/experimental/v1/ontology/odata/Institutions",
257
+ [Authorization = "Bearer " & LiquiLensKey]
258
+ )
259
+ ```
260
+
261
+ Do not share a workbook that holds a key.
262
+
263
+ ## Errors
264
+
265
+ | Exception | When |
266
+ | --- | --- |
267
+ | `KeyRequired` | HTTP 401: the request needs a free API key, or the keyless allowance is used up |
268
+ | `PaidKeyRequired` | HTTP 402: the request needs a paid API key |
269
+ | `RateLimited` | HTTP 429 after retries; `retry_after` holds the API's wait in seconds |
270
+ | `ObjectNotFound` | `describe` of an id no object has |
271
+ | `NotFound`, `InvalidRequest`, `ServerError`, `APIError` | Other HTTP errors |
272
+ | `TransportError` | Connection failures and timeouts after retries |
273
+ | `UnexpectedResponse` | A response this client does not recognise |
274
+
275
+ `KeyRequired` and `PaidKeyRequired` are `AccessError`s and carry `depth`, `what`, `requires`, `tier`,
276
+ `message` and `how_to_get_access` when the API sent them. Every error derives from `LiquiLensError`.
277
+
278
+ ## Retries and limits
279
+
280
+ ```python
281
+ Client(
282
+ api_key=None, # or LIQUILENS_API_KEY
283
+ base_url=None, # or LIQUILENS_BASE_URL, else https://api.liquilens.in
284
+ timeout=30.0,
285
+ retries=3, # timeouts, network errors, 429 and 5xx
286
+ backoff=0.5, # 0.5 s, 1 s, 2 s ... capped at 30 s
287
+ max_retry_wait=60.0, # a longer Retry-After is raised as RateLimited at once
288
+ )
289
+ ```
290
+
291
+ A daily allowance refusal carries a long `Retry-After`; the client raises it instead of sleeping.
292
+
293
+ ## Security and privacy
294
+
295
+ - The key is read from the `api_key` argument or `LIQUILENS_API_KEY`, sent only to the configured
296
+ origin as `Authorization: Bearer`, never logged, never shown in `repr`, and never written to a
297
+ bundle. The command line reads it from the environment only.
298
+ - `base_url` must be HTTPS (plain HTTP only on a loopback address) and a bare origin.
299
+ - Redirects are never followed, responses are size-capped, and paging links are requested from the
300
+ configured origin only.
301
+ - If the API reports that it did not accept a key, the client warns once (`LiquiLensWarning`).
302
+
303
+ See [SECURITY.md](SECURITY.md) to report a vulnerability.
304
+
305
+ ## Development
306
+
307
+ ```bash
308
+ python -m pip install -e . --group dev # pip 25.1 or later
309
+ pytest # offline: every request is mocked
310
+ ruff check . && ruff format --check . && mypy
311
+ LIQUILENS_LIVE=1 pytest tests/test_live.py # about ten requests to the real API
312
+ ```
313
+
314
+ The tests never touch the network unless `LIQUILENS_LIVE=1` is set. The OpenBB provider has its own
315
+ tests under `integrations/openbb/tests`.
316
+
317
+ ## Licence
318
+
319
+ MIT, see [LICENSE](LICENSE). Data served by the API stays subject to the terms LiquiLens and its
320
+ sources state for it.