ndeleh-fba 1.1.0
N-FBA V2: A modern fishbone root-cause reasoning engine for industrial diagnostics.
License: Apache-2.0
Requires Python: >=3.9
Keywords: fishbone, root-cause, diagnostics, industrial, quality, graphs, manufacturing, AI, N-FBA

# 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

```bash
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.