# luckychiller/lutufi architecture

> Architecture diagram of the GitHub repository luckychiller/lutufi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luckychiller/lutufi
- Repository: https://github.com/luckychiller/lutufi

## Overview

Lutufi is a Rust probabilistic graphical-model and network-analysis library with a Python API. The main workflow is to construct a Bayesian network, provide probability tables, query through an inference engine, and receive marginal results. The Rust core also supports learning, causal and structural analysis, dynamic models, and format interoperability. The graph follows the sampled Python-to-Rust inference path; several README capabilities are represented at their documented subsystem paths, but their internal wiring is not inferred where source was not sampled.

Main entry points: [`src/core/inference/strategy_factory.rs`](https://github.com/luckychiller/lutufi/blob/main/src/core/inference/strategy_factory.rs) (Strategy selection), [`src/core/models/bayesian_network.rs`](https://github.com/luckychiller/lutufi/blob/main/src/core/models/bayesian_network.rs) (Bayesian networks), [`bindings/ffi/inference.rs`](https://github.com/luckychiller/lutufi/blob/main/bindings/ffi/inference.rs) (Inference bindings), [`bindings/ffi/learning.rs`](https://github.com/luckychiller/lutufi/blob/main/bindings/ffi/learning.rs) (Learning bindings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Python API"]
  node_py_models["Model API<br/>[models.py]"]
  node_py_inference["Inference API<br/>[inference.py]"]
  node_py_learning["Learning API<br/>[learning.py]"]
  node_py_io["Python I/O<br/>[io.py]"]
  node_ffi_models["Model bindings<br/>[models.rs]"]
  node_ffi_inference["Inference bindings<br/>[inference.rs]"]
  node_ffi_learning["Learning bindings<br/>[learning.rs]"]
  node_ffi_network["Network bindings<br/>[network.rs]"]
  node_result["Query result<br/>[inference.py]"]
end

subgraph group_models["Models and factors"]
  node_bn["Bayesian networks"]
  node_builder["Network builder"]
  node_factors["Factors and CPTs<br/>[mod.rs]"]
  node_dbn["Dynamic networks"]
end

subgraph group_inference["Inference"]
  node_inference_engine["Inference facade<br/>[engine.rs]"]
  node_strategy_factory["Strategy selection"]
  node_ve["Variable elimination"]
  node_junction["Junction tree<br/>[junction_tree.rs]"]
  node_approx["Approximate inference<br/>[lbp.rs]"]
  node_sampling["MCMC and variational<br/>[mcmc.rs]"]
  node_temporal["Temporal queries<br/>[temporal_query.rs]"]
end

subgraph group_learning["Learning and analysis"]
  node_learning_core["Parameter learning<br/>[parameter.rs]"]
  node_structure_learning["Structure learning<br/>[mod.rs]"]
  node_causal["Causal analysis<br/>[mod.rs]"]
  node_network_science["Network science<br/>[mod.rs]"]
end

subgraph group_io["Interoperability"]
  node_core_io["Format conversion<br/>[mod.rs]"]
  node_formats["BIF UAI LMF<br/>[mod.rs]"]
end

node_user(("Python user"))

node_user -->|"builds model"| node_py_models
node_user -->|"submits query"| node_py_inference
node_user -->|"learns model"| node_py_learning
node_user -->|"imports or exports"| node_py_io
node_py_models -->|"wraps model"| node_ffi_models
node_ffi_models -->|"builds"| node_builder
node_builder -->|"creates"| node_bn
node_bn -->|"stores probabilities"| node_factors
node_py_inference -->|"calls engines"| node_ffi_inference
node_ffi_inference -->|"runs query"| node_inference_engine
node_inference_engine -->|"selects strategy"| node_strategy_factory
node_strategy_factory -->|"dispatches"| node_ve
node_strategy_factory -->|"dispatches"| node_junction
node_strategy_factory -->|"dispatches"| node_approx
node_strategy_factory -->|"dispatches"| node_sampling
node_inference_engine -->|"reads model"| node_bn
node_ffi_inference -->|"packs result"| node_result
node_py_learning -->|"calls estimators"| node_ffi_learning
node_ffi_learning -->|"estimates parameters"| node_learning_core
node_ffi_learning -->|"learns structure"| node_structure_learning
node_ffi_network -->|"runs analysis"| node_network_science
node_bn -->|"supports causal analysis"| node_causal
node_dbn -->|"queried by"| node_temporal
node_py_io -->|"uses formats"| node_core_io
node_core_io -->|"handles"| node_formats

click node_py_models "https://github.com/luckychiller/lutufi/blob/main/bindings/python/lutufi/models.py"
click node_py_inference "https://github.com/luckychiller/lutufi/blob/main/bindings/python/lutufi/inference.py"
click node_py_learning "https://github.com/luckychiller/lutufi/blob/main/bindings/python/lutufi/learning.py"
click node_py_io "https://github.com/luckychiller/lutufi/blob/main/bindings/python/lutufi/io.py"
click node_ffi_models "https://github.com/luckychiller/lutufi/blob/main/bindings/ffi/models.rs"
click node_ffi_inference "https://github.com/luckychiller/lutufi/blob/main/bindings/ffi/inference.rs"
click node_ffi_learning "https://github.com/luckychiller/lutufi/blob/main/bindings/ffi/learning.rs"
click node_ffi_network "https://github.com/luckychiller/lutufi/blob/main/bindings/ffi/network.rs"
click node_bn "https://github.com/luckychiller/lutufi/blob/main/src/core/models/bayesian_network.rs"
click node_builder "https://github.com/luckychiller/lutufi/blob/main/src/core/models/bayesian_network_builder.rs"
click node_factors "https://github.com/luckychiller/lutufi/blob/main/src/core/factor/mod.rs"
click node_dbn "https://github.com/luckychiller/lutufi/blob/main/src/core/models/dynamic_bayesian_network.rs"
click node_inference_engine "https://github.com/luckychiller/lutufi/blob/main/src/core/inference/engine.rs"
click node_strategy_factory "https://github.com/luckychiller/lutufi/blob/main/src/core/inference/strategy_factory.rs"
click node_ve "https://github.com/luckychiller/lutufi/blob/main/src/core/inference/variable_elimination.rs"
click node_junction "https://github.com/luckychiller/lutufi/blob/main/src/core/inference/junction_tree.rs"
click node_approx "https://github.com/luckychiller/lutufi/blob/main/src/core/inference/lbp.rs"
click node_sampling "https://github.com/luckychiller/lutufi/blob/main/src/core/inference/mcmc.rs"
click node_temporal "https://github.com/luckychiller/lutufi/blob/main/src/core/inference/dbn/temporal_query.rs"
click node_learning_core "https://github.com/luckychiller/lutufi/blob/main/src/core/learning/parameter.rs"
click node_structure_learning "https://github.com/luckychiller/lutufi/blob/main/src/core/learning/structure/mod.rs"
click node_causal "https://github.com/luckychiller/lutufi/blob/main/src/core/models/causal_model/mod.rs"
click node_network_science "https://github.com/luckychiller/lutufi/blob/main/src/core/network/mod.rs"
click node_core_io "https://github.com/luckychiller/lutufi/blob/main/src/core/io/mod.rs"
click node_formats "https://github.com/luckychiller/lutufi/blob/main/src/core/io/lmf/mod.rs"
click node_result "https://github.com/luckychiller/lutufi/blob/main/bindings/python/lutufi/inference.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_py_models,node_py_inference,node_py_learning,node_py_io,node_ffi_models,node_ffi_inference,node_ffi_learning,node_ffi_network,node_result,node_user toneBlue
class node_bn,node_builder,node_factors,node_dbn toneAmber
class node_inference_engine,node_strategy_factory,node_ve,node_junction,node_approx,node_sampling,node_temporal toneMint
class node_learning_core,node_structure_learning,node_causal,node_network_science toneRose
class node_core_io,node_formats toneIndigo
```

## Components

### Python API

- [Model API](https://github.com/luckychiller/lutufi/blob/main/bindings/python/lutufi/models.py): `bindings/python/lutufi/models.py`
- [Inference API](https://github.com/luckychiller/lutufi/blob/main/bindings/python/lutufi/inference.py): `bindings/python/lutufi/inference.py`
- [Learning API](https://github.com/luckychiller/lutufi/blob/main/bindings/python/lutufi/learning.py): `bindings/python/lutufi/learning.py`
- [Python I/O](https://github.com/luckychiller/lutufi/blob/main/bindings/python/lutufi/io.py): `bindings/python/lutufi/io.py`
- [Model bindings](https://github.com/luckychiller/lutufi/blob/main/bindings/ffi/models.rs): `bindings/ffi/models.rs`
- [Inference bindings](https://github.com/luckychiller/lutufi/blob/main/bindings/ffi/inference.rs): `bindings/ffi/inference.rs`
- [Learning bindings](https://github.com/luckychiller/lutufi/blob/main/bindings/ffi/learning.rs): `bindings/ffi/learning.rs`
- [Network bindings](https://github.com/luckychiller/lutufi/blob/main/bindings/ffi/network.rs): `bindings/ffi/network.rs`
- [Query result](https://github.com/luckychiller/lutufi/blob/main/bindings/python/lutufi/inference.py): `bindings/python/lutufi/inference.py`

### Models and factors

- [Bayesian networks](https://github.com/luckychiller/lutufi/blob/main/src/core/models/bayesian_network.rs): `src/core/models/bayesian_network.rs`
- [Network builder](https://github.com/luckychiller/lutufi/blob/main/src/core/models/bayesian_network_builder.rs): `src/core/models/bayesian_network_builder.rs`
- [Factors and CPTs](https://github.com/luckychiller/lutufi/blob/main/src/core/factor/mod.rs): `src/core/factor/mod.rs`
- [Dynamic networks](https://github.com/luckychiller/lutufi/blob/main/src/core/models/dynamic_bayesian_network.rs): `src/core/models/dynamic_bayesian_network.rs`

### Inference

- [Inference facade](https://github.com/luckychiller/lutufi/blob/main/src/core/inference/engine.rs): `src/core/inference/engine.rs`
- [Strategy selection](https://github.com/luckychiller/lutufi/blob/main/src/core/inference/strategy_factory.rs): `src/core/inference/strategy_factory.rs`
- [Variable elimination](https://github.com/luckychiller/lutufi/blob/main/src/core/inference/variable_elimination.rs): `src/core/inference/variable_elimination.rs`
- [Junction tree](https://github.com/luckychiller/lutufi/blob/main/src/core/inference/junction_tree.rs): `src/core/inference/junction_tree.rs`
- [Approximate inference](https://github.com/luckychiller/lutufi/blob/main/src/core/inference/lbp.rs): `src/core/inference/lbp.rs`
- [MCMC and variational](https://github.com/luckychiller/lutufi/blob/main/src/core/inference/mcmc.rs): `src/core/inference/mcmc.rs`
- [Temporal queries](https://github.com/luckychiller/lutufi/blob/main/src/core/inference/dbn/temporal_query.rs): `src/core/inference/dbn/temporal_query.rs`

### Learning and analysis

- [Parameter learning](https://github.com/luckychiller/lutufi/blob/main/src/core/learning/parameter.rs): `src/core/learning/parameter.rs`
- [Structure learning](https://github.com/luckychiller/lutufi/blob/main/src/core/learning/structure/mod.rs): `src/core/learning/structure/mod.rs`
- [Causal analysis](https://github.com/luckychiller/lutufi/blob/main/src/core/models/causal_model/mod.rs): `src/core/models/causal_model/mod.rs`
- [Network science](https://github.com/luckychiller/lutufi/blob/main/src/core/network/mod.rs): `src/core/network/mod.rs`

### Interoperability

- [Format conversion](https://github.com/luckychiller/lutufi/blob/main/src/core/io/mod.rs): `src/core/io/mod.rs`
- [BIF UAI LMF](https://github.com/luckychiller/lutufi/blob/main/src/core/io/lmf/mod.rs): `src/core/io/lmf/mod.rs`

### Other components

- **Python user**

## Connections

- Python user → Model API: builds model
- Python user → Inference API: submits query
- Python user → Learning API: learns model
- Python user → Python I/O: imports or exports
- Model API → Model bindings: wraps model
- Model bindings → Network builder: builds
- Network builder → Bayesian networks: creates
- Bayesian networks → Factors and CPTs: stores probabilities
- Inference API → Inference bindings: calls engines
- Inference bindings → Inference facade: runs query
- Inference facade → Strategy selection: selects strategy
- Strategy selection → Variable elimination: dispatches
- Strategy selection → Junction tree: dispatches
- Strategy selection → Approximate inference: dispatches
- Strategy selection → MCMC and variational: dispatches
- Inference facade → Bayesian networks: reads model
- Inference bindings → Query result: packs result
- Learning API → Learning bindings: calls estimators
- Learning bindings → Parameter learning: estimates parameters
- Learning bindings → Structure learning: learns structure
- Network bindings → Network science: runs analysis
- Bayesian networks → Causal analysis: supports causal analysis
- Dynamic networks → Temporal queries: queried by
- Python I/O → Format conversion: uses formats
- Format conversion → BIF UAI LMF: handles