ndeleh-fba 1.1.0

N-FBA V2: A modern fishbone root-cause reasoning engine for industrial diagnostics.

Ndeleh Fishbone Algorithm (Ndeleh-FBA)

Author: Andrew Ndeleh Mbavaya
<<<<<<< HEAD License: MIT
Current Version: 1.1.0

Ndeleh-FBA is a human-inspired causal reasoning framework designed to model cause → effect relationships in complex systems.
It began as a simple fishbone (Ishikawa-style) graph and evolved into a memory-like associative reasoning engine capable of supporting industrial diagnostics, adaptive workflows, and future healthcare applications.

Why Ndeleh-FBA Exists

In real systems—factories, logistics, healthcare, human memory—failure rarely comes from a single cause.
Instead, problems emerge from chains of weak signals.

Ndeleh-FBA was built to:

• Preserve causality
• Surface hidden contributors
• Avoid halting entire systems when only one component struggles
• Mimic how humans recall related information (association-based memory)

Version History Overview

Version 1 — Fishbone Core (Baseline)

Focus: Structural causality

Features:

• Lightweight graph model
• Nodes represent causes
• Weighted edges represent influence strength
• Deterministic traversal

Use when you need:

• Clear root-cause visualization
• Simple cause → effect reasoning

Version 2 — Associative / Memory-Inspired Reasoning

Focus: Contextual awareness & association

Enhancements:

• Spine extraction
• Micro-spine propagation
• Morphological grouping
• Inspired by hippocampal memory recall (association chaining)

Use when you need:

• Context preservation
• Pattern recognition across events
• Reasoning beyond single failures

Version 3 (Current) — Industrial Intelligence (Torque + Forklift)

Focus: Real-time industrial diagnostics without stopping production

Adds:

• Torque anomaly diagnosis
• Retry / jam / red-flag reasoning
• Forklift operational analysis
• Partial-line continuation logic (system adapts instead of halting)

Key idea:

If one station struggles, the entire line does not need to stop.

Use when:

• Downtime is expensive
• Safety and continuity must coexist
• Operators need decision support, not replacement

Forklift Intelligence (v1.1.0)

Ndeleh-FBA now supports forklift-specific reasoning:

Detected conditions:

• Load imbalance
• Excessive vibration
• Unsafe tilt angles
• Operator behavior anomalies
• Environmental interference

Output includes:

• Root cause
• Confidence score
• Safe continuation recommendation
• Escalation only when required

Installation

pip install ndeleh-fba

Or for development:

pip install -e .

**Maintainer:** NDELEH  
**License:** MIT  
**Status:** Actively developed  



## 🌍 Overview

The **Ndeleh Fishbone Algorithm (Ndeleh-FBA)** is a causal-reasoning and diagnostic framework inspired by classical Ishikawa (fishbone) diagrams and extended with modern computational reasoning.

Unlike traditional rule-based systems, Ndeleh-FBA models **cause–effect relationships as weighted graphs**, allowing systems to reason about failures, inefficiencies, and anomalies in complex environments such as industrial operations, logistics, and decision-support systems.

This repository documents the **evolution of the algorithm across three major stages**, each expanding its reasoning depth and real-world applicability.


## 🧬 Evolution of the Algorithm

### 🔹 Version 1 — Core Fishbone Graph (Baseline)
**Focus:** Structural causal reasoning

- Graph-based cause–effect modeling
- Nodes represent causes or factors
- Weighted edges represent influence strength
- Deterministic spine construction
- Visualization utilities for fishbone diagrams

**Use cases:**
- Root cause analysis
- Quality control
- Process diagnostics
- Education & visualization


### 🔹 Version 2 — Contextual & Memory-Inspired Reasoning
**Focus:** Adaptive reasoning inspired by associative memory


Basic Usage
Graph Construction

from ndeleh_fba.graph import Graph

g = Graph()
g.add_edge("torque", "tool_wear", 0.9)
g.add_edge("machine", "operator", 0.8)

Industrial Torque Analysis

from ndeleh_fba.industrial.industrial_logic import analyze_torque_event

result = analyze_torque_event(
    torque_value=25,
    target_min=22,
    target_max=30,
    is_red_flag=False,
    jam_detected=False,
    cycle_time=3.1,
    retries=0,
    manual_check_used=False
)

Forklift Analysis

from ndeleh_fba.industrial.forklift_logic import analyze_forklift_event

result = analyze_forklift_event(
    load_weight=1200,
    max_capacity=1500,
    tilt_angle=3.5,
    vibration_level=0.2,
    operator_alert=True
)

Visualization

from ndeleh_fba.visualize import plot_fishbone
plot_fishbone(g)

This version extends the baseline fishbone model with **contextual propagation** inspired by how memory recall works in humans.

Key additions:
- Seed-based reasoning (starting from an observed event)
- Dynamic spine and micro-spine extraction
- Weighted propagation of influence
- Context-aware root cause ranking

**Use cases:**
- Industrial diagnostics
- Complex fault analysis
- Systems where causes are not linear
- Environments with uncertainty or partial data


### 🔹 Version 3 — Industrial & Operational Intelligence
**Focus:** Real-world operational diagnostics


This version introduces **domain-specific reasoning layers**, allowing Ndeleh-FBA to operate directly on operational signals.


Design Philosophy

Humans reason by association, not brute force

Systems should adapt before escalating

AI should assist, not replace

Continuity > interruption

Memory matters

#### 🏭 Industrial Torque Analysis
- Under-torque / over-torque detection
- Red-flag event handling
- Retry and manual-intervention reasoning
- Structured diagnostic outputs
- Confidence scoring

#### 🚜 Forklift Operational Diagnostics
- Load imbalance detection
- Speed and braking anomalies
- Operator behavior indicators
- Environmental risk factors
- Early warning reasoning before failures escalate

**Use cases:**
- Manufacturing floors
- Warehouses & logistics
- Safety-critical operations
- Preventive maintenance systems



## 🧠 Why Ndeleh-FBA Is Different

- Graph-native causal reasoning (not black-box AI)
- Explainable outputs
- Deterministic + adaptive hybrid logic
- Human-interpretable diagnostics
- Designed for environments where **trust, safety, and clarity matter**


## 📦 Installation


What’s Next (Announced)

Adaptive line-balancing logic

Healthcare reasoning models

Memory-support systems for cognitive health

Public-space early detection tools


Disclaimer

```bash
pip install ndeleh-fba

Or for development:

git clone https://github.com/NDELEH/ndeleh-fba.git
cd ndeleh-fba
python -m venv venv
source venv/bin/activate
pip install -e .

🧪 Testing
python -m pytest -q

📊 Visualization

Ndeleh-FBA includes visualization utilities for fishbone diagrams:

from ndeleh_fba.visualize import plot_fishbone

🚀 Current Capabilities

✔ Root cause analysis
✔ Contextual reasoning
✔ Industrial diagnostics
✔ Forklift safety intelligence
✔ Explainable causal graphs

🔮 Ongoing Work

The algorithm is actively evolving to support:

Additional operational domains

Broader human-centered reasoning applications

Assistive systems for decision support

(Details will be announced publicly as development progresses.)

📄 Citation

If you use Ndeleh-FBA in research or applied work, please cite the associated research paper.

🤝 Contributing

Contributions, testing, and feedback are welcome.
This project prioritizes clarity, safety, and real-world usefulness.

🧑‍💻 Author

Andrew Ndeleh Mbavaya
Creator of the Ndeleh Fishbone Algorithm

GitHub: https://github.com/NDELEH



This project is a decision-support system.
It does not replace human judgment, medical advice, or safety protocols.

Acknowledgment

This algorithm emerged from lived experience, memory reconstruction techniques, and real-world system observation.

Ndeleh-FBA is about understanding systems the way humans do.