Skip to main content

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_keys lists 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. With include_citation_in_text=False there is no Source: line and citation is 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, language and, for case law, ecli, court, decision_date.

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). With unresolved="drop" it is left out; with unresolved="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=False leaves 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)

Source distribution for llama-index-retrievers-lexapi 0.1.0
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)

Table of built distributions (wheels) for llama-index-retrievers-lexapi 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page