# dpm-xl

> Parser and evaluator for the EBA DPM-XL validation-rule language. dpm-xl parses DPM-XL expressions, evaluates them against report data supplied through a small provider interface, with EBA interval arithmetic and null logic, and explains each failing record in plain numbers.

Python 3.11+, no runtime dependencies (`pip install dpm-xl`; the `columnar` extra adds a polars evaluator). Independent project, not affiliated with or endorsed by the EBA. Everything below in one file: https://luukhopman.github.io/dpm-xl/llms-full.txt

## Home

- [dpm-xl](https://luukhopman.github.io/dpm-xl/index.md): What dpm-xl is, who it is for, a 30-second example and where to go next.

## Getting started

- [Getting started](https://luukhopman.github.io/dpm-xl/getting-started.md): Install dpm-xl, evaluate a first rule against in-memory data, read the explanation and use the CLI.

## How-to guides

- [How-to guides](https://luukhopman.github.io/dpm-xl/guides/index.md): Task-oriented recipes for connecting data, evaluating and explaining rules, scaling up and building tooling.
- [Connect your data](https://luukhopman.github.io/dpm-xl/guides/provider.md): Write a DataProvider for your own storage, including the optional open_keys, table_group, operation and earlier_report hooks.
- [Evaluate a rule file](https://luukhopman.github.io/dpm-xl/guides/rule-files.md): Evaluate every rule of a rule file against one report, in Python or with dpm-xl eval, and read the results.
- [Explain failures in a UI](https://luukhopman.github.io/dpm-xl/guides/explain.md): Turn a failing record into a sentence, a filled formula and the cells to highlight, for a review screen or an API response.
- [Evaluate large reports](https://luukhopman.github.io/dpm-xl/guides/columnar.md): Evaluate rules on polars frames for reports with millions of open-table rows, falling back to the reference evaluator on ColumnarUnsupported.
- [Run rules in threads](https://luukhopman.github.io/dpm-xl/guides/threads.md): Evaluate the rules of one report concurrently, with the caches and providers that are safe to share across threads.
- [Compare with earlier reports](https://luukhopman.github.io/dpm-xl/guides/time-shift.md): Evaluate time_shift against earlier reports through earlier_report, shift date keys within a report, and annualise year-to-date amounts.
- [Check rule syntax in CI](https://luukhopman.github.io/dpm-xl/guides/ci.md): Fail a CI job when a rule in a rule repository does not parse, with dpm-xl check or a pytest test.
- [Build editor support](https://luukhopman.github.io/dpm-xl/guides/editor.md): Build syntax highlighting, error squiggles, quick fixes and completion for DPM-XL with the tokenizer, diagnose, the grammar module and the TextMate grammar.
- [Analyse rules statically](https://luukhopman.github.io/dpm-xl/guides/analyse.md): Read a rule without evaluating it - the expression tree, the selections with their with-context applied, the tables and the filing indicators it tests.
- [From an XBRL report to explained failures](https://luukhopman.github.io/dpm-xl/guides/end-to-end.md): Read an xBRL-CSV report with dpm-xbrl, bind its facts to a dpm-xl provider, evaluate rules with the columnar engine and the reference fallback, and explain the failures.
- [Toolkit tour](https://luukhopman.github.io/dpm-xl/guides/toolkit-tour.md): One report through the dpm toolkit - generate it with dpm-synth, read it with dpm-xbrl, then evaluate and explain its DPM-XL rules with dpm-xl.

## Concepts

- [Concepts](https://luukhopman.github.io/dpm-xl/concepts/index.md): The semantics of DPM-XL as dpm-xl implements them, and where the specification leaves a choice.
- [Records and keys](https://luukhopman.github.io/dpm-xl/concepts/records-and-keys.md): How selections become keyed records, how operators join them, and how key names match.
- [Null logic](https://luukhopman.github.io/dpm-xl/concepts/null.md): Missing facts, defaults, three-valued logic, conditionals and record-level errors such as division by zero.
- [Interval arithmetic](https://luukhopman.github.io/dpm-xl/concepts/intervals.md): How reported precision (XBRL decimals) turns numbers into intervals, how arithmetic and comparisons treat them, and why explanations report a gap.
- [Preconditions and results](https://luukhopman.github.io/dpm-xl/concepts/results.md): The five rule statuses, what preconditions do, and what a RuleResult and its outcomes hold.
- [Statements and assignments](https://luukhopman.github.io/dpm-xl/concepts/statements.md): Scripts of several statements, temporary assignments with := and persistent assignments with <-.
- [Sets](https://luukhopman.github.io/dpm-xl/concepts/sets.md): Set literals, set parameters, set_of and the set operators, and how in tests membership.
- [Aggregates and analytic functions](https://luukhopman.github.io/dpm-xl/concepts/analytics.md): Aggregates with group by, and analytic functions (rank and windowed aggregates) with partitions, ordering and windows.
- [Time](https://luukhopman.github.io/dpm-xl/concepts/time.md): Dates, the date functions, time_shift across reports and date keys, and annualise.
- [Parameters, operations and table groups](https://luukhopman.github.io/dpm-xl/concepts/references.md): Filing indicators, report parameters, typed parameters, operation references and table groups, and the reference prefixes.

## Reference

- [Reference](https://luukhopman.github.io/dpm-xl/reference/index.md): Reference material - the language, the CLI, the data formats and the Python API.
- [Quick reference](https://luukhopman.github.io/dpm-xl/reference/quick-reference.md): DPM-XL on one page - statements, selections, references, literals, operators by precedence, clauses, every function and the complete grammar, each linked to its language reference entry.
- [Language reference](https://luukhopman.github.io/dpm-xl/reference/language.md): The complete DPM-XL language as dpm-xl implements it - lexical rules, precedence, and every statement, selection, reference, operator, clause and function with its syntax, types, null and interval behaviour, errors and verified examples.
- [CLI](https://luukhopman.github.io/dpm-xl/reference/cli.md): The dpm-xl command line - check and eval, every option, the exit statuses and the JSON output schema.
- [Data formats](https://luukhopman.github.io/dpm-xl/reference/data-formats.md): The JSON rule file and data file formats that dpm-xl check and dpm-xl eval read.
- [Python API](https://luukhopman.github.io/dpm-xl/reference/api/index.md): The public Python API of dpm-xl, module by module, and the names re-exported from the dpmxl package.
- [`dpmxl.evaluator`](https://luukhopman.github.io/dpm-xl/reference/api/evaluator.md): API reference for dpmxl.evaluator: evaluate_rule, RuleResult, Outcome, SelectionCache and the thread-safety guarantees.
- [`dpmxl.explain`](https://luukhopman.github.io/dpm-xl/reference/api/explain.md): API reference for dpmxl.explain: explain, Explanation, Side and Operand.
- [`dpmxl.provider`](https://luukhopman.github.io/dpm-xl/reference/api/provider.md): API reference for dpmxl.provider: the DataProvider protocol, MemoryProvider, DataPoint, CellQuery and the axis matchers.
- [`dpmxl.columnar`](https://luukhopman.github.io/dpm-xl/reference/api/columnar.md): API reference for dpmxl.columnar: evaluate_rule_columnar, FrameProvider, FrameCache, the frame schema and the thread-safety guarantees.
- [`dpmxl.parser`](https://luukhopman.github.io/dpm-xl/reference/api/parser.md): API reference for dpmxl.parser: parse, parse_program, parse_selection, tokenize, Token and DpmXlSyntaxError.
- [`dpmxl.ast`](https://luukhopman.github.io/dpm-xl/reference/api/ast.md): API reference for dpmxl.ast: the expression tree, selections, axis selectors, items, walk and children.
- [`dpmxl.grammar`](https://luukhopman.github.io/dpm-xl/reference/api/grammar.md): API reference for dpmxl.grammar: keywords, operators, function names, token kinds and the TextMate grammar.
- [`dpmxl.values`](https://luukhopman.github.io/dpm-xl/reference/api/values.md): API reference for dpmxl.values: Number with interval tolerance, ValueSet, compare and formatting.
- [`dpmxl.recordset`](https://luukhopman.github.io/dpm-xl/reference/api/recordset.md): API reference for dpmxl.recordset: keyed record sets, the natural join and the evaluation errors.
- [`dpmxl.references`](https://luukhopman.github.io/dpm-xl/reference/api/references.md): API reference for dpmxl.references: static selections with their with-context applied, tables and filing-indicator templates.
- [`dpmxl.diagnostics`](https://luukhopman.github.io/dpm-xl/reference/api/diagnostics.md): API reference for dpmxl.diagnostics: positioned problems in an expression, from syntax errors to unknown tables and coordinates.

## AI agents

- [Using dpm-xl with AI agents](https://luukhopman.github.io/dpm-xl/agents.md): The essential dpm-xl API on one page for AI agents and their users - contracts, a complete example and common pitfalls.

## Related

The other packages of the dpm toolkit:

- [dpm-xbrl](https://luukhopman.github.io/dpm-xbrl/llms.txt): Read, write and check xBRL-CSV and XBRL-XML reports.
- [dpm-synth](https://luukhopman.github.io/dpm-synth/llms.txt): Generate test reports that satisfy DPM-XL rules.
- [Toolkit tour](https://luukhopman.github.io/dpm-xl/guides/toolkit-tour.md): Generate a report with dpm-synth, read it with dpm-xbrl, then evaluate and explain its rules with dpm-xl.

## Optional

- [Changelog](https://luukhopman.github.io/dpm-xl/project/changelog.md): Every release of dpm-xl and what changed in it.
- [Stability and versioning](https://luukhopman.github.io/dpm-xl/project/stability.md): What the public API is, what semantic versioning promises for it, and what may change in minor releases.
- [Benchmarks](https://luukhopman.github.io/dpm-xl/project/benchmarks.md): dpm-xl compared with pydpm-xl and dpmcore on capabilities, licence, parse speed, coverage of the EBA rules, footprint and error messages.
- [Security](https://luukhopman.github.io/dpm-xl/project/security.md): How to report a vulnerability, and what dpm-xl does and does not protect against when it parses and evaluates rules.
- [Contributing](https://luukhopman.github.io/dpm-xl/project/contributing.md): Set up a development environment, run the checks, write docs and send a change.
- [Licence](https://luukhopman.github.io/dpm-xl/project/licence.md): dpm-xl is released under the MIT licence.