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.
- liquilens-0.1.0/.gitignore +26 -0
- liquilens-0.1.0/CHANGELOG.md +69 -0
- liquilens-0.1.0/CITATION.cff +22 -0
- liquilens-0.1.0/LICENSE +21 -0
- liquilens-0.1.0/PKG-INFO +320 -0
- liquilens-0.1.0/README.md +284 -0
- liquilens-0.1.0/SECURITY.md +42 -0
- liquilens-0.1.0/pyproject.toml +103 -0
- liquilens-0.1.0/src/liquilens/__init__.py +78 -0
- liquilens-0.1.0/src/liquilens/_http.py +226 -0
- liquilens-0.1.0/src/liquilens/_version.py +1 -0
- liquilens-0.1.0/src/liquilens/bundle/__init__.py +35 -0
- liquilens-0.1.0/src/liquilens/bundle/build.py +239 -0
- liquilens-0.1.0/src/liquilens/bundle/data/bundle-manifest.schema.json +50 -0
- liquilens-0.1.0/src/liquilens/bundle/data/rights-rule.json +9 -0
- liquilens-0.1.0/src/liquilens/bundle/manifest.py +163 -0
- liquilens-0.1.0/src/liquilens/bundle/tables.py +131 -0
- liquilens-0.1.0/src/liquilens/bundle/writers.py +119 -0
- liquilens-0.1.0/src/liquilens/cli.py +161 -0
- liquilens-0.1.0/src/liquilens/client.py +315 -0
- liquilens-0.1.0/src/liquilens/errors.py +189 -0
- liquilens-0.1.0/src/liquilens/ids.py +80 -0
- liquilens-0.1.0/src/liquilens/models.py +413 -0
- liquilens-0.1.0/src/liquilens/odata.py +105 -0
- liquilens-0.1.0/src/liquilens/py.typed +0 -0
- liquilens-0.1.0/src/liquilens_join/__init__.py +87 -0
- liquilens-0.1.0/src/liquilens_join/__main__.py +99 -0
- liquilens-0.1.0/src/liquilens_join/bundle_check.py +81 -0
- liquilens-0.1.0/src/liquilens_join/data/SCOWL-Copyright.txt +248 -0
- liquilens-0.1.0/src/liquilens_join/data/common_words.txt.gz +0 -0
- liquilens-0.1.0/src/liquilens_join/dates.py +65 -0
- liquilens-0.1.0/src/liquilens_join/evaluate.py +332 -0
- liquilens-0.1.0/src/liquilens_join/kit.py +310 -0
- liquilens-0.1.0/src/liquilens_join/linker.py +913 -0
- liquilens-0.1.0/src/liquilens_join/mention.py +276 -0
- liquilens-0.1.0/src/liquilens_join/normalize.py +55 -0
- liquilens-0.1.0/src/liquilens_join/profile.py +99 -0
- liquilens-0.1.0/src/liquilens_join/resolver.py +376 -0
- liquilens-0.1.0/src/liquilens_join/textkey.py +347 -0
- liquilens-0.1.0/src/liquilens_join/validators.py +129 -0
- liquilens-0.1.0/tests/__init__.py +0 -0
- liquilens-0.1.0/tests/conftest.py +67 -0
- liquilens-0.1.0/tests/fake_api.py +432 -0
- liquilens-0.1.0/tests/fixtures/census.json +183 -0
- liquilens-0.1.0/tests/fixtures/object_bank_of_baroda.json +42 -0
- liquilens-0.1.0/tests/fixtures/object_dena_bank.json +30 -0
- liquilens-0.1.0/tests/fixtures/object_not_found_404.json +7 -0
- liquilens-0.1.0/tests/fixtures/release_identity.json +8 -0
- liquilens-0.1.0/tests/fixtures/resolve_ambiguous.json +9 -0
- liquilens-0.1.0/tests/fixtures/resolve_not_found.json +6 -0
- liquilens-0.1.0/tests/fixtures/resolve_resolved.json +6 -0
- liquilens-0.1.0/tests/test_as_of.py +195 -0
- liquilens-0.1.0/tests/test_bundle.py +321 -0
- liquilens-0.1.0/tests/test_cli.py +107 -0
- liquilens-0.1.0/tests/test_client.py +210 -0
- liquilens-0.1.0/tests/test_errors.py +103 -0
- liquilens-0.1.0/tests/test_feed.py +202 -0
- liquilens-0.1.0/tests/test_http.py +231 -0
- liquilens-0.1.0/tests/test_ids.py +55 -0
- liquilens-0.1.0/tests/test_join.py +278 -0
- liquilens-0.1.0/tests/test_linker.py +301 -0
- liquilens-0.1.0/tests/test_live.py +51 -0
- liquilens-0.1.0/tests/test_mention.py +140 -0
- liquilens-0.1.0/tests/test_mention_precision.py +80 -0
- 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
|
liquilens-0.1.0/LICENSE
ADDED
|
@@ -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.
|
liquilens-0.1.0/PKG-INFO
ADDED
|
@@ -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.
|