llama-index-retrievers-lexapi
LlamaIndex retrievers for EU legislation and CJEU case law from LexAPI, with a citation on every node.
LexAPILegislationRetriever: articles of EU legislation by meaning, optionally in the version LexAPI lists for a date (as_of).LexAPICaseLawRetriever: decisions of the Court of Justice of the EU by meaning.
Install
pip install llama-index-retrievers-lexapi
Python 3.11 or later. You need a LexAPI key (lex_...) from your LexAPI
dashboard, in the environment as LEXAPI_API_KEY or passed as api_key=.
Usage
from llama_index.retrievers.lexapi import LexAPILegislationRetriever
retriever = LexAPILegislationRetriever(similarity_top_k=5)
for item in retriever.retrieve("right to erasure of personal data"):
meta = item.node.metadata
# cite_celex is absent for a consolidated text whose act LexAPI did not name.
print(item.score, meta.get("cite_celex"), meta["citation"])
print(item.node.get_content())
Inside a query engine, with the LLM of your choice:
from llama_index.core.query_engine import RetrieverQueryEngine
engine = RetrieverQueryEngine.from_args(retriever, llm=my_llm)
print(engine.query("When must a controller erase personal data?"))
To use your own SDK clients (timeouts, retries, base URL), pass them in. In an async context:
from lexapi import AsyncLexAPI, LexAPI
retriever = LexAPILegislationRetriever(LexAPI(), AsyncLexAPI())
nodes = await retriever.aretrieve("own funds requirements")
retrieve uses the sync client and aretrieve the async one. With only a
sync client, aretrieve runs it in a worker thread; with only an async
client, retrieve raises ValueError. A client you pass in is never
closed. Clients the retriever builds from a key (the async one on first
async use) are closed by close() (the sync one) or await aclose()
(both), or by leaving a with / async with block; the retriever is then
closed and refuses further calls.
Nodes
Each hit becomes one TextNode in a NodeWithScore:
| Node field | Value |
|---|---|
text |
The text, then a Source: line with the citation. With include_citation_in_text=False, the text alone. |
id_ |
lexapi:<celex>:<part>:<as_of>:<language>, stable across calls |
metadata |
The passage's citation fields (below), never the text |
score |
The API's similarity score, unchanged |
The text and metadata are built by lexapi.passages in the LexAPI Python
SDK, so every LexAPI integration shows the same citation and notices.
Metadata keys (present when known): kind, celex, cite_celex,
citation, id, text_status, text_withheld, consolidated,
base_celex, consolidated_as_of, consolidated_note, article_ref,
article_number, article_title, title, language, url, eli, score,
as_of, as_of_resolved, as_of_reason, version_celex, version_kind,
version_date, version_valid_until, and for case law ecli,
case_number, court, decision_date, document_type,
paragraph_number.
- Embedding: no metadata key is embedded
(
excluded_embed_metadata_keyslists them all). - LLM view: the citation is read once, in the
Source:line; the keys the model sees are listed below.- Hidden (
EXCLUDED_LLM_METADATA_KEYS):base_celex,celex,citation,eli,id,kind,score,text_withheld,url,version_celex,version_date,version_kind,version_valid_until. Withinclude_citation_in_text=Falsethere is noSource:line andcitationis shown instead. - Seen: every other key that is present, among them
cite_celex,consolidated,consolidated_note,as_of,as_of_resolved,as_of_reason,text_status,title,article_ref,languageand, for case law,ecli,court,decision_date.
- Hidden (
The text for a date
retriever = LexAPILegislationRetriever(as_of="2019-06-01")
The date must be a real calendar day in the form YYYY-MM-DD (or a
datetime.date); anything else raises ValueError before any request.
- A text is passed on as the text for the date only when LexAPI established it for that date.
- Any other hit is kept as a node whose text is a notice with LexAPI's
reason and no text (
unresolved="withhold", the default). Withunresolved="drop"it is left out; withunresolved="keep_labelled"the latest indexed text is kept, labelled as not established for the date. - Withheld nodes have
metadata["text_withheld"] == True. Do not index or embed them;emit_withheld=Falseleaves them out of the results. - The date is set per retriever. LlamaIndex's
retrieve()takes only the query, so for another date build another retriever.
Restricting to one act
celex="32016R0679" keeps only hits of that act and its consolidated texts.
The search itself cannot be limited to an act: the retriever filters the
similarity_top_k hits it asked for, so the result can be shorter or empty.
It never asks for more hits to make up the number.
Case law
LexAPICaseLawRetriever always asks for the full text of each decision
(include_text=True). The text of a node is the whole decision, which can
be long. With max_chars=N (at least 200) a longer text is cut at a
paragraph break when one falls in the second half of the limit, otherwise
at a line break or a space there, otherwise at the limit, and the cut is
marked with [Text cut by llama-index-retrievers-lexapi: K of M characters shown. The full text is at the source.] before the Source: line. The
default is the whole decision. The search snippet and
the machine-written summary are never used as text. Filters: court,
date_from, date_to.
Credits
similarity_top_k is the number of hits requested. A legislation search
costs 5 credits; with as_of, each version LexAPI does not hold is fetched
(up to 3 per search) at 0-5 credits each. A case-law search
costs 5 credits. See the LexAPI API reference for the current prices.
What a call did is reported per call, never stored on the retriever:
nodes, report, result = retriever.retrieve_with_result("right to erasure")
print(report.requested, report.returned, report.units_charged, report.credits_remaining)
report is a LexAPICallReport: requested, returned, as_of, the
core's counters withheld, kept_labelled, dropped, uncitable and
filtered_out (counted before de-duplication), returned_withheld,
returned_labelled, withheld_not_emitted, duplicates, truncated
(returned texts that were cut), not_shown (always 0 for the retrievers),
units_charged, credits_remaining and hint. result is the call's
lexapi.passages.PassageResult. Inside a query engine, subscribe an
instrumentation event handler to LexAPIRetrievalEvent, which carries both
for every retrieval.
Nodes keep the API's order. Two hits with the same node id are merged: the first position is kept, and a later hit replaces the earlier one only when it carries more (a text over a labelled latest text over a notice). Each node keeps its own score, so after a merge the scores need not be descending.
Errors
Arguments are checked before any request and refused with
InvalidArgumentError, a ValueError importable from
llama_index.retrievers.lexapi: an empty or whitespace-only query (query must not be empty), and the constructor's similarity_top_k, max_chars,
unresolved, as_of, date_from and date_to. A bad celex restriction
and wrong client wiring raise a plain ValueError. A closed retriever raises
ClientClosedError before any other check.
An error is never turned into an empty list. An answer LexAPI's client
cannot read raises an error; it is never read as an empty result, and a 2xx
answer is never retried. A result
can be empty when the search had no hits, when celex filtered every hit
out, when
unresolved="drop" left every hit out, when emit_withheld=False left out
withheld hits, or when the API sent hits without a CELEX number (counted in
report.uncitable). SDK exceptions are raised unchanged; an API error's
message is the API's own text. For example: lexapi.CreditsExhaustedError
(402), lexapi.PaymentPastDueError (403), lexapi.RateLimitedError (429),
lexapi.AuthenticationError (401), and lexapi.InvalidResponseError for
an answer that could not be read. Using a retriever after close() raises
ClientClosedError.
lexapi.PaymentPastDueError derives from lexapi.TierForbiddenError:
catch it first to tell a failed payment from a plan gate.
RateLimitedError.quota_exhausted (with resets_at, when the quota
refills) tells an exhausted quota from a per-minute rate limit; the SDK
retries a rate limit; it does not retry a 429 that is an exhausted quota.
What this package does not do
- LexAPI provides source texts and citations. It does not assess whether anyone complies with the law, and neither does this package.
- Consolidated texts are documentation tools without legal force. Cite the
act as published in the Official Journal (
cite_celex). - A text is passed on as the text for a date only when LexAPI established it
for that date. For any other hit this package passes on no text, with the
reason LexAPI gave, unless you opt into
unresolved="keep_labelled", which passes on the latest text labelled as not established for the date. - Not legal advice. A retriever sees only what the search returned.
Tests
The tests run offline against synthetic fixtures, with mock LLM and embedding models. They do not cover the live service.
Licence
MIT
Metadata
Release files for llama-index-retrievers-lexapi 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| llama_index_retrievers_lexapi-0.1.0.tar.gz | 15.7 kB | Without provenance | Details for llama_index_retrievers_lexapi-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| llama_index_retrievers_lexapi-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for llama_index_retrievers_lexapi-0.1.0-py3-none-any.whl |
Total release size: 32.8 kB
Release files / llama_index_retrievers_lexapi-0.1.0.tar.gz
| Download URL | llama_index_retrievers_lexapi-0.1.0.tar.gz |
|---|---|
| Size | 15.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ea9e5c7aca2f2eda246833e945a0cb0d7c5b8c6efa8a85fa13742c0e99193157
|
|
BLAKE2b-256 checksum How to use checksums |
972c969e92a0a5a52d5db0b406313f17d44e5418ac1208a8caaf53c3b62bb39e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.6
|
Release files / llama_index_retrievers_lexapi-0.1.0-py3-none-any.whl
| Download URL | llama_index_retrievers_lexapi-0.1.0-py3-none-any.whl |
|---|---|
| Size | 17.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
84a8dcf7ecc2c1f0b353f139e6c4e56922f39a74b524fea7dfb97bb3361f5e2e
|
|
BLAKE2b-256 checksum How to use checksums |
b018e9f5cb1511bf7f5c4b9240d3f46c2e47c7e2b3a9cb2233c4ec547f993b71
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.6
|
Security for llama-index-retrievers-lexapi 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.