How goldmansachs/jdmn-python-runtime works
Project Type and Purpose
• This project is a runtime library for processing DMN (Decision Model and Notation) and evaluating FEEL (Friendly Enough Expression Language). Its purpose is to serve as a lightweight engine to interpret and execute decision tables and expressions defined in DMN models.
• The README confirms it’s meant for installation via pip, and the file tree shows a modular, well-organized library structure with clearly separated functional areas, unit tests, CI scripts, and configuration files.
Analyzing the File Structure
• Top-level directories and files such as src/, tests/, and CI-related files indicate that the project is built around a clear separation of concerns (core runtime vs. FEEL language processing vs. testing).
• The src/jdmn directory is the core of the library and is split into subdirectories:
• src/jdmn/feel: Houses the FEEL implementation. The lib/ folder further breaks down into modules for base logic, standard libraries, and type-specific libraries (e.g., for booleans, numeric values, strings, dates/times, lists, ranges).
• src/jdmn/runtime: Contains classes for executing decisions (like DMNDecision, ExecutionContext, and DMNRuntimeException), along with utility modules such as caching, discovery, external execution, annotations, and event listeners.
• This level of granularity (e.g., type-specific comparators and libraries) points to a design that lends itself to modularization and possibly plug-and-play extensibility of individual FEEL type implementations.
Components
• Core DMN Runtime Engine:
• Central DMN engine that manages the execution context, decision processing, and exception handling.
• Classes like DMNDecision, ExecutionContext, and DMNRuntimeException.
• FEEL Evaluation Engine:
• Base and Standard FEEL Libraries (BaseFEELLib, BaseStandardFEELLib, DefaultStandardFEELLib)
• Specialized libraries for handling different types: Boolean, Numeric, List, Context, Range, String, and Temporal types.
• Type comparator modules for ordering and equality (such as ComparableComparator, EqualityComparator, etc.)
• Supporting Subsystems:
• External Function Executor: Outline the module that allows for external function execution (DefaultExternalFunctionExecutor), which likely integrates with external systems or libraries.
• Cache: Highlight the caching layer (DefaultCache) that supports runtime optimization.
• Event Listener Subsystem: Include modules from the listener directory (e.g., LoggingEventListener, NopEventListener) that handle events, rules, and annotations during DMN execution.
• Discovery and Registry: Briefly note modules such as ModelElementRegistry for discovery of model elements.
• Annotations: Represent how annotations (Annotation, AnnotationSet) are used to add metadata or runtime instrumentation.
• Infrastructure and CI/CD:
Relationships and Interactions
• The DMN Runtime Engine calls into the FEEL Evaluation Engine to perform its expression evaluations.
• The FEEL Engine, in turn, uses type-specific libraries to execute operations based on operand types.
• External function calls route through the External Function Executor, feeding back into the core execution context.
• The caching and event listener subsystems interact with the runtime to optimize performance and log/monitor decision executions.
• Data flow from input (decision context) to processing layers (FEEL library evaluation, decision resolution) and then to output (decision results).
Architectural Patterns and Design Principles
• Modular design: Each major domain (FEEL evaluation, DMN runtime, type libraries) is encapsulated within its own module and likely communicates via well-defined interfaces.
• Separation of concerns: Different components (e.g., evaluators vs. execution context) perform distinct roles, making the system easier to maintain and extend.
• Extensibility: The presence of multiple “Default” implementations (e.g., DefaultStandardFEELLib, DefaultCache) indicates an architecture built to allow alternative implementations or plugging in additional features if needed.
Relevant Technologies, Frameworks, and Libraries
• Python is the central language.
• Testing is handled by pytest and tox (as seen in the README and tests/ directory).
• CI/CD integration is managed via GitHub workflows and additional scripts in the ci/ directory.
• Static analysis and quality assurance are ensured by tools (pylint, flake8) as referenced in the configuration files.