Skip to main content

langchain-lexapi

LangChain retrievers and tools for EU law from LexAPI: EU legislation article by article, CJEU case law, and the text of an act for a date, each with its CELEX citation.

  • LexAPILegislationRetriever: semantic search over EU legislation, optionally for a date (as_of).
  • LexAPICaseLawRetriever: semantic search over CJEU case law.
  • Tools: lexapi_search_legislation, lexapi_read_document (a document or one article) and lexapi_legislation_as_of (the version of an act listed for a date, and one provision of it).

Documents and tool outputs are built by the SDK's lexapi.passages module, so this package applies the same citation and date rules as the Python SDK.

Install

pip install langchain-lexapi

It needs Python 3.11 or later, langchain-core 1.4 or later and the LexAPI Python SDK. Get an API key from the LexAPI dashboard and set LEXAPI_API_KEY, or pass api_key=.

Examples

Legislation, for a date. Each document's page_content is the text followed by a Source: line with the citation, so a stock LangChain prompt shows the model where the text comes from:

from langchain_lexapi import LexAPILegislationRetriever

retriever = LexAPILegislationRetriever(k=3, as_of="2019-06-01")
docs = retriever.invoke("right to erasure")
for doc in docs:
    print(doc.page_content)
    # No cite_celex when a consolidated text does not name its act.
    print(doc.metadata.get("cite_celex"), doc.metadata["text_withheld"])

Case law. A hit's text is the whole decision; max_chars bounds it: the 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 a note says so. The note and the Source: line come on top of the bound:

from langchain_lexapi import LexAPICaseLawRetriever

retriever = LexAPICaseLawRetriever(k=2, max_chars=4000, court="Court of Justice")
docs, report = retriever.invoke_with_report("right to be forgotten")
print(len(docs), "documents;", report.units_charged, "credits charged")

Tools, for an agent or a tool-calling model. Each returns the text for the model and, as the artifact, the passages' metadata and the call's report:

from langchain_lexapi import (
    LexAPILegislationAsOfTool,
    LexAPIReadDocumentTool,
    LexAPISearchLegislationTool,
)

tools = [LexAPISearchLegislationTool(), LexAPIReadDocumentTool(), LexAPILegislationAsOfTool()]
as_of = tools[2]
message = as_of.invoke(
    {
        "type": "tool_call",
        "id": "call-1",
        "name": as_of.name,
        "args": {"celex": "32016R0679", "as_of": "2019-06-01", "provision": "art_17"},
    }
)
print(message.content)
print(message.artifact["report"]["units_charged"])

lexapi_read_document returns at most max_chars (default 20,000) characters of text per call, in whole articles from the first: once an article does not fit what is left, it and every later article are listed by reference instead, so the model can ask for one. Only the first article is cut, when it alone is longer than max_chars (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 then nothing else is shown. The numbering, the cut note, the Source: lines and that list come on top of the bound. The tool's report counts truncated (texts cut) and not_shown. The tool's description states the budget.

Pass your own SDK clients with client= (a lexapi.LexAPI) and async_client= (a lexapi.AsyncLexAPI) to control timeouts, retries and their lifetime: this package never closes a client you pass in. Without them, each retriever or tool builds its own clients from api_key (or LEXAPI_API_KEY) and base_url: the sync client at construction, the async client on first async use. Close those with close() (sync client) or aclose() (both), or use the object as a context manager (with / async with). With only client=, async calls run the sync client in an executor; with only async_client=, sync calls are refused. Unknown constructor arguments raise a validation error.

A model_copy (or copy.copy) shares the clients of the object it was copied from but never closes them, and cannot change the connection settings; a deep copy or pickle is refused, since the object holds an open client.

What a document holds

  • page_content: lexapi.passages.format_passage(passage): the text, or a one-line notice when there is no text, then Source: <citation>. With include_citation_in_content=False it is the text or notice alone.
  • metadata: passage.metadata() unchanged (flat strings, numbers and booleans; never the text), plus source, LangChain's usual key, set to the passage's url when it has one. Always present: kind, celex, text_status, text_withheld, consolidated, citation, id. Present when known: cite_celex, article_ref, article_number, article_title, title, language, url, eli, score, base_celex, consolidated_as_of, consolidated_note, as_of, as_of_resolved, as_of_reason, version_celex, version_kind, version_date, version_valid_until, ecli, case_number, court, decision_date, document_type, paragraph_number.
  • id: passage.id, lexapi:<celex>:<part>:<as_of>:<language>. It is the same on every call that returns the same passage. Within one result, passages with the same id are returned once. They rank: a text from the API, then a latest text under a label (keep_labelled), then a notice or no text. A later passage replaces the earlier one only if it ranks strictly higher, and the document keeps the position of the first.
  • metadata["score"] is the API's score, unchanged.

The text for a date

  • With as_of, the API answers each hit with the version listed for that date. A hit it could not establish for the date still carries its latest text in the API response. By default (unresolved="withhold") this package does not pass that text on; "drop" leaves the hit out, and "keep_labelled" passes the latest text on under a label saying it is not established for the date.
  • unresolved="withhold" (the default) returns such a hit as a document whose content is a notice with the reason, and metadata["text_withheld"] = True. "drop" leaves it out. "keep_labelled" returns the latest text under a label saying it is not established for the date. emit_withheld=False leaves the notices out.
  • Do not index documents with metadata["text_withheld"] = True in a vector store: they hold a notice, not a text.
  • lexapi_legislation_as_of returns a notice with the reason, and no text, when LexAPI cannot establish the version or the text for the date. It does not say whether a provision applied on that date.

k and the celex restriction

k is the number of hits asked for. Fewer documents can come back: the API's relevance floor, withheld or dropped texts, de-duplication. The retrievers never ask for more hits to make up the number. celex= keeps only passages of the given acts (and their consolidated texts). The API cannot limit a search to one act, so this filters the k hits after the search: it costs the same as the search without it, and the result can be shorter than k or empty. Raise k if you need more candidates; the search costs the same, but with as_of more hits can mean more version fetches.

Credits

Each call draws credits from your LexAPI plan. As documented by the API today:

  • Legislation search: 5 credits. With as_of, each version LexAPI does not hold yet is fetched (at most 3 per search), at 0 to 5 credits each.
  • Case-law search: 5 credits.
  • lexapi_read_document: 5 credits, settled at 1 when LexAPI already holds the document and 4 when it is read from the Publications Office.
  • lexapi_legislation_as_of: 1 credit when no text is fetched; 4 or 5 when the provision's text is fetched; 1 if that fetch finds no text.

See the API reference for current prices. To see what a call cost, use invoke_with_report / ainvoke_with_report on a retriever (it returns the documents and a RetrievalReport with units_charged, credits_remaining, the core's withheld, labelled, dropped and filtered counts, and what was returned: returned, returned_withheld, returned_labelled), read artifact["report"] of a tool message, or handle the lexapi_retrieval_report callback event, which every retriever call sends on its own run. The report is per call and is not stored on the retriever, so concurrent calls do not mix.

Errors

An error is never turned into an empty list. An answer LexAPI's client cannot read raises an error; a 2xx answer is never retried, and never read as an empty result. A result can still be empty without an error: no hit above the relevance floor, a celex restriction that matched nothing, hits left out by unresolved="drop" or emit_withheld=False, or hits without a CELEX number.

  • After close() / aclose(), retrievers raise langchain_lexapi.ClientClosedError (<Class> is closed; create a new one.); tools raise ToolException with the same text. So does a model_copy once the object it was copied from has closed the clients it built: a copy shares those clients and never closes them.

  • Retrievers raise the SDK's exceptions unchanged, with the API's own message (nothing is masked or reworded): lexapi.CreditsExhaustedError (402), lexapi.PaymentPastDueError (403, a subclass of lexapi.TierForbiddenError), lexapi.RateLimitedError (429, after the SDK's own retries), lexapi.AuthenticationError (401), and the rest of lexapi.LexAPIError.

  • Tools raise langchain_core.tools.ToolException. For a LexAPI error its text is one line:

    LexAPI error CODE (HTTP n): <the API's message>.
      then, each only when it applies, in this order:
      Credits reset at <t>.                            credits exhausted
      This is an exhausted quota, not a rate limit.    RateLimitedError.quota_exhausted
      Quota resets at <t>.                             the same, when the time is known
      Access ended at <t>.                             PaymentPastDueError
      Billing: <url>                                   the same, unless the message holds the link
      Retry after <n> s.                               only where LexAPI's client retries
    LexAPI error CODE: <message>.                      no HTTP status (a connection error)
    Invalid argument: <what is wrong>                  refused before any request
    <Class> is closed; create a new one.               use after close()
    

    The server's strings are put on one line (control characters and line breaks become spaces) and capped: the message at 1,000 characters, a time or link at 200 (… marks a cut); a blank one is left out. Anything shaped like an API key is masked.

  • A wait (Retry after 7 s.) is given only for an error LexAPI's client retries: a 429 rate limit, or a 521/522/523 (the request never reached LexAPI), with a wait from the server above 0. Never for a failed payment, an exhausted quota, credits or another 4xx, nor for another 5xx: the tools' calls are POSTs, which the client does not retry on a 5xx with its default settings.

  • Other details an error carries (an upgrade or accept link, a 404's reason, a national allowance's reset time) are not in the text; read them from the exception.

  • An answer that could not be read gives LexAPI error INVALID_RESPONSE (HTTP 200): The answer could not be read. and quotes nothing from it; an answer without its documented fields (no document, say) is rejected by LexAPI's client and gives that same text. A few further checks are this package's own: a document without a celex, a fullText that is not a string, or a blank as-of document gives the text without the status, LexAPI error INVALID_RESPONSE: The answer could not be read.. Neither is ever a "no text" answer. An argument that matches the tool's schema but is an impossible date (2099-02-30), or a query or celex that is only whitespace, gives Invalid argument: ... (for example Invalid argument: query must not be empty) before any request; retrievers raise InvalidArgumentError with the same text without the prefix; an argument that does not match the tool's schema (as_of="1 June 2099") raises the framework's validation error. A configuration error (such as a tool given only an async_client and called synchronously) is raised as itself.

  • Set handle_tool_error=True on a tool to hand that text to the model instead of raising. With handle_tool_error=True the model reads this text and may repeat it to the person it is talking to, including a failed payment and the billing link; an application that handles billing itself should catch the error instead.

The API key is never logged, never in repr() and never serialised.

The same error text in your own tools

tool_error(error) turns a lexapi.LexAPIError into the ToolException these tools raise, with the same text and the same masking; anything else raises TypeError. Use it in a tool of your own that calls the SDK:

from langchain_core.tools import tool
from lexapi import LexAPI, LexAPIError

from langchain_lexapi import tool_error

client = LexAPI()


@tool
def lexapi_cited_by(celex: str) -> str:
    """List the documents that cite an EU act, by its CELEX number."""
    try:
        page = client.citations.cited_by(celex)
    except LexAPIError as error:
        raise tool_error(error) from error
    return "\n".join(item["id"] for item in page["citedBy"])

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. It is not legal advice.
  • Consolidated texts have no legal force: they are documentation. Cite the act as published in the Official Journal (metadata["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, by default (unresolved="withhold") this package returns a notice with the reason LexAPI gave, not the text; "drop" leaves the hit out, and "keep_labelled" returns the latest text under a label saying it is not established for the date.
  • It does not call a language model, build prompts or chains, embed texts or cache results.

Tests

The tests run offline against synthetic fixtures: no request reaches LexAPI, a model provider or LangSmith. They do not cover the live service.

pip install -e ".[dev]"
pytest

License

MIT. See LICENSE.

Metadata

Release files for langchain-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 langchain-lexapi 0.1.0
File Size Uploaded Provenance Actions
langchain_lexapi-0.1.0.tar.gz 62.9 kB Without provenance Details for langchain_lexapi-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for langchain-lexapi 0.1.0
File Interpreter ABI Platform Actions
langchain_lexapi-0.1.0-py3-none-any.whl Python 3 none any Details for langchain_lexapi-0.1.0-py3-none-any.whl

Total release size: 92.4 kB

Release files / langchain_lexapi-0.1.0.tar.gz

Download URL langchain_lexapi-0.1.0.tar.gz
Size 62.9 kB
Tags Source
SHA-256 checksum
How to use checksums
39e877e4e1ff3766f8ea6c101e239e2b79c59ca2390568b722a0f63622d082eb
BLAKE2b-256 checksum
How to use checksums
98327e47ddde74faf690ca247f2cac49102ed86ad72c2926d4c2a14d4d811ba2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.6

Release files / langchain_lexapi-0.1.0-py3-none-any.whl

Download URL langchain_lexapi-0.1.0-py3-none-any.whl
Size 29.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f57c714ef25797a3d0e2d204c063391c8b7006737c5ef9c8c43fbaa35b817a2d
BLAKE2b-256 checksum
How to use checksums
c4fc8dccb89ee2360fac6a6ef9b0a1a706b64926db884e931624714d4478828e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.6

Security for langchain-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