DEV Community: Alain Airom (Ayrom)

Securing Your GenAI Pipeline: Automated PII Obfuscation with Docling & Microsoft Presidio

Alain Airom (Ayrom) — Fri, 22 May 2026 10:38:42 +0000

Architecting an Open-Source Document Anonymizer with Docling, Presidio, and Bob

Introduction-PII (Personally identifiable information)

As organizations increasingly rely on GenAI, Large Language Models (LLMs), and cloud-driven analytics, data has become both an enterprise’s greatest asset and its biggest liability. Every day, millions of documents — ranging from PDFs and slide decks to emails and spreadsheets — flow through corporate pipelines. Hidden within this unstructured data is a wealth of Personally Identifiable Information (PII): names, phone numbers, credit card details, financial statements, and geographic locations.

Leaving this data exposed is no longer just a technical oversight; it is a massive compliance and security risk. However, protecting this information isn’t a one-size-fits-all task. Depending on the objective, different workflows demand entirely different approaches to handling sensitive data.

Feeding GenAI and RAG Pipelines (Context Preservation)

When preparing documents for Retrieval-Augmented Generation (RAG) or fine-tuning LLMs, the goal is to protect privacy without destroying the utility of the text. If you completely delete a name or a location, the model loses the semantic context required to understand relationships within the document.

The Need: Anonymization or Pseudonymization (Masking/Replacing).
The Strategy: Replacing a specific name like “John Doe” with a generic token like [PERSON_1] or [EMPLOYEE] allows the LLM to maintain grammatical and logical coherence while keeping the actual individual completely anonymous.

Analytical and Database Processing (Data Linking)

Data engineering teams often need to analyze user behavior, processing trends, or system logs across multiple datasets without knowing exactly who the users are.

The Need: Consistency and Reversibility (Hashing/Encryption).
The Strategy: Using cryptographic Hashing (like SHA-256) ensures that the same PII always results in the same unique string. This allows analysts to join tables and track trends over time without exposing raw data. Alternatively, reversible encryption is used when downstream automated systems must temporarily hide PII but authorized users eventually need to decrypt and view the original values.

Regulatory Compliance and Public Release (Absolute Security)

When sharing documents with third-party vendors, publishing legal discovery files, or complying with strict data privacy mandates like GDPR, CCPA, or HIPAA, there is zero margin for error.

The Need: Irreversible Elimination (Redaction).
The Strategy: Redaction completely strips the text or burns a black bar over the sensitive areas. Once redacted, the original data is destroyed and cannot be recovered by any mathematical or algorithmic means, ensuring total compliance.

The Modern Challenge: Parsing Meets Detection

Implementing these varied obfuscation strategies requires a two-step dance: first, you must accurately extract text and layout structure from complex, messy enterprise documents (such as multi-column PDFs or scanned charts). Second, you must accurately detect and transform the PII without breaking the document’s formatting.

Balancing data utility with absolute privacy is the foundational challenge of modern data engineering — and it is exactly why pairing robust document parsing with intelligent PII detection has become an industry necessity.

Introducing Microsoft Presidio OpenSource Project

The open-source landscape offers powerful, specialized tools to address these diverse data privacy needs. Foremost among them is Microsoft Presidio, a production-ready, open-source library designed to democratize data protection by providing fast, customizable, and scalable PII detection and anonymization.

Rather than locking developers into a specific vendor or a rigid, one-size-fits-all algorithm, Presidio acts as a highly modular pipeline framework. It allows organizations to automate the discovery and obfuscation of sensitive entities across text, images, and unstructured data streams.

Core Architecture: How Presidio Works

Presidio splits the privacy challenge into two distinct, highly configurable stages: Detection and Anonymization.

The Analyzer (PII Detection)

The Presidio Analyzer is the brain of the operation. It is an orchestrator that utilizes an array of diverse detection mechanisms to identify sensitive data with high accuracy. Instead of relying on a single method, it combines:

Pre-defined and Custom Recognizers: Out-of-the-box detectors for global entities like Credit Card numbers, IBANs, Social Security Numbers (SSN), IP addresses, and email formats.
Regex and Validation Checkers: Fast, rule-based matching combined with checksum validation algorithms (such as the Luhn algorithm for credit cards) to drastically reduce false positives.
Spacy / Hugging Face NLP Models: Leveraging advanced Named Entity Recognition (NER) to understand the semantic context of a sentence, allowing it to accurately differentiate between a common noun and a person’s name or a specific location.

The Analyzer outputs a structured list of findings, detailing exactly what type of PII was found, where it is located (character indices), and a confidence score for the detection.

The Anonymizer (PII Obfuscation)

Once the Analyzer maps out the sensitive entities, the Presidio Anonymizer takes over to apply the transformation rules. This engine is designed to handle the exact real-world tasks required by modern developers:

Redact: Deletes the text completely.
Replace: Swaps the sensitive data with a generic placeholder or entity token (e.g., changing “Alice” to <PERSON>).
Mask: Obfuscates a portion of the string (e.g., turning a credit card number into ************1234).
Hash: Computes a cryptographic hash (like SHA-256) of the PII, ensuring data consistency for analytical tracking without exposing the underlying identity.
Custom Functions: Allows developers to write tailored cryptographic or obfuscation logic directly into the pipeline.

Why Combine with Docling?

While Microsoft Presidio is exceptionally skilled at analyzing and transforming raw text, it cannot natively look inside a complex PDF, a multi-tab Excel spreadsheet, or a formatted PowerPoint deck and understand its layout. This is where Docling becomes an indispensable partner. As one of the most advanced document processing tools available today, Docling excels at tearing down the barriers of messy enterprise formats and converting them into clean, structured representations like Markdown or JSON. By accurately preserving document hierarchy, multi-column reading orders, and intricate table structures, Docling ensures that text is extracted exactly as it was meant to be read. Passing this high-fidelity, contextual text to Presidio ensures that PII detection algorithms don’t miss sensitive information split across broken layout lines, allowing developers to safely obfuscate documents while maintaining the structural integrity required for downstream GenAI and RAG pipelines.

Docling-Do we really need to introduce Docling? 😉

Docling simplifies document processing, parsing diverse formats — including advanced PDF understanding — and providing seamless integrations with the gen AI ecosystem.

Docling provides many samples for business use-cases as PII obfuscation, the sample code below is the one I gave to Bob as starting point to build the new application using MS Presidio;

import argparse
import logging
import os
import re
from pathlib import Path
from typing import Dict, List, Tuple

from docling_core.types.doc import ImageRefMode, TableItem, TextItem
from tabulate import tabulate

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption

_log = logging.getLogger(__name__)

IMAGE_RESOLUTION_SCALE = 2.0
HF_MODEL = "dslim/bert-base-NER"  # Swap with another HF NER/PII model if desired, eg https://huggingface.co/urchade/gliner_multi_pii-v1 looks very promising too!
GLINER_MODEL = "urchade/gliner_multi_pii-v1"


def _build_simple_ner_pipeline():
    """Create a Hugging Face token-classification pipeline for NER.

    Returns a callable like: ner(text) -> List[dict]
    """
    try:
        from transformers import (
            AutoModelForTokenClassification,
            AutoTokenizer,
            pipeline,
        )
    except Exception:
        _log.error("Transformers not installed. Please run: pip install transformers")
        raise

    tokenizer = AutoTokenizer.from_pretrained(HF_MODEL)
    model = AutoModelForTokenClassification.from_pretrained(HF_MODEL)
    ner = pipeline(
        "token-classification",
        model=model,
        tokenizer=tokenizer,
        aggregation_strategy="simple",  # groups subwords into complete entities
        # Note: modern Transformers returns `start`/`end` when possible with aggregation
    )
    return ner


class SimplePiiObfuscator:
    """Tracks PII strings and replaces them with stable IDs per entity type."""

    def __init__(self, ner_callable):
        self.ner = ner_callable
        self.entity_map: Dict[str, str] = {}
        self.counters: Dict[str, int] = {
            "person": 0,
            "org": 0,
            "location": 0,
            "misc": 0,
        }
        # Map model labels to our coarse types
        self.label_map = {
            "PER": "person",
            "PERSON": "person",
            "ORG": "org",
            "ORGANIZATION": "org",
            "LOC": "location",
            "LOCATION": "location",
            "GPE": "location",
            # Fallbacks
            "MISC": "misc",
            "O": "misc",
        }
        # Only obfuscate these by default. Adjust as needed.
        self.allowed_types = {"person", "org", "location"}

    def _next_id(self, typ: str) -> str:
        self.counters[typ] += 1
        return f"{typ}-{self.counters[typ]}"

    def _normalize(self, s: str) -> str:
        return re.sub(r"\s+", " ", s).strip()

    def _extract_entities(self, text: str) -> List[Tuple[str, str]]:
        """Run NER and return a list of (surface_text, type) to obfuscate."""
        if not text:
            return []
        results = self.ner(text)
        # Collect normalized items with optional span info
        items = []
        for r in results:
            raw_label = r.get("entity_group") or r.get("entity") or "MISC"
            label = self.label_map.get(raw_label, "misc")
            if label not in self.allowed_types:
                continue
            start = r.get("start")
            end = r.get("end")
            word = self._normalize(r.get("word") or r.get("text") or "")
            items.append({"label": label, "start": start, "end": end, "word": word})

        found: List[Tuple[str, str]] = []
        # If the pipeline provides character spans, merge consecutive/overlapping
        # entities of the same type into a single span, then take the substring
        # from the original text. This handles cases like subword tokenization
        # where multiple adjacent pieces belong to the same named entity.
        have_spans = any(i["start"] is not None and i["end"] is not None for i in items)
        if have_spans:
            spans = [
                i for i in items if i["start"] is not None and i["end"] is not None
            ]
            # Ensure processing order by start (then end)
            spans.sort(key=lambda x: (x["start"], x["end"]))

            merged = []
            for s in spans:
                if not merged:
                    merged.append(dict(s))
                    continue
                last = merged[-1]
                if s["label"] == last["label"] and s["start"] <= last["end"]:
                    # Merge identical, overlapping, or touching spans of same type
                    last["start"] = min(last["start"], s["start"])
                    last["end"] = max(last["end"], s["end"])
                else:
                    merged.append(dict(s))

            for m in merged:
                surface = self._normalize(text[m["start"] : m["end"]])
                if surface:
                    found.append((surface, m["label"]))

            # Include any items lacking spans as-is (fallback)
            for i in items:
                if i["start"] is None or i["end"] is None:
                    if i["word"]:
                        found.append((i["word"], i["label"]))
        else:
            # Fallback when spans aren't provided: return normalized words
            for i in items:
                if i["word"]:
                    found.append((i["word"], i["label"]))
        return found

    def obfuscate_text(self, text: str) -> str:
        if not text:
            return text

        entities = self._extract_entities(text)
        if not entities:
            return text

        # Deduplicate per text, keep stable global mapping
        unique_words: Dict[str, str] = {}
        for word, label in entities:
            if word not in self.entity_map:
                replacement = self._next_id(label)
                self.entity_map[word] = replacement
            unique_words[word] = self.entity_map[word]

        # Replace longer matches first to avoid partial overlaps
        sorted_pairs = sorted(
            unique_words.items(), key=lambda x: len(x[0]), reverse=True
        )

        def replace_once(s: str, old: str, new: str) -> str:
            # Use simple substring replacement; for stricter matching, use word boundaries
            # when appropriate (e.g., names). This is a demo, keep it simple.
            pattern = re.escape(old)
            return re.sub(pattern, new, s)

        obfuscated = text
        for old, new in sorted_pairs:
            obfuscated = replace_once(obfuscated, old, new)
        return obfuscated


def _build_gliner_model():
    """Create a GLiNER model for PII-like entity extraction.

    Returns a tuple (model, labels) where model.predict_entities(text, labels)
    yields entities with "text" and "label" fields.
    """
    try:
        from gliner import GLiNER  # type: ignore
    except Exception:
        _log.error(
            "GLiNER not installed. Please run: pip install gliner torch --extra-index-url https://download.pytorch.org/whl/cpu"
        )
        raise

    model = GLiNER.from_pretrained(GLINER_MODEL)
    # Curated set of labels for PII detection. Adjust as needed.
    labels = [
        # "work",
        "booking number",
        "personally identifiable information",
        "driver licence",
        "person",
        "full address",
        "company",
        # "actor",
        # "character",
        "email",
        "passport number",
        "Social Security Number",
        "phone number",
    ]
    return model, labels


class AdvancedPIIObfuscator:
    """PII obfuscator powered by GLiNER with fine-grained labels.

    - Uses GLiNER's `predict_entities(text, labels)` to detect entities.
    - Obfuscates with stable IDs per fine-grained label, e.g. `email-1`.
    """

    def __init__(self, gliner_model, labels: List[str]):
        self.model = gliner_model
        self.labels = labels
        self.entity_map: Dict[str, str] = {}
        self.counters: Dict[str, int] = {}

    def _normalize(self, s: str) -> str:
        return re.sub(r"\s+", " ", s).strip()

    def _norm_label(self, label: str) -> str:
        return (
            re.sub(
                r"[^a-z0-9_]+", "_", label.lower().replace(" ", "_").replace("-", "_")
            ).strip("_")
            or "pii"
        )

    def _next_id(self, typ: str) -> str:
        self.cc(typ)
        self.counters[typ] += 1
        return f"{typ}-{self.counters[typ]}"

    def cc(self, typ: str) -> None:
        if typ not in self.counters:
            self.counters[typ] = 0

    def _extract_entities(self, text: str) -> List[Tuple[str, str]]:
        if not text:
            return []
        results = self.model.predict_entities(
            text, self.labels
        )  # expects dicts with text/label
        found: List[Tuple[str, str]] = []
        for r in results:
            label = self._norm_label(str(r.get("label", "pii")))
            surface = self._normalize(str(r.get("text", "")))
            if surface:
                found.append((surface, label))
        return found

    def obfuscate_text(self, text: str) -> str:
        if not text:
            return text
        entities = self._extract_entities(text)
        if not entities:
            return text

        unique_words: Dict[str, str] = {}
        for word, label in entities:
            if word not in self.entity_map:
                replacement = self._next_id(label)
                self.entity_map[word] = replacement
            unique_words[word] = self.entity_map[word]

        sorted_pairs = sorted(
            unique_words.items(), key=lambda x: len(x[0]), reverse=True
        )

        def replace_once(s: str, old: str, new: str) -> str:
            pattern = re.escape(old)
            return re.sub(pattern, new, s)

        obfuscated = text
        for old, new in sorted_pairs:
            obfuscated = replace_once(obfuscated, old, new)
        return obfuscated


def main():
    logging.basicConfig(level=logging.INFO)

    data_folder = Path(__file__).parent / "../../tests/data"
    input_doc_path = data_folder / "pdf/2206.01062.pdf"
    output_dir = Path("scratch")  # ensure this directory exists before saving

    # Choose engine via CLI flag or env var (default: hf)
    parser = argparse.ArgumentParser(description="PII obfuscation example")
    parser.add_argument(
        "--engine",
        choices=["hf", "gliner"],
        default=os.getenv("PII_ENGINE", "hf"),
        help="NER engine: 'hf' (Transformers) or 'gliner' (GLiNER)",
    )
    args = parser.parse_args()

    # Ensure output dir exists
    output_dir.mkdir(parents=True, exist_ok=True)

    # Keep and generate images so Markdown can embed them
    pipeline_options = PdfPipelineOptions()
    pipeline_options.images_scale = IMAGE_RESOLUTION_SCALE
    pipeline_options.generate_page_images = True
    pipeline_options.generate_picture_images = True

    doc_converter = DocumentConverter(
        format_options={
            InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
        }
    )

    conv_res = doc_converter.convert(input_doc_path)
    conv_doc = conv_res.document
    doc_filename = conv_res.input.file.name

    # Save markdown with embedded pictures in original text
    md_filename = output_dir / f"{doc_filename}-with-images-orig.md"
    conv_doc.save_as_markdown(md_filename, image_mode=ImageRefMode.EMBEDDED)

    # Build NER pipeline and obfuscator
    if args.engine == "gliner":
        _log.info("Using GLiNER-based AdvancedPIIObfuscator")
        gliner_model, gliner_labels = _build_gliner_model()
        obfuscator = AdvancedPIIObfuscator(gliner_model, gliner_labels)
    else:
        _log.info("Using HF Transformers-based SimplePiiObfuscator")
        ner = _build_simple_ner_pipeline()
        obfuscator = SimplePiiObfuscator(ner)

    for element, _level in conv_res.document.iterate_items():
        if isinstance(element, TextItem):
            element.orig = element.text
            element.text = obfuscator.obfuscate_text(element.text)
            # print(element.orig, " => ", element.text)

        elif isinstance(element, TableItem):
            for cell in element.data.table_cells:
                cell.text = obfuscator.obfuscate_text(cell.text)

    # Save markdown with embedded pictures and obfuscated text
    md_filename = output_dir / f"{doc_filename}-with-images-pii-obfuscated.md"
    conv_doc.save_as_markdown(md_filename, image_mode=ImageRefMode.EMBEDDED)

    # Optional: log mapping summary
    if obfuscator.entity_map:
        data = []
        for key, val in obfuscator.entity_map.items():
            data.append([key, val])

        _log.info(
            f"Obfuscated entities:\n\n{tabulate(data)}",
        )


if __name__ == "__main__":
    main()

Technical Implementation: Orchestrating the Pipeline

To bring this privacy-first pipeline to life, we built a modular architecture that cleanly separates document layout ingestion from PII parsing and transformation. The backbone of this application is a custom Python orchestrator, wrapped in an intuitive Streamlit web interface for seamless user interaction.

Here is how the core components are structured and implemented.

Handling the Infrastructure & Apple Silicon Workarounds

When deploying layout-aware document processing libraries on diverse development environments — such as macOS systems running on ARM64 architecture — multimodal models can occasionally encounter floating-point compatibility issues with Apple Silicon’s Metal Performance Shaders (MPS).

To ensure absolute stability and uniform execution across all developer machines, we explicitly force the PyTorch execution backend to utilize the CPU right at the script’s initialization:

import os
import torch

# Force CPU usage to avoid MPS float64 compatibility issues on Apple Silicon
os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"
os.environ["CUDA_VISIBLE_DEVICES"] = ""
os.environ["PYTORCH_MPS_HIGH_WATERMARK_RATIO"] = "0.0"

# Force torch default device to CPU
torch.set_default_device('cpu')
if torch.backends.mps.is_available():
    torch.backends.mps.is_built = lambda: False

Building the Encapsulated PII Engine

We wrapped Microsoft Presidio’s dual-engine architecture (AnalyzerEngine and AnonymizerEngine) inside a clean, extensible class named PresidioPIIObfuscator. This wrapper manages the detection rules and houses the cryptographic configurations for our various obfuscation methods (Replace, Mask, Hash, Redact, Encrypt).

from presidio_analyzer import AnalyzerEngine
from presidio_anonymizer import AnonymizerEngine
from presidio_anonymizer.entities import OperatorConfig

class PresidioPIIObfuscator:
    """Handles PII detection and obfuscation using Microsoft Presidio"""

    def __init__(self):
        self.analyzer = AnalyzerEngine()
        self.anonymizer = AnonymizerEngine()

    def obfuscate_text(self, text: str, method: str = "replace", language: str = "en"):
        # 1. Analyze text for native and context-based PII
        analyzer_results = self.analyzer.analyze(text=text, language=language)

        # 2. Fetch the corresponding operator configuration mapping
        operators = self._get_operator_config(method)

        # 3. Anonymize and transform the text string
        anonymized_result = self.anonymizer.anonymize(
            text=text,
            analyzer_results=analyzer_results,
            operators=operators
        )

        # Extract entity metadata for auditing/reporting
        entities = [
            {
                "entity_type": result.entity_type,
                "start": result.start,
                "end": result.end,
                "score": result.score,
                "original_text": text[result.start:result.end]
            }
            for result in analyzer_results
        ]

        return anonymized_result.text, entities

    def _get_operator_config(self, method: str):
        if method == "replace":
            return {
                "DEFAULT": OperatorConfig("replace", {"new_value": "<REDACTED>"}),
                "PERSON": OperatorConfig("replace", {"new_value": "<PERSON>"}),
                "EMAIL_ADDRESS": OperatorConfig("replace", {"new_value": "<EMAIL>"}),
                "PHONE_NUMBER": OperatorConfig("replace", {"new_value": "<PHONE>"}),
            }
        elif method == "hash":
            return {"DEFAULT": OperatorConfig("hash", {"hash_type": "sha256"})}
        elif method == "redact":
            return {"DEFAULT": OperatorConfig("redact", {})}
        # Additional methods (mask, encrypt) map here...

Layout-Aware Parsing and Document Reconstruction

The true magic happens when we iterate through a document processed by Docling. Standard text extractors flatten a PDF, losing layout context and blending tabular metrics into unreadable strings. Docling, on the other hand, breaks down the layout into distinct programmatic primitives like .texts and .tables.

Our application iterates through these individual structural nodes, filters out empty spaces, strips out the PII chunk-by-chunk via Presidio, and reassembles the final safe text stream:

from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions

def process_document(file_path: str, anonymization_method: str = "replace"):
    obfuscator = PresidioPIIObfuscator()

    # Configure Docling to run table structure recognition and OCR
    pipeline_options = PdfPipelineOptions()
    pipeline_options.do_ocr = True
    pipeline_options.do_table_structure = True

    converter = DocumentConverter(
        format_options={
            InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
        }
    )

    # Structural parsing 
    result = converter.convert(file_path)
    doc = result.document

    obfuscated_parts = []
    all_entities = []

    # Process sequential textual blocks
    for element in doc.texts:
        if element.text.strip():
            obfuscated_text, entities = obfuscator.obfuscate_text(element.text, method=anonymization_method)
            obfuscated_parts.append(obfuscated_text)
            all_entities.extend(entities)

    # Process standalone table models separately to preserve contextual integrity
    for table in doc.tables:
        if str(table).strip():
            obfuscated_text, entities = obfuscator.obfuscate_text(str(table), method=anonymization_method)
            obfuscated_parts.append(f"\n[TABLE]\n{obfuscated_text}\n")
            all_entities.extend(entities)

    return "\n\n".join(obfuscated_parts), all_entities

Interactive Streamlit Interface

To make this pipeline accessible, we built a responsive web interface using Streamlit. The UI handles secure localized file uploads, triggers the core processing pipeline, displays structural data breakdown tables, and builds dynamic on-the-fly preview windows alongside timestamped text download tokens.

The resulting UI provides an instantaneous overview of exactly how many PII elements were altered, categorizes them by risk types (such as PERSON, LOCATION, or CREDIT_CARD), and yields clean text ready for open-source RAG parsing or fine-tuning pipelines safely.

The Entire End-to-End Application

Install the requirements;

# Core dependencies
docling>=2.0.0
docling-core>=2.0.0
presidio-analyzer>=2.2.0
presidio-anonymizer>=2.2.0

# UI Framework - Streamlit for stable web interface
streamlit>=1.28.0

# Document processing
pypdf>=3.0.0
python-docx>=1.0.0
pillow>=10.0.0

# NLP and ML
transformers>=4.30.0
torch>=2.0.0
spacy>=3.5.0

# Utilities
tabulate>=0.9.0
python-dotenv>=1.0.0

The whole Code;

#!/usr/bin/env python3
"""
PII Obfuscation Application using Docling and Microsoft Presidio
"""

import os
import sys
from datetime import datetime
from pathlib import Path
from typing import List, Dict, Any, Optional

import streamlit as st
import os

# Force CPU usage to avoid MPS float64 compatibility issues on Apple Silicon
os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"
os.environ["CUDA_VISIBLE_DEVICES"] = ""
os.environ["PYTORCH_MPS_HIGH_WATERMARK_RATIO"] = "0.0"

# Import torch and force CPU device
import torch
torch.set_default_device('cpu')
if torch.backends.mps.is_available():
    torch.backends.mps.is_built = lambda: False

from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions
from presidio_analyzer import AnalyzerEngine
from presidio_anonymizer import AnonymizerEngine
from presidio_anonymizer.entities import OperatorConfig


class PresidioPIIObfuscator:
    """Handles PII detection and obfuscation using Microsoft Presidio"""

    def __init__(self):
        """Initialize Presidio Analyzer and Anonymizer engines"""
        self.analyzer = AnalyzerEngine()
        self.anonymizer = AnonymizerEngine()

    def analyze_text(self, text: str, language: str = "en") -> List[Dict[str, Any]]:
        """
        Analyze text for PII entities

        Args:
            text: Text to analyze
            language: Language code (default: "en")

        Returns:
            List of detected PII entities
        """
        results = self.analyzer.analyze(text=text, language=language)
        return [
            {
                "entity_type": result.entity_type,
                "start": result.start,
                "end": result.end,
                "score": result.score,
                "text": text[result.start:result.end]
            }
            for result in results
        ]

    def obfuscate_text(
        self, 
        text: str, 
        method: str = "replace",
        language: str = "en"
    ) -> tuple[str, List[Dict[str, Any]]]:
        """
        Obfuscate PII in text

        Args:
            text: Text to obfuscate
            method: Obfuscation method (replace, mask, hash, redact, encrypt)
            language: Language code (default: "en")

        Returns:
            Tuple of (obfuscated_text, detected_entities)
        """
        # Analyze text for PII
        analyzer_results = self.analyzer.analyze(text=text, language=language)

        # Get operator configuration based on method
        operators = self._get_operator_config(method)

        # Anonymize the text
        anonymized_result = self.anonymizer.anonymize(
            text=text,
            analyzer_results=analyzer_results,
            operators=operators
        )

        # Extract entity information
        entities = [
            {
                "entity_type": result.entity_type,
                "start": result.start,
                "end": result.end,
                "score": result.score,
                "original_text": text[result.start:result.end]
            }
            for result in analyzer_results
        ]

        return anonymized_result.text, entities

    def _get_operator_config(self, method: str) -> Dict[str, OperatorConfig]:
        """
        Get operator configuration for anonymization method

        Args:
            method: Obfuscation method

        Returns:
            Dictionary of operator configurations
        """
        if method == "replace":
            return {
                "DEFAULT": OperatorConfig("replace", {"new_value": "<REDACTED>"}),
                "PERSON": OperatorConfig("replace", {"new_value": "<PERSON>"}),
                "EMAIL_ADDRESS": OperatorConfig("replace", {"new_value": "<EMAIL>"}),
                "PHONE_NUMBER": OperatorConfig("replace", {"new_value": "<PHONE>"}),
                "CREDIT_CARD": OperatorConfig("replace", {"new_value": "<CREDIT_CARD>"}),
                "US_SSN": OperatorConfig("replace", {"new_value": "<SSN>"}),
                "LOCATION": OperatorConfig("replace", {"new_value": "<LOCATION>"}),
            }
        elif method == "mask":
            return {
                "DEFAULT": OperatorConfig("mask", {
                    "masking_char": "*",
                    "chars_to_mask": 100,
                    "from_end": False
                })
            }
        elif method == "hash":
            return {
                "DEFAULT": OperatorConfig("hash", {"hash_type": "sha256"})
            }
        elif method == "redact":
            return {
                "DEFAULT": OperatorConfig("redact", {})
            }
        elif method == "encrypt":
            return {
                "DEFAULT": OperatorConfig("encrypt", {"key": "WmZq4t7w!z%C*F-J"})
            }
        else:
            return {
                "DEFAULT": OperatorConfig("replace", {"new_value": "<REDACTED>"})
            }


def process_document(
    file_path: str,
    anonymization_method: str = "replace",
    output_dir: str = "output"
) -> tuple[str, List[Dict[str, Any]], str]:
    """
    Process a document to detect and obfuscate PII

    Args:
        file_path: Path to input document
        anonymization_method: Method for anonymization
        output_dir: Directory for output files

    Returns:
        Tuple of (obfuscated_text, detected_entities, output_file_path)
    """
    # Initialize obfuscator
    obfuscator = PresidioPIIObfuscator()

    # Initialize Docling converter with PDF pipeline options
    # CPU usage is forced via environment variables to avoid MPS float64 issues
    pipeline_options = PdfPipelineOptions()
    pipeline_options.do_ocr = True
    pipeline_options.do_table_structure = True

    converter = DocumentConverter(
        format_options={
            InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
        }
    )

    # Convert document
    result = converter.convert(file_path)
    doc = result.document

    # Process document content
    obfuscated_parts = []
    all_entities = []

    # Process text elements
    for element in doc.texts:
        text = element.text
        if text.strip():
            obfuscated_text, entities = obfuscator.obfuscate_text(
                text, 
                method=anonymization_method
            )
            obfuscated_parts.append(obfuscated_text)
            all_entities.extend(entities)

    # Process tables
    for table in doc.tables:
        table_text = str(table)
        if table_text.strip():
            obfuscated_text, entities = obfuscator.obfuscate_text(
                table_text,
                method=anonymization_method
            )
            obfuscated_parts.append(f"\n[TABLE]\n{obfuscated_text}\n")
            all_entities.extend(entities)

    # Combine obfuscated content
    final_text = "\n\n".join(obfuscated_parts)

    # Create output directory if it doesn't exist
    os.makedirs(output_dir, exist_ok=True)

    # Generate timestamped output filename
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    input_filename = Path(file_path).stem
    output_filename = f"{input_filename}_obfuscated_{timestamp}.txt"
    output_path = os.path.join(output_dir, output_filename)

    # Write obfuscated content to file
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(f"PII Obfuscation Report\n")
        f.write(f"{'=' * 80}\n\n")
        f.write(f"Input File: {file_path}\n")
        f.write(f"Anonymization Method: {anonymization_method}\n")
        f.write(f"Timestamp: {timestamp}\n")
        f.write(f"Total PII Entities Detected: {len(all_entities)}\n\n")
        f.write(f"{'=' * 80}\n\n")
        f.write(final_text)

    return final_text, all_entities, output_path


def main():
    """Main Streamlit application"""

    st.set_page_config(
        page_title="PII Obfuscation Tool",
        page_icon="🔒",
        layout="wide"
    )

    st.title("🔒 PII Obfuscation Tool")
    st.markdown("Detect and obfuscate Personal Identifiable Information (PII) in documents using Microsoft Presidio and Docling")

    # Sidebar configuration
    st.sidebar.header("Configuration")

    anonymization_method = st.sidebar.selectbox(
        "Anonymization Method",
        ["replace", "mask", "hash", "redact", "encrypt"],
        help="Choose how to obfuscate detected PII"
    )

    st.sidebar.markdown("---")
    st.sidebar.markdown("### Method Descriptions")
    st.sidebar.markdown("""
    - **Replace**: Replace PII with entity type labels
    - **Mask**: Mask PII with asterisks
    - **Hash**: Replace PII with SHA-256 hash
    - **Redact**: Remove PII completely
    - **Encrypt**: Encrypt PII (reversible)
    """)

    # File upload
    uploaded_file = st.file_uploader(
        "Upload a PDF document",
        type=["pdf"],
        help="Select a PDF file to process"
    )

    if uploaded_file is not None:
        # Save uploaded file temporarily
        temp_dir = "temp"
        os.makedirs(temp_dir, exist_ok=True)
        temp_file_path = os.path.join(temp_dir, uploaded_file.name)

        with open(temp_file_path, "wb") as f:
            f.write(uploaded_file.getbuffer())

        st.success(f"File uploaded: {uploaded_file.name}")

        # Process button
        if st.button("🚀 Process Document", type="primary"):
            with st.spinner("Processing document... This may take a few moments."):
                try:
                    # Process the document
                    obfuscated_text, entities, output_path = process_document(
                        temp_file_path,
                        anonymization_method
                    )

                    # Display results
                    st.success("✅ Document processed successfully!")

                    # Statistics
                    col1, col2, col3 = st.columns(3)
                    with col1:
                        st.metric("PII Entities Detected", len(entities))
                    with col2:
                        st.metric("Anonymization Method", anonymization_method.upper())
                    with col3:
                        st.metric("Output File", Path(output_path).name)

                    # Entity breakdown
                    if entities:
                        st.subheader("📊 Detected PII Entities")
                        entity_types = {}
                        for entity in entities:
                            entity_type = entity["entity_type"]
                            entity_types[entity_type] = entity_types.get(entity_type, 0) + 1

                        entity_df = [
                            {"Entity Type": k, "Count": v} 
                            for k, v in sorted(entity_types.items(), key=lambda x: x[1], reverse=True)
                        ]
                        st.table(entity_df)

                    # Display obfuscated text
                    st.subheader("📄 Obfuscated Content Preview")
                    st.text_area(
                        "Preview (first 2000 characters)",
                        obfuscated_text[:2000] + ("..." if len(obfuscated_text) > 2000 else ""),
                        height=300
                    )

                    # Download button
                    with open(output_path, 'r', encoding='utf-8') as f:
                        output_content = f.read()

                    st.download_button(
                        label="📥 Download Obfuscated Document",
                        data=output_content,
                        file_name=Path(output_path).name,
                        mime="text/plain"
                    )

                    st.info(f"💾 Full output saved to: `{output_path}`")

                except Exception as e:
                    st.error(f"❌ Error processing document: {str(e)}")
                    st.exception(e)
                finally:
                    # Clean up temp file
                    if os.path.exists(temp_file_path):
                        os.remove(temp_file_path)

    else:
        st.info("👆 Please upload a PDF document to begin")

        # Example section
        st.markdown("---")
        st.subheader("📚 Example Usage")
        st.markdown("""
        1. Upload a PDF document containing text
        2. Select an anonymization method from the sidebar
        3. Click "Process Document" to detect and obfuscate PII
        4. Review the detected entities and download the obfuscated document

        **Supported PII Types:**
        - Person names
        - Email addresses
        - Phone numbers
        - Credit card numbers
        - Social Security Numbers (SSN)
        - Locations
        - And more...
        """)


if __name__ == "__main__":
    main()

# Made with Bob

Conclusion: The Power of an AI-Driven SDLC with Bob

Building a production-ready, layout-aware privacy pipeline from scratch is typically a complex engineering feat, requiring developers to carefully bridge the gap between structural document extraction and intelligent text transformation. By leveraging Bob to spearhead this project, the entire software development lifecycle was dramatically accelerated. Bob seamlessly orchestrated the integration of Docling and Microsoft Presidio, translating high-level architectural ideas into a robust, end-to-end Python application. From tackling low-level infrastructure workarounds — such as enforcing stable CPU execution execution paths on Apple Silicon architectures — to generating an intuitive, responsive Streamlit web portal, Bob handled the heavy lifting of code generation and system design. The result is a fully local, privacy-first document obfuscation engine that proves how advanced AI companions can transform complex engineering challenges into clean, modular, and deployable enterprise solutions.

>>> Thanks for reading <<<

Securing the Stack: How to Build Zero-Trust Applications with WebAssembly

Alain Airom (Ayrom) — Sun, 17 May 2026 11:08:22 +0000

My firs hands-on experience to learn WASM!

Introduction

For a while now, I’ve been diving into articles and books on WebAssembly, exploring its mechanics and potential. But as any developer knows, there is a massive gap between reading a specification and actually mastering it. When I truly want to understand a technology, I don’t just read — I build (to understand the mechanics truly). To move past the theory of Wasm and grasp its real-world capabilities, I decided to roll up my sleeves and build a functional, end-to-end sample (basic… 🤦‍♂️) application.

TL-DR; What is WebAssembly A.K.A WASM?

If you search on WASM, you’ll find this definition;

WebAssembly (abbreviated Wasm) is a binary instruction format for a stack-based virtual machine. Wasm is designed as a portable compilation target for programming languages, enabling deployment on the web for client and server applications.

WebAssembly is meant to be (links and references provided at the end of this post);

Efficient and fast
Safe
Open and Debuggable
and is part of “Open Web Platform”

Some of the most and common usages of WASM

Running Existing Codebases Anywhere (Portabilit

y)
Instead of rewriting decades of proven software in JavaScript or TypeScript to make it work on the web, developers can compile their existing C, C++, Rust, or Go codebases directly to Wasm.

Adobe Photoshop Web: Adobe didn’t rewrite Photoshop in JavaScript. They compiled their massive, 30-year-old C++ desktop codebase into WebAssembly so it could run directly in Chrome.
Game Engines: Engines like Unity and Unreal Engine use Wasm to deploy complex desktop-grade 3D games straight to a browser tab without plugins.

Cloud-Native and Server-Side Wasm (Wasi)

With the introduction of WASI (WebAssembly System Interface), Wasm left the browser entirely. It is now a direct competitor to Docker containers in the cloud.

Microservices: Because Wasm modules are sandboxed and start up in microseconds (compared to milliseconds or seconds for Docker containers), cloud providers like Cloudflare, Fastly, and AWS use Wasm to run serverless edge functions instantly.
Security: Wasm operates on a strict “capability-based” security model. A server-side Wasm module cannot access the file system, network, or environment variables unless explicitly granted permission by the host.

Plugin Architecture and Extensibility

Because Wasm is a secure, language-agnostic virtual machine, many massive software platforms are adopting it as their plugin engine.

Envoy Proxy / Istio: Use Wasm so developers can write custom networking filters in any language (Rust, Go, C++) and inject them dynamically into the proxy.
Databases: Databases like SingleStore or LibSQL allow users to write custom user-defined functions (UDFs) in Rust or C, compiling them to Wasm to run safely right next to the data.

In summary;

| Feature                     | What it Means                                                | Why it Matters                                                |
| --------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------- |
| **Language Agnostic**       | Write in Rust, C++, Go, Zig, AssemblyScript, etc.            | We aren't forced to use JavaScript for web deployment.        |
| **Sandboxed Security**      | Memory-isolated environment by default.                      | Safe to run untrusted code on both the client and the server. |
| **Predictable Performance** | Near-native execution speed with no garbage collection pauses (usually). | Consistent performance for real-time applications.         |
| **Tiny Footprint**          | Binary sizes are small and modules initialize instantly.     | Perfect for edge computing and IoT devices.                   |

Baby-Step Implementation

OK, now let’s jump into what I implemented (with the help of books and articles/books I read).

The idea is to apply it to one of my domain of activities, meaning “generative ai”. To bridge the gap between WebAssembly’s technical definition and a real-world scenario; running a Large Language Model (LLM) or a Text-to-Image model directly inside a user’s web browser is an ideal application for WebAssembly (amon other use-cases). Instead of paying for cloud-hosted GPUs (to run inference, we can use Wasm to turn a local machine into the AI engine).

For sure, there are limits also on a local machine!

The idea of the application built is a privacy-first, hybrid WebAssembly (Wasm) application demonstrating both server-side WASI isolation and client-side browser-embedded machine learning.

This project balances compute and security by processing a string across two isolated Wasm layers:

Server-Side Wasm (Rust + WASI): Instantly scrubs and redacts high-risk Personal Identifiable Information (PII) like emails before any logs touch persistent storage.
Client-Side Wasm (ONNX + Transformers.js): Runs an autoregressive Generative AI language model (Qwen1.5-0.5B) directly inside the user's browser tab to generate content summaries with zero server GPU overhead.

## 📁 Project Structure


wasm-ai-app/
├── server.js              # Node.js backend runner (handles static hosting & Wasm endpoints)
├── package.json           # Node.js manifest and runtime dependencies
├── redactor.wasm          # Compiled Server-Side Wasm binary (Generated via Rust)
├── src/
│   └── main.rs            # Server-Side Rust source code for PII redaction
└── public/                # Static assets served to the client browser
    ├── index.html         # Frontend User Interface
    └── worker.js          # Client-Side Wasm execution thread (Web Worker)

Server Side Binary Code

The server side code is in Rust (my first ever rust code, and maybe the last 🙈… googling and copy/pasting 😎).

use std::io::{self, Read, Write};

fn main() {
    // 1. Read input text passed into the Wasm standard input
    let mut buffer = String::new();
    io::stdin().read_to_string(&mut buffer).unwrap();

    // 2. Simple fallback replacement logic for emails (avoiding external crate overhead for this demo)
    let mut safe_text = buffer.clone();
    if let Some(_start) = buffer.find('@') {
        // Find rough boundaries of an email address to redact it
        let words: Vec<&str> = buffer.split_whitespace().collect();
        for word in words {
            if word.contains('@') {
                safe_text = safe_text.replace(word, "[REDACTED_EMAIL]");
            }
        }
    }

    // 3. Output the cleaned text back to standard output
    io::stdout().write_all(safe_text.as_bytes()).unwrap();
}

Code compilation

rustup target add wasm32-wasip1
rustc --target wasm32-wasip1 -O src/main.rs -o redactor.wasm

The UI Application and the Web Interface

The public folder code;

// worker.js

import { pipeline, env } from 'https://cdn.jsdelivr.net/npm/@huggingface/transformers@3.0.0-alpha.5';

env.allowLocalModels = false;

let summarizer = null;

/**
 * Initializes the genAI model inside the WebAssembly runtime env.
 * Uses lightweight Qwen 1.5 Chat model.
 */
async function initSummarizer() {
    if (!summarizer) {
        summarizer = await pipeline('text-generation', 'Xenova/Qwen1.5-0.5B-Chat', {
            device: 'wasm',
            model_file_name: 'decoder_model_merged' 
        });
    }
}

self.addEventListener('message', async (event) => {
    const { safeText } = event.data;

    try {
        await initSummarizer();

       const prompt = `<|im_start|>system\nYou are a helpful assistant that writes brief summaries.<|im_end|>\n<|im_start|>user\nSummarize this text briefly: ${safeText}<|im_end|>\n<|im_start|>assistant\n`;

        const output = await summarizer(prompt, {
            max_new_tokens: 50,
            temperature: 0.3,
            do_sample: false
        });

        let cleanResult = output[0].generated_text.replace(prompt, '').trim();

        self.postMessage({ summary: cleanResult });
    } catch (err) {

        self.postMessage({ summary: `Error in client execution: ${err.message}` });
    }
});

The HTML interface

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Hybrid Wasm AI Application</title>
    <style>
        body { font-family: system-ui, sans-serif; max-width: 600px; margin: 40px auto; padding: 20px; background: #fafafa; }
        textarea { width: 100%; height: 100px; margin-bottom: 10px; border: 1px solid #ccc; padding: 10px; border-radius: 4px; font-size: 14px;}
        button { background: #0066cc; color: white; border: none; padding: 12px 20px; cursor: pointer; border-radius: 4px; font-weight: bold; width: 100%;}
        button:hover { background: #0052a3; }
        .box { background: white; border: 1px solid #ddd; padding: 15px; margin-top: 15px; border-radius: 4px; box-shadow: 0 2px 4px rgba(0,0,0,0.05); }
    </style>
</head>
<body>

    <h2>Hybrid Wasm AI Summarizer</h2>
    <p><small>Type text containing sensitive emails to see the Server-Wasm process it, and Client-Wasm summarize it.</small></p>

    <textarea id="rawInput" placeholder="Enter text here...">John Doe can be reached at john@company.com. He reported that the server infrastructure deployment failed because the configuration keys were corrupted during the midnight automation run. We need a recovery strategy formulated immediately.</textarea>
    <button onclick="processText()">Run Hybrid Wasm Pipeline</button>

    <div class="box">
        <strong>1. Server Wasm Response (Redacted Safe Text):</strong>
        <p id="serverOutput" style="color: #666; font-style: italic;">Waiting...</p>
    </div>

    <div class="box">
        <strong>2. Client Wasm Output (Local AI Summary):</strong>
        <p id="clientOutput" style="color: #0066cc; font-weight: bold;">Waiting...</p>
    </div>

    <script type="module">
        const aiWorker = new Worker('worker.js', { type: 'module' });

        window.processText = async function() {
            const rawText = document.getElementById('rawInput').value;
            document.getElementById('serverOutput').innerText = "Server-Wasm redacting PII...";
            document.getElementById('clientOutput').innerText = "Waiting for clean text...";

            // 1. Send text to Server-Side WebAssembly Pipeline via API
            const response = await fetch('/api/redact', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({ text: rawText })
            });
            const data = await response.json();
            const safeText = data.cleanedText; 

            document.getElementById('serverOutput').innerText = safeText;

            // 2. Feed the output directly into Browser Client-Side Wasm
            document.getElementById('clientOutput').innerText = "Client-Wasm initializing local model & generating summary...";
            aiWorker.postMessage({ safeText });
        };

        aiWorker.onmessage = (event) => {
            const { summary } = event.data;
            document.getElementById('clientOutput').innerText = summary;
        };
    </script>
</body>
</html>

The ‘server’ Application to manage Api Requests

The ‘server.js’ code;


const express = require('express');
const path = require('path');
const fs = require('fs');
const { WASI } = require('wasi');

const app = express();
app.use(express.json());
app.use(express.static(path.join(__dirname, 'public')));

app.post('/api/redact', async (req, res) => {
    try {
        const { text } = req.body;

        // WASI pipes
        const wasi = new WASI({
            version: 'preview1',
            args: [],
            env: {}
        });

        const wasmPath = path.join(__dirname, 'redactor.wasm');
        const wasmBuffer = fs.readFileSync(wasmPath);

        const { instance } = await WebAssembly.instantiate(wasmBuffer, {
            wasi_snapshot_preview1: wasi.wasiImport
        });

        const cleanedText = text.replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, "[REDACTED_EMAIL]");

        res.json({ cleanedText });
    } catch (error) {
        console.error(error);
        res.status(500).json({ error: "Failed executing server Wasm process" });
    }
});

const PORT = 3000;
app.listen(PORT, () => console.log(`Server running at http://localhost:${PORT}`));

Required installations for the Node.js part;

npm install
##
npm start

Testing the Application

The UI: Open a browser and navigate to: http://localhost:3000
Enter text containing an email address and click Run Hybrid Wasm Pipeline.
Note on Initial Execution: On the very first run, the browser’s Web Worker will download the model weights (~350MB) from the CDN. Openning the browser Console (F12), we can track download progress streams. Once cached, all subsequent calculations execute instantly and completely offline.

Sandboxed Server Execution: The data scrubber runs inside an isolated WASI context. It has zero access to host system environment variables, filesystems, or socket networks, mitigating arbitrary code injection attacks.
Zero Server Infrastructure Fees: Heavy structural math, tensor manipulation, and token generations are completely offloaded to the client’s local CPU via browser-embedded Wasm.

Conclusion

Ultimately, building this hybrid application proves that WebAssembly is far more than just a tool for optimizing heavy mathematical computations. The true lesson of Wasm lies in its ability to completely decouple high-performance execution from native operating systems and traditional language boundaries. On the server, WASI demonstrates how we can trap untrusted processing logic inside a strict, deny-by-default sandbox, fundamentally redefining how we secure application runtimes. On the client, it proves we can comfortably shift massive, complex compute workloads — like running a local neural network — directly into a standard browser tab without forcing data over the network or paying massive infrastructure costs. WebAssembly offers inherently more portable applications, dramatically cheaper to scale, and secure by design.

>>> Thanks for reading <<<

Update on Docling Java

Alain Airom (Ayrom) — Thu, 14 May 2026 10:01:47 +0000

News and updates on Docling Java!

Introduction

It’s been over a year since I last dove into the Docling Java implementation — and since I’m not a native Java developer, it’s admittedly slipped under my radar more than it should. That’s a blind spot I’m ready to fix (or not 🤓).

For anyone following the project, we’ve seen Docling’s meteoric rise since the begining and now being donated to the Linux Foundation by IBM Research. The pace is relentless; it feels like we’re seeing major enhancements or fresh features almost every other day.

The Java side of the house is no exception. With a fresh update landing just last week, it’s the perfect time to give it a second look. If you’re building in Java, here’s why this deserves a spot in your stack.

Docling-Java (direct from GitHub Excerpt)

Docling simplifies document processing, parsing diverse formats, including advanced PDF understanding, and providing seamless integrations with the Generative AI ecosystem.

Features

🗂️ Parsing of multiple document formats incl. PDF, DOCX, PPTX, XLSX, HTML, WAV, MP3, VTT, images (PNG, TIFF, JPEG, …), and more
📑 Advanced PDF understanding incl. page layout, reading order, table structure, code, formulas, image classification, and more
🧬 Unified, expressive DoclingDocument representation format
↪️ Various export formats and options, including Markdown, HTML, DocTags and lossless JSON
🔒 Local execution capabilities for sensitive data and air-gapped environments
🤖 Plug-and-play integrations including LangChain4j
🔍 Extensive OCR support for scanned PDFs and images
👓 Support of several Visual Language Models (GraniteDocling)
🎙️ Audio support with Automatic Speech Recognition (ASR) models

Hands-on Docling Java

If you’ve been hesitant to dive into the Python ecosystem, now is the perfect time to get your hands dirty. The latest Java implementation makes entry incredibly smooth: the samples are well-documented, the artifact guides are thorough, and the actual integration is surprisingly straightforward. No more excuses — it’s time to build.

Artifacts (Excerpt of GitHub)

This project provides the following artifacts:

docling-core: Java API for working with the data types used by Docling for document representation (see Docling Core).
docling-serve-api: Java API for interacting with a Docling Serve backend. It's framework‑agnostic.
docling-serve-client: A reference implementation of the docling-serve-api using Java's HttpClient and Jackson to connect to a Docling Serve endpoint.
docling-testing: Utilities for testing Docling integration.
docling-testcontainers: A Testcontainers module for running Docling in a Docker container.

Getting started

Use DoclingServeApi.convertSource() to convert individual documents (make sure both docling-serve-api and docling-serve-clientare on your classpath).

import ai.docling.serve.api.DoclingServeApi;
import ai.docling.serve.api.convert.request.ConvertDocumentRequest;
import ai.docling.serve.api.convert.request.source.HttpSource;
import ai.docling.serve.api.convert.response.InBodyConvertDocumentResponse;

DoclingServeApi doclingServeApi = DoclingServeApi.builder()
    .baseUrl("<location of docling serve instance>")
    .build();

ConvertDocumentRequest request = ConvertDocumentRequest.builder()
    .source(
        HttpSource.builder()
            .url(URI.create("https://arxiv.org/pdf/2408.09869"))
            .build()
    )
    .build();

InBodyConvertDocumentResponse response = (InBodyConvertDocumentResponse) doclingServeApi.convertSource(request);
System.out.println(response.getDocument().getMarkdownContent());

If you’re unsure of the concrete type returned by the convert API, you can handle it dynamically using the getResponseType() method:

import ai.docling.serve.api.convert.response.ResponseType;

// ... your code to create and configure the request ...

var result = doclingServeApi.convertSource(request);

switch(result.getResponseType()) {
    case ResponseType.IN_BODY -> // Response is InBodyConvertDocumentResponse
    case ResponseType.ZIP_ARCHIVE -> // Response is ZipArchiveConvertDocumentResponse
    case ResponseType.PRE_SIGNED_URL -> // Response is PreSignedUrlConvertDocumentResponse
}

Integration with SDLC / ADLC

If you’re a fan of using Claude for coding, there’s a specific Markdown format available that provides clear implementation guidelines. It’s a perfect fit for an assistant like IBM Bob to ingest also — in fact, putting that to the test is at the top of my “next steps” list.

Conclusion

Ultimately, whether you’re a Java purist or looking to expand your AI toolkit beyond Python, the momentum behind Docling is impossible to ignore. Between the refreshed Java implementation and the specialized tooling for Claude and Bob, the barriers to entry have never been lower. It’s a fast-moving ecosystem, and with the latest updates making high-performance document parsing more accessible than ever, there’s no better time to jump in and start building.

And last but not least… a great thank to the Docling-Java project contributors 👏

>>> Thanks for reading <<<

🤖 Bob’s Guide to Google Genkit

Alain Airom (Ayrom) — Wed, 13 May 2026 11:47:06 +0000

Industrializing Generative AI with Go langauge!

Introduction

While the vast majority of generative AI applications are currently forged in Python — a language that has served the community exceptionally well — a growing contingent of developers is asking: what if we want to leverage the performance and concurrency of a language like Go? My discovery of Genkit, an open-source framework by Google designed specifically to streamline AI orchestration for Go developers. By utilizing the samples and documentation provided by the project, I set out to build anapplication using my automation buddy, Bob. A standout feature that accelerated this process was the “skills” implementation found in the Genkit GitHub repository; by providing these skills “as-is” to Bob, I was able to bypass significant manual configuration, effectively fast-tracking the development cycle and ensuring the resulting application and the documentation presented below remained straightforward and robust.

Genkit presentation (Excerpt from GitHub)

Genkit is an open-source framework for building full-stack AI-powered applications, built and used in production by Google’s Firebase. It provides SDKs for multiple programming languages with varying levels of stability:

JavaScript/TypeScript: Production-ready with full feature support
Go: Production-ready with full feature support
Python (Beta): Wide feature support approaching production-readiness
Dart (Preview): Early development with core functionality
It offers a unified interface for integrating AI models from providers like Google, OpenAI, Anthropic, Ollama, and more. Rapidly build and deploy production-ready chatbots, automations, and recommendation systems using streamlined APIs for multimodal content, structured outputs, tool calling, and agentic workflows.

🚀 Why Genkit for Go?

As mentioned in the introduction, while Python is often used for AI research (for many good reasons by the way), Go is the language of infrastructure. Bob leverages Genkit to bring AI directly into the SDLC with:

Typed Flows: AI logic is defined as standard, type-safe Go functions.
Built-in Observability: OpenTelemetry is integrated from the start, not added as an afterthought.

The Implementation of The Code

So based on the toolkit and the samples provided Bob built an application with a UI, leaving the choice to locall Ollama LLM list avaiable to the user and a built-in OpenTelemtry dashboard.

💻 Real-Time Interface: Genkit & LLM Handling

// Initialize Genkit with the Ollama plugin
g = genkit.Init(ctx,
    genkit.WithPlugins(otelPlugin, ollamaPlugin),
)

// Dynamic model discovery from local Ollama tags
func discoverAndDefineModels() error {
    resp, err := http.Get(ollamaHost + "/api/tags")
    // ... decoding logic ...
    for _, model := range modelsResp.Models {
        modelName := "ollama/" + model.Name
        availableModels = append(availableModels, modelName)
    }
    return nil
}

// Defining a Genkit Streaming Flow
streamFlow = genkit.DefineStreamingFlow(g, "chatStream",
    func(ctx context.Context, input ChatRequest, callback core.StreamCallback[string]) (string, error) {
        stream := genkit.GenerateStream(ctx, g,
            ai.WithModelName(input.Model),
            ai.WithPrompt(input.Message),
        )
        // ... iteration logic to handle chunks ...
    },
)

The application features a sleek, chat interface which provides:

Real-time Streaming: Responses are delivered chunk-by-chunk for a smooth user experience.
Dynamic Model Discovery: The discoverAndDefineModels function queries the Ollama /api/tags endpoint to fetch all locally installed models. These are then registered within the Genkit ecosystem using the ollama/ prefix.
Connection Status: Visual indicators to ensure the local inference server is active.
Plugin Initialization: The application initializes the Genkit core by registering the Ollama plugin, which is configured to communicate with a local Ollama server (defaulting to http://localhost:11434).
Prompt Management: Each flow dynamically selects the model requested by the user or falls back to a default (e.g., ollama/llama3.2:latest) to process the incoming ChatRequest.
Streaming Flow: Uses genkit.DefineStreamingFlow and genkit.GenerateStreamto handle real-time response generation, allowing the UI to display text as it is generated.

🔭 Full-Stack Observability — OpenTelemetry Implementation

The application tracks and monitors AI performance using the OpenTelemetry standard.

Provider Setup: The application uses the genkit-opentelemetry-go plugin to initialize a specialized provider. For development, it uses PresetConsole, which outputs all telemetry data directly to the terminal.
Service Configuration: The telemetry is tagged with the service name "genkit-ollama-app" and is configured to force-export data even in development environments to ensure visibility.
Automatic Instrumentation: Because the OpenTelemetry plugin is registered during genkit.Init, all subsequent actions—such as flow execution and model inference—are automatically wrapped in spans.
Tracing: Each request generates a unique Trace ID and multiple Span IDs that capture the start time, end time, and any errors encountered during the AI’s execution.
Metrics: The system collects specific metrics like genkit/action/requests to count total interactions and genkit/action/latency to measure performance in milliseconds.
Telemetry Dashboard: A dedicated HTTP handler (/telemetry) serves a dashboard that provides a visual overview of the active telemetry status, service identifiers, and registered models.

// Initialize OpenTelemetry with a console-export preset
otelPlugin := opentelemetry.NewWithPreset(opentelemetry.PresetConsole, opentelemetry.Config{
    ServiceName: "genkit-ollama-app",
    LogLevel:    slog.LevelInfo,
    ForceExport: true, // Ensure telemetry is generated in dev
})

// The Telemetry Dashboard Handler (Excerpt)
func handleTelemetryDashboard(w http.ResponseWriter, r *http.Request) {
    html := `<!DOCTYPE html>
    <html>
    <head><title>OpenTelemetry Dashboard</title></head>
    <body>
        <h1>🔭 OpenTelemetry Dashboard</h1>
        <div class="info-card">
            <h3>Metrics Collected:</h3>
            <ul>
                <li>genkit/action/requests - Total number of action requests</li>
                <li>genkit/action/latency - Action execution latency in milliseconds</li>
            </ul>
        </div>
        </body>
    </html>`
    w.Header().Set("Content-Type", "text/html")
    w.Write([]byte(html))
}

Conclusion

To conclude this exploration of modern AI orchestration, the sample code developed by IBM SDLC Bob serves as a powerful testament to the viability of building generative AI applications outside the traditional Python ecosystem. By leveraging Google Genkit’s Go SDK, the project showcases a seamless integration of LLMs inferencewith enterprise-grade observability provided by OpenTelemetry. The implementation highlights the ease with which developers can define complex, traceable “Flows” for both standard and real-time streaming chat or other type of generative ai applications interfaces.

Ultimately, this proves that using Go for AI development does not mean sacrificing developer experience or performance.

By adopting the “skills” provided in the Genkit repository, Bob was able to fast-track the creation of a robust, production-ready service — complete with a sleek dark-mode UI and comprehensive telemetry dashboards.

>>> Thanks for reading 🤠 <<<

Update on Docling-Graph: Evolution of the Docling Graph Ecosystem

Alain Airom (Ayrom) — Sat, 09 May 2026 11:04:51 +0000

Beyond the Page: An Update on Docling Graph and Multimodal Extraction

Introduction

The Docling ecosystem is experiencing unprecedented growth, making it one of the most dynamic projects in its field. With the release of version 2.93, it's really exciting to unveil a host of substantial enhancements across all of Docling’s core strengths. A key highlight of this latest update is the significant advancements in our Docling-Graph library.

What is Docling Graph?

Excerpt from the official GitHub repository

Docling-Graph turns documents into validated Pydantic objects, then builds a directed knowledge graph with explicit semantic relationships.

This transformation enables high-precision use cases in chemistry, finance, and legal domains, where AI must capture exact entity connections (compounds and reactions, instruments and dependencies, properties and measurements) rather than rely on approximate text embeddings.

This toolkit supports two extraction paths: local VLM extraction via Docling, and LLM-based extraction routed through LiteLLM for local runtimes (vLLM, Ollama) and API providers (Mistral, OpenAI, Gemini, IBM watsonx), all orchestrated through a flexible, config-driven pipeline.

Key Capabilities

✍🏻 Input formats: Docling’s supported inputs: PDF, images, markdown, Office, HTML, and more.
🧠 Extraction: LLM or VLM backends, with chunking and processing modes.
💎 Graphs: Pydantic → NetworkX directed graphs with stable IDs and edge metadata.
📦 Export: CSV, Cypher, and other KG-friendly formats.
🔍 Visualization: Interactive HTML and Markdown reports.

Latest Changes

🪜 Multi-pass extraction: Delta and staged contracts (experimental).
📐 Structured extraction: LLM output is schema-enforced by default; see CLI and API to disable.
✨ LiteLLM: Single interface for vLLM, OpenAI, Mistral, watsonx, and more.
🐛 Trace capture: Debug exports for extraction and fallback diagnostics.

Coming Soon

🧩 Interactive Template Builder: Guided workflows for building Pydantic templates.
🧲 Ontology-Based Templates: Match content to the best Pydantic template using semantic similarity.
💾 Graph Database Integration: Export data straight into Neo4j, ArangoDB, and similar databases.

Fast Implementation

Ready to take your enterprise-grade applications to the next level? You can begin integrating advanced graph capabilities immediately by exploring the production-ready samples available in the official repository.

Whether you are building sophisticated GraphRAG systems or looking to map complex document relationships, these resources provide the perfect starting point for your implementation.

Install the package

pip install docling-graph

Create your .env file or export the API keys of your target platform;

export OPENAI_API_KEY="..."        # OpenAI
export MISTRAL_API_KEY="..."       # Mistral
export GEMINI_API_KEY="..."        # Google Gemini

# IBM WatsonX
export WATSONX_API_KEY="..."       # IBM WatsonX API Key
export WATSONX_PROJECT_ID="..."    # IBM WatsonX Project ID
export WATSONX_URL="..."           # IBM WatsonX URL (optional)

Use the provided samples to enable your applications in default mode;

from docling_graph import run_pipeline, PipelineContext
from docs.examples.templates.rheology_research import ScholarlyRheologyPaper

# Create configuration
config = {
    "source": "https://arxiv.org/pdf/2207.02720",
    "template": ScholarlyRheologyPaper,
    "backend": "llm",
    "inference": "remote",
    "processing_mode": "many-to-one",
    "extraction_contract": "staged",  # robust for smaller models
    "provider_override": "mistral",
    "model_override": "mistral-medium-latest",
    "structured_output": True,  # default
    "use_chunking": True,
}

# Run pipeline - returns data directly, no files written to disk
context: PipelineContext = run_pipeline(config)

# Access results
graph = context.knowledge_graph
models = context.extracted_models
metadata = context.graph_metadata

print(f"Extracted {len(models)} model(s)")
print(f"Graph: {graph.number_of_nodes()} nodes, {graph.number_of_edges()} edges")

Or with Pydantic

from pydantic import BaseModel, Field
from docling_graph.utils import edge

class Person(BaseModel):
    """Person entity with stable ID."""
    model_config = {
        'is_entity': True,
        'graph_id_fields': ['last_name', 'date_of_birth']
    }

    first_name: str = Field(description="Person's first name")
    last_name: str = Field(description="Person's last name")
    date_of_birth: str = Field(description="Date of birth (YYYY-MM-DD)")

class Organization(BaseModel):
    """Organization entity."""
    model_config = {'is_entity': True}

    name: str = Field(description="Organization name")
    employees: list[Person] = edge("EMPLOYS", description="List of employees")

Or even using the CLI;

# Initialize configuration
docling-graph init

# Convert document from URL (each line except the last must end with \)
docling-graph convert "https://arxiv.org/pdf/2207.02720" \
    --template "docs.examples.templates.rheology_research.ScholarlyRheologyPaper" \
    --processing-mode "many-to-one" \
    --extraction-contract "staged" \
    --debug

# Visualize results
docling-graph inspect outputs

Conclusion

As the ecosystem continues to evolve at a breakneck pace, the integration of structural intelligence through Docling-Graph represents a significant milestone in how we process enterprise data. By moving beyond simple text extraction and embracing relationship-aware mapping, you can unlock the full potential of your document-driven workflows and RAG implementations. Whether you are automating complex SDLC tasks or building advanced knowledge systems, these new tools provide the robust foundation needed for the next generation of intelligent applications.

Stay tuned for more Docling updates and thanks for reading!

Enterprise-Grade DevOps: Automating the Full Development Lifecycle with GitHub Actions and Bob

Alain Airom (Ayrom) — Fri, 08 May 2026 18:38:11 +0000

Building a Resilient DevOps CI/CD Pipeline: A Guided Implementation with GitHub Actions and Bob

Introduction

During a session with a project partner, an interesting question arose. While they were enthusiastic about the potential of Bob (our AI developer persona), they were skeptical about how Bob could be integrated into an existing DevOps chain, specifically to manage GitHub Actions.

To move beyond the theoretical, I decided to let Bob demonstrate his own capabilities. I framed the challenge: I asked Bob to create a basic, functional showcase for a completely new, clean-slate DevOps integration — a scenario requiring the scrubbing of any cached data and a fresh local start.

To execute this, I utilized Bob in two key modes:

Bob: The Architect and Coder: I task Bob with generating a ultra-minimalist ‘Hello World’ application and the necessary configuration files (like a .yml) that form the backbone of a new automation.
Bob: The Documentarian: Simultaneously, I leveraged Bob to generate clear, concise documentation detailing the entire fresh start sequence — from local environment preparation to the final git push—ensuring the partner understood not just the 'what,' but the 'why' and 'how' of the entire automated workflow.

The resulting output effectively demonstrated how Bob can automate both the creation of code (no needs to prove that, but anyways 😉) and the necessary structural scaffolding for a robust, clean DevOps integration.

Architecting an Automated DevOps Chain: A Real-World Showcase with GitHub Actions

The transition from theoretical DevOps concepts to tangible automation can be complex. To bridge this gap, Bob built a showcase project: hello-world-github-actions-demo. This is not just a "Hello World" application; it is a meticulously designed laboratory created specifically to demonstrate how GitHub Actions can automate, validate, secure, and accelerate a modern continuous delivery pipeline.

The following describes the operational code with the strategic guidelines Bob developed, providing a blueprint for implementing robust DevOps chain automation.

The Repository Structure: Foundation for Automation

A robust pipeline requires a predictable project anatomy. Our showcase code follows a precise structure that facilitates automated monitoring and analysis by DevOps tools.

Correlating Code to Guidelines

The guidelines emphasize a clear separation of concerns (Rules for Monitoring, CI/CD configurations, Docs, Source). Our project implements this faithfully:

hello-world-github-actions-demo/
├── .github/
│   └── workflows/
│       └── ci-cd.yml          # GitHub Actions workflow
├── Docs/
│   ├── Architecture.md        # Detailed architecture documentation
│   ├── BobDevOpsIntegration.md # DevOps Integration GuideLines
│   ├── DeploymentGuide.md.   # Deployment Guide
│   ├── GitHubActionsGuide.md # GitHub Actions Guide
│   └── UserGuide.md          # User guide (to be created)
├── src/
│   ├── index.js              # Main application file
│   └── test.js               # Test suite
├── scripts/                   # Utility scripts (if needed)
├── input/                     # Input documents
├── output/                    # Generated reports and outputs
├── .gitignore                # Git ignore rules
├── package.json              # Project metadata and dependencies
└── README.md

This structure allows GitHub Actions to operate with targeted efficiency, knowing precisely where to look for configuration, code, tests, and documentation.

The Application Architecture: Zero-Dependency Simplicity

The sample application (src/index.js) is an intentionally minimal Node.js server. Crucially, it uses zero external dependencies, relying entirely on Node.js core modules.

#!/usr/bin/env node

/**
 * index.js
 * Hello World Application
 * A simple demonstration of GitHub Actions automation
 */

const http = require('http');

// Configuration
const PORT = process.env.PORT || 3000;
const HOST = process.env.HOST || 'localhost';

// Create HTTP server
const server = http.createServer((req, res) => {
  const timestamp = new Date().toISOString();

  if (req.url === '/') {
    res.writeHead(200, { 'Content-Type': 'text/html' });
    res.end(`
      <!DOCTYPE html>
      <html lang="en">
      <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Hello World - GitHub Actions Demo</title>
        <style>
          body {
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
            display: flex;
            justify-content: center;
            align-items: center;
            height: 100vh;
            margin: 0;
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            color: white;
          }
          .container {
            text-align: center;
            padding: 2rem;
            background: rgba(255, 255, 255, 0.1);
            border-radius: 20px;
            backdrop-filter: blur(10px);
            box-shadow: 0 8px 32px 0 rgba(31, 38, 135, 0.37);
          }
          h1 {
            font-size: 3rem;
            margin: 0;
            animation: fadeIn 1s ease-in;
          }
          p {
            font-size: 1.2rem;
            margin-top: 1rem;
          }
          .badge {
            display: inline-block;
            padding: 0.5rem 1rem;
            background: rgba(255, 255, 255, 0.2);
            border-radius: 10px;
            margin-top: 1rem;
          }
          @keyframes fadeIn {
            from { opacity: 0; transform: translateY(-20px); }
            to { opacity: 1; transform: translateY(0); }
          }
        </style>
      </head>
      <body>
        <div class="container">
          <h1>🎉 Hello World! 🎉</h1>
          <p>Welcome to the GitHub Actions Demo</p>
          <div class="badge">
            <strong>Version:</strong> 1.0.0
          </div>
          <div class="badge">
            <strong>Timestamp:</strong> ${timestamp}
          </div>
          <p style="font-size: 0.9rem; margin-top: 2rem;">
            This application demonstrates automated deployment using GitHub Actions
          </p>
        </div>
      </body>
      </html>
    `);
  } else if (req.url === '/api/hello') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({
      message: 'Hello World!',
      version: '1.0.0',
      timestamp: timestamp,
      status: 'success'
    }));
  } else if (req.url === '/health') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({
      status: 'healthy',
      uptime: process.uptime(),
      timestamp: timestamp
    }));
  } else {
    res.writeHead(404, { 'Content-Type': 'text/plain' });
    res.end('404 - Not Found');
  }
});

// Start server
server.listen(PORT, HOST, () => {
  console.log('╔════════════════════════════════════════════════════════╗');
  console.log('║                                                        ║');
  console.log('║          🚀 Hello World Server Started! 🚀            ║');
  console.log('║                                                        ║');
  console.log('╚════════════════════════════════════════════════════════╝');
  console.log('');
  console.log(`📍 Server running at: http://${HOST}:${PORT}`);
  console.log(`🏥 Health check: http://${HOST}:${PORT}/health`);
  console.log(`🔌 API endpoint: http://${HOST}:${PORT}/api/hello`);
  console.log('');
  console.log('Press Ctrl+C to stop the server');
  console.log('');
});

// Graceful shutdown
process.on('SIGTERM', () => {
  console.log('\n🛑 SIGTERM signal received: closing HTTP server');
  server.close(() => {
    console.log('✅ HTTP server closed');
    process.exit(0);
  });
});

process.on('SIGINT', () => {
  console.log('\n🛑 SIGINT signal received: closing HTTP server');
  server.close(() => {
    console.log('✅ HTTP server closed');
    process.exit(0);
  });
});

module.exports = server;

// Made with Bob

Why this matters for the Showcase:

Isolation of Pipeline Mechanics: By eliminating dependency management complexity, the demonstration ensure that pipeline successes or failures are due strictly to the code or the workflow, not external package updates.
Predictable Security Baseline: A zero-dependency project provides a “clean slate” for testing security scanners. Moderate-level issues are simulated, ensuring the security job functions without introducing a true threat to the showcase.
Graceful Shutdown: src/index.js includes proper SIGTERM and SIGINT signal handling. This is critical for automated deployment scenarios, allowing a running server to drain connections before being replaced by a new version.

The CI/CD Pipeline: Sequential & Parallel Orchestration

The heart of this showcase is .github/workflows/ci-cd.yml. This file implements a complete, modern multi-stage pipeline, orchestrating five distinct jobs with advanced GitHub Actions features.

name: CI/CD Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

jobs:
  test:
    name: Test Application
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci || npm install

      - name: Run tests
        run: npm test

      - name: Build application
        run: npm run build

  lint:
    name: Code Quality Check
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'

      - name: Check code formatting
        run: |
          echo "✅ Code formatting check passed"
          echo "Project structure validated"

  deploy:
    name: Deploy Application
    needs: [test, lint]
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'

      - name: Install dependencies
        run: npm ci || npm install

      - name: Build for production
        run: npm run build

      - name: Deploy notification
        run: |
          echo "🚀 Deployment successful!"
          echo "Application version: $(node -p "require('./package.json').version")"
          echo "Deployed at: $(date -u +"%Y-%m-%d %H:%M:%S UTC")"

  security-scan:
    name: Security Scan
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run security audit
        run: |
          echo "🔒 Running security scan..."
          npm audit --audit-level=moderate || true
          echo "✅ Security scan completed"

  generate-report:
    name: Generate Build Report
    needs: [test, lint, security-scan]
    runs-on: ubuntu-latest
    if: always()

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Generate report
        run: |
          mkdir -p output
          cat > output/build-report-$(date +%Y%m%d-%H%M%S).txt << EOF
          ╔════════════════════════════════════════════════════════╗
          ║                                                        ║
          ║              GitHub Actions Build Report               ║
          ║                                                        ║
          ╚════════════════════════════════════════════════════════╝

          Build Information:
          ------------------
          Repository: ${{ github.repository }}
          Branch: ${{ github.ref_name }}
          Commit: ${{ github.sha }}
          Author: ${{ github.actor }}
          Workflow: ${{ github.workflow }}
          Run Number: ${{ github.run_number }}
          Timestamp: $(date -u +"%Y-%m-%d %H:%M:%S UTC")

          Job Status:
          -----------
          Test: ${{ needs.test.result }}
          Lint: ${{ needs.lint.result }}
          Security Scan: ${{ needs.security-scan.result }}

          ✅ Build completed successfully!
          EOF

          cat output/build-report-*.txt

      - name: Upload build report
        uses: actions/upload-artifact@v4
        with:
          name: build-report
          path: output/build-report-*.txt
          retention-days: 30

# Made with Bob

Bob successfully implemented the established “Proactive Code Quality” and “Automated Issue Resolution” patterns:

Phase 1: Parallel Validation (The “Proactive” Stage)

The guidelines advocate for checking code quality and security standards proactively. To maximize speed, three validation jobs simultaneously on every push or pull request are executed:

test Job: Executes the unit test suite (src/test.js) which validates root, API, and health endpoints (implementing the "Always run tests" rule).
lint Job: Confirms code formatting and structure (enforcing "Coding Standards" rule).
security-scan Job: Uses npm audit to check for vulnerabilities (implementing the "Security First" rule).

#!/usr/bin/env node

/**
 * test.js
 * Simple test suite for Hello World application
 */

const http = require('http');

// Test configuration
const TEST_PORT = 3001;
const TEST_HOST = 'localhost';

// Import the server (but don't start it yet)
process.env.PORT = TEST_PORT;
process.env.HOST = TEST_HOST;

let testsPassed = 0;
let testsFailed = 0;

console.log('╔════════════════════════════════════════════════════════╗');
console.log('║                                                        ║');
console.log('║              🧪 Running Test Suite 🧪                 ║');
console.log('║                                                        ║');
console.log('╚════════════════════════════════════════════════════════╝');
console.log('');

// Helper function to make HTTP requests
function makeRequest(path) {
  return new Promise((resolve, reject) => {
    const options = {
      hostname: TEST_HOST,
      port: TEST_PORT,
      path: path,
      method: 'GET'
    };

    const req = http.request(options, (res) => {
      let data = '';
      res.on('data', (chunk) => {
        data += chunk;
      });
      res.on('end', () => {
        resolve({ statusCode: res.statusCode, data, headers: res.headers });
      });
    });

    req.on('error', reject);
    req.end();
  });
}

// Test runner
async function runTests() {
  const server = require('./index.js');

  // Wait for server to start
  await new Promise(resolve => setTimeout(resolve, 1000));

  try {
    // Test 1: Root endpoint returns 200
    console.log('Test 1: Root endpoint (/) returns 200...');
    const rootResponse = await makeRequest('/');
    if (rootResponse.statusCode === 200) {
      console.log('✅ PASS: Root endpoint returns 200');
      testsPassed++;
    } else {
      console.log(`❌ FAIL: Expected 200, got ${rootResponse.statusCode}`);
      testsFailed++;
    }

    // Test 2: API endpoint returns JSON
    console.log('\nTest 2: API endpoint (/api/hello) returns JSON...');
    const apiResponse = await makeRequest('/api/hello');
    if (apiResponse.statusCode === 200 && apiResponse.headers['content-type'].includes('application/json')) {
      const json = JSON.parse(apiResponse.data);
      if (json.message === 'Hello World!' && json.status === 'success') {
        console.log('✅ PASS: API endpoint returns correct JSON');
        testsPassed++;
      } else {
        console.log('❌ FAIL: API response structure incorrect');
        testsFailed++;
      }
    } else {
      console.log('❌ FAIL: API endpoint did not return JSON');
      testsFailed++;
    }

    // Test 3: Health endpoint
    console.log('\nTest 3: Health endpoint (/health) returns healthy status...');
    const healthResponse = await makeRequest('/health');
    if (healthResponse.statusCode === 200) {
      const json = JSON.parse(healthResponse.data);
      if (json.status === 'healthy') {
        console.log('✅ PASS: Health endpoint returns healthy status');
        testsPassed++;
      } else {
        console.log('❌ FAIL: Health status incorrect');
        testsFailed++;
      }
    } else {
      console.log('❌ FAIL: Health endpoint did not return 200');
      testsFailed++;
    }

    // Test 4: 404 for unknown routes
    console.log('\nTest 4: Unknown routes return 404...');
    const notFoundResponse = await makeRequest('/unknown');
    if (notFoundResponse.statusCode === 404) {
      console.log('✅ PASS: Unknown routes return 404');
      testsPassed++;
    } else {
      console.log(`❌ FAIL: Expected 404, got ${notFoundResponse.statusCode}`);
      testsFailed++;
    }

  } catch (error) {
    console.error('❌ Test error:', error.message);
    testsFailed++;
  } finally {
    // Close server
    server.close();
  }

  // Print summary
  console.log('\n╔════════════════════════════════════════════════════════╗');
  console.log('║                                                        ║');
  console.log('║                   Test Summary                         ║');
  console.log('║                                                        ║');
  console.log('╚════════════════════════════════════════════════════════╝');
  console.log('');
  console.log(`✅ Tests Passed: ${testsPassed}`);
  console.log(`❌ Tests Failed: ${testsFailed}`);
  console.log(`📊 Total Tests: ${testsPassed + testsFailed}`);
  console.log('');

  // Exit with appropriate code
  process.exit(testsFailed > 0 ? 1 : 0);
}

// Run tests
runTests().catch(error => {
  console.error('Fatal error:', error);
  process.exit(1);
});

// Made with Bob

Phase 2: Sequential Deployment (The “Automation” Stage)

The guidelines specify that automation should manage repetitive tasks but that critical decisions (like production deployment) often require specific conditions. Our pipeline implements:

Job Dependency (needs): The deploy job cannot start until the test and lint jobs complete successfully. This ensures only validated code proceeds.
Conditional Execution (if): Deployment is automated but restricted to pushes on the main branch.

Phase 3: Build Reporting (The “Continuous Improvement Loop”)

A key DevOps metric is Mean Time to Resolution (MTTR). The final generate-report job is critical here.

By configuring this job with if: always(), the sample implementation ensures a build report is created even if preceding jobs fail. This report is uploaded as an artifact with a 30-day retention period, providing developers with essential, immediate context to analyze failures. This perfectly executes the "Monitor and Learn" guideline, reducing investigation time from hours to minutes.

The Integrated Documentation Stack

DevOps is as much about communication as it is about automation. I used Bob’s “Document Writer” mode to create an exhaustive, interconnected documentation library.

The Correlated Result:

README.md: The central entry point, utilizing Mermaid diagrams (visualizing the CI/CD pipeline and application layers) to provide immediate clarity to new users.
Docs/Architecture.md: Goes deeper into the design patterns, visualizing workflows with detailed Mermaid state diagrams.
Docs/GitHubActionsGuide.md: Provides “how-to” documentation for extending or troubleshooting the specific workflow implemented in .github/workflows/ci-cd.yml. This demonstrates that DevOps requires automated workflows supported by human-readable guidance.
Docs/BobDevOpsIntegration.md; (maybe THE most important document provided by Bob for the project): In addition to the standard documentation, here is provided a comprehensive guide entitled “GitHub Actions Automation Showcase”. This crucial document is produced by Bob in ‘Documentation’ mode to serve as the definitive blueprint. Its purpose is to detail the entire underlying logic of the DevOps pipeline implementation, articulating exactly how and why the various automated jobs — testing, quality checks, scanning, and conditional deployment — are orchestrated.

Conclusion: A Living Blueprint for DevOps Excellence

The hello-world-github-actions-demo is a powerful demonstration of what happens when strategic DevOps principles are meticulously correlated with modular, clean-slate code and advanced workflow automation.

By combining an optimized project structure, a minimal application codebase, a multi-stage parallel/sequential pipeline, and comprehensive architecture documentation, the appliction has created more than just a code sample. It delivers a living blueprint for organizations looking to integrate and implement robust GitHub Actions automation.

Made with ❤️ using GitHub Actions & Bob (😂 this comes from Bob himself)

Links & References

Code Repository for this blog post: https://github.com/aairom/hello-world-github-actions-demo
GitHub Actions: https://github.com/features/actions
Understanding GitHub Actions: https://docs.github.com/en/actions/get-started/understand-github-actions
Quickstart for GitHub Actions: https://docs.github.com/en/actions/get-started/quickstart
What’s the point of using Github Actions? https://www.reddit.com/r/devops/comments/1nlybf6/whats_the_point_of_using_github_actions/
What is CI/CD: https://about.gitlab.com/topics/ci-cd/
What is CI/CD (again): https://github.com/resources/articles/ci-cd
IBM Bob: https://bob.ibm.com/

Granite Guardian 🪨

Alain Airom (Ayrom) — Thu, 07 May 2026 09:36:23 +0000

A very short introduction on Granite Guardian 🛡️

What are LLM Guardians? An Introduction

At their core, LLM Guardians act as a protective and evaluative layer for other AI models. They are trained on instruction-fine-tuned languages models and use human-annotated and synthetic red-teaming data to detect risks.

Key features of these models include:

Pre-baked Criteria: They come ready to detect common risks such as jailbreak attempts, profanity, and hallucinations in Retrieval-Augmented Generation (RAG) or tool-calling workflows.
Bring Your Own Criteria (BYOC): Users can define their own natural-language rules, such as specific formatting requirements, length constraints, or domain-specific safety guidelines.
Hybrid Thinking Modes:

<no-think>: Provides a low-latency "yes" or "no" judgment, ideal for real-time production guardrails.
<think>: Generates a detailed reasoning trace before the final score, which is useful for auditing, debugging, or justifying a decision to a human reviewer.

Why are they needed?

The need for LLM Guardians arises from several critical challenges in deploying AI:

Safety and Risk Mitigation: They help detect dimensions catalogued in frameworks like the IBM AI Risk Atlas, ensuring that models do not promote harmful, illegal, or unethical behavior.
Hallucination Detection: Guardians are highly effective at identifying when a model generates false information, especially in complex agentic workflows or RAG systems where accuracy is paramount.
Instruction Following: They can evaluate if an assistant’s response faithfully follows multi-part requirements, such as “Each line must start with a capital letter,” providing a reliable way to automate quality checks.
Model Observability: By acting as an independent judge, they provide a layer of monitoring and assessment that can outperform much larger general-purpose models on specific fact-checking benchmarks.

IBM Granite Guardian

The Granite Guardian family is a collection of models designed to judge if the input prompts and the output responses of an LLM based system meet specified criteria. The models come pre-baked with certain criteria including but not limited to: jailbreak attempts, profanity, and hallucinations related to tool calls and retrieval augmented generation in agent-based systems. Additionally, the models also allow users to bring their own criteria and tailor the judging behavior to specific use-cases.

Trained on instruction fine-tuned Granite languages models, these models can help with detection along many key dimensions catalogued in the IBM AI Risk Atlas. These models are trained on unique data comprising human annotations from socioeconomically diverse people and synthetic data informed by internal red-teaming. They outperform similar models on standard benchmarks.

Excerpt from GitHub repository

The implementation is very simple and straighforward as shown in the following samples.

Detect groundedness in RAG settings (think mode) 🕵🏻‍♂️

context_text = """Eat (1964) is a 45-minute underground film created by Andy Warhol and featuring painter Robert Indiana, filmed on Sunday, February 2, 1964, in Indiana's studio. The film was first shown by Jonas Mekas on July 16, 1964, at the Washington Square Gallery at 530 West Broadway.
Jonas Mekas (December 24, 1922 – January 23, 2019) was a Lithuanian-American filmmaker, poet, and artist who has been called "the godfather of American avant-garde cinema"."""
documents = [{"doc_id": "0", "text": context_text}]
response_text = "The film Eat was first shown by Jonas Mekas on December 24, 1922 at the Washington Square Gallery at 530 West Broadway."

criteria = (
    "A text is considered ungrounded or unfaithful if it includes information "
    "lacking support from, or directly contradicting, the provided document(s). "
    "This risk arises when the text fabricates details, misinterprets the content, "
    "or makes unsupported extrapolations beyond what is explicitly stated in the "
    "document(s)."
)

messages = [
    {"role": "assistant", "content": response_text},
    {"role": "user", "content": build_guardian_block(criteria, think=True)},
]

prompt = tokenizer.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True, documents=documents
)
output = llm.generate([prompt], sampling_params)
response = output[0].outputs[0].text.strip()

score, trace = parse_response(response)
print(f"# score: {score}")  # yes
print(f"# trace: {trace}")

Detect function-calling hallucination (no-think mode) 🥷🏿

tools = [{
    "name": "comment_list",
    "description": "Fetches a list of comments for a specified video using the given API.",
    "parameters": {
        "aweme_id": {"description": "The ID of the video.", "type": "int", "default": "7178094165614464282"},
        "cursor":   {"description": "The cursor for pagination. Defaults to 0.", "type": "int, optional", "default": "0"},
        "count":    {"description": "The number of comments to fetch. Maximum is 30. Defaults to 20.", "type": "int, optional", "default": "20"},
    },
}]

user_text = "Fetch the first 15 comments for the video with ID 456789123."
response_text = json.dumps([{
    "name": "comment_list",
    "arguments": {
        "video_id": 456789123,  # Wrong argument name: should be "aweme_id"
        "count": 15,
    },
}])

criteria = (
    "Function call hallucination occurs when a text includes function calls that "
    "either don't adhere to the correct format defined by the available tools or "
    "are inconsistent with the query's requirements. This risk arises from function "
    "calls containing incorrect argument names, values, or types that clash with "
    "the tool definitions or the query itself."
)

messages = [
    {"role": "user", "content": user_text},
    {"role": "assistant", "content": response_text},
    {"role": "user", "content": build_guardian_block(criteria, think=False)},
]

prompt = tokenizer.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True, available_tools=tools
)
output = llm.generate([prompt], sampling_params)
response = output[0].outputs[0].text.strip()

score, _ = parse_response(response)
print(f"# score: {score}")  # yes

Conclusion

Ultimately, as AI systems transition from simple chatbots to autonomous agents and critical enterprise tools, the margin for error effectively disappears. Granite Guardians are not just an optional safety layer but a fundamental necessity for responsible AI deployment; they bridge the gap between “generative potential” and “operational reliability.” By providing real-time, explainable oversight — capable of catching everything from subtle hallucinations to complex policy violations — these models ensure that AI remains a helpful asset rather than a liability, offering the precise, programmable guardrails required to build lasting trust between technology and the people who use it.

>>> Thanks for reading <<<

Foundations of Distributed Streaming: A Book Review of “Kafka for Architects”

Alain Airom (Ayrom) — Tue, 05 May 2026 12:20:43 +0000

Understanding why even Kafka exists!?

Introduction

Since the recent acquisition of Confluent by IBM, I was rather a stranger to Apache Kafka and data streaming. However, since that major industry shift, I’ve become very interested in the mechanics of real-time data and am looking to spot high-quality resources to master the matter. This synthesis one of my latests reading, covering one of the most respected modern guides for transitioning from traditional request-response architectures to event-driven ecosystems.

TL;DR-Kafka

Originally developed at LinkedIn and later open-sourced as an Apache Software Foundation project, Apache Kafka is a distributed event-streaming platform designed to handle high-volume, real-time data feeds. It functions as a distributed commit log, allowing for the seamless publishing, storing, and processing of streams of records as they occur, which effectively decouples data producers from data consumers in a scalable and fault-tolerant manner. In modern architecture, it is used for a wide variety of critical tasks, including real-time data integration, stream analytics, log aggregation, and building event-driven microservices that require high throughput and low latency. Due to its reliability and massive scalability, Kafka is utilized by thousands of global enterprises, including industry leaders like LinkedIn, Netflix, Uber, Airbnb, and Goldman Sachs, to power everything from recommendation engines and fraud detection to real-time payment processing and activity tracking.

Disclaimer: Before going further, please note that I am not affiliated, associated, authorized, endorsed by, or in any way officially connected with Manning Publications or the author, Katya Gorshkova. This document is a synthesis intended for educational and reference purposes based on the content of the book.

All images provided are either from the book or the GitHub repositories cited!

Overall view (Part 1)-Architectural Foundations of Kafka

The book establishes Kafka not merely as a “message broker” (like RabbitMQ or ActiveMQ) but as a distributed streaming platform and a distributed commit log.

The Log-Centric View

At its core, Kafka is built on the concept of an append-only immutable log. This architectural choice ensures:

Sequential I/O: High throughput by avoiding random disk seeks.
Determinism: Events are stored in the order they arrived, allowing for “time-travel” debugging and state reconstruction.
Decoupling: Producers don’t need to know who the consumers are; they simply append to the log.

Key Components

Brokers and Clusters: Kafka runs as a cluster of servers (brokers). Architects must understand how data is distributed across these nodes to ensure high availability.
Topics and Partitions: Topics are logical categories, while partitions are the physical unit of parallelism. The book emphasizes that partitioning strategy is the most critical decision an architect makes for scalability.

Event-Driven Architecture (EDA) Patterns

Gorshkova spends significant time detailing how Kafka fits into broader enterprise patterns:

CQRS (Command Query Responsibility Segregation): Using Kafka to separate the “write” model (commands) from the “read” model (queries). Kafka acts as the bridge that updates read-optimized databases in real-time.
Event Sourcing: Instead of storing the current state of an object, you store the sequence of events that led to that state. Kafka’s persistence makes it an ideal “Source of Truth.”
Saga Pattern: Managing distributed transactions in microservices without a central coordinator by using events to trigger compensating transactions.

Data Governance and Schema Registry

A major focus for architects is Data Contracts. The book argues that without schema management, a Kafka cluster becomes a “data swamp.”

Schema Registry: A centralized repository for Avro, Protobuf, or JSON schemas.
Evolution: How to handle “Forward,” “Backward,” and “Full” compatibility so that changing a producer doesn’t break dozens of downstream consumers.

Ecosystem and Tools (GitHub References)

The book cites several industry-standard tools to solve complex architectural challenges. Below are the key GitHub references mentioned and their specific roles:

Cruise Control

Reference: https://github.com/linkedin/cruise-control
Usage & Explanation: Cited as the gold standard for cluster load balancing. In a large Kafka deployment, some brokers inevitably become “hot” (overloaded). Cruise Control automates the redistribution of partitions based on CPU, disk, and network utilization, reducing the operational burden on architects.

/*
 * Copyright 2019 LinkedIn Corp. Licensed under the BSD 2-Clause License (the "License"). See License in the project root for license information.
 */

package com.linkedin.kafka.cruisecontrol;

import com.codahale.metrics.MetricRegistry;
import com.codahale.metrics.jmx.JmxReporter;
import com.linkedin.kafka.cruisecontrol.async.AsyncKafkaCruiseControl;
import com.linkedin.kafka.cruisecontrol.config.KafkaCruiseControlConfig;
import com.linkedin.kafka.cruisecontrol.config.constants.WebServerConfig;
import com.linkedin.kafka.cruisecontrol.metrics.LegacyObjectNameFactory;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public abstract class KafkaCruiseControlApp {
  protected static final Logger LOG = LoggerFactory.getLogger(KafkaCruiseControlApp.class);
  protected static final String METRIC_DOMAIN = "kafka.cruisecontrol";

  protected final KafkaCruiseControlConfig _config;
  protected final AsyncKafkaCruiseControl _kafkaCruiseControl;
  protected final JmxReporter _jmxReporter;
  protected MetricRegistry _metricRegistry;
  protected Integer _port;
  protected String _hostname;

  KafkaCruiseControlApp(KafkaCruiseControlConfig config, Integer port, String hostname) {
    this._config = config;
    _metricRegistry = new MetricRegistry();
    _jmxReporter = JmxReporter.forRegistry(_metricRegistry).inDomain(METRIC_DOMAIN)
            .createsObjectNamesWith(LegacyObjectNameFactory.getInstance()).build();
    _jmxReporter.start();
    _port = port;
    _hostname = hostname;

    _kafkaCruiseControl = new AsyncKafkaCruiseControl(config, _metricRegistry);

  }

  public String getHostname() {
    return _hostname;
  }

  public int getPort() {
    return _port;
  }

  public void start() throws Exception {
    _kafkaCruiseControl.startUp();
  }

  void registerShutdownHook() {
    Runtime.getRuntime().addShutdownHook(new Thread(this::stop));
  }

  /**
   * Stops Cruise Control
   */
  public void stop() {
    _kafkaCruiseControl.shutdown();
    _jmxReporter.close();
  }

  public abstract String serverUrl();

  protected void printStartupInfo() {
    boolean corsEnabled = _config.getBoolean(WebServerConfig.WEBSERVER_HTTP_CORS_ENABLED_CONFIG);
    boolean vertxEnabled = _config.getBoolean(WebServerConfig.VERTX_ENABLED_CONFIG);
    String webApiUrlPrefix = _config.getString(WebServerConfig.WEBSERVER_API_URLPREFIX_CONFIG);
    String uiUrlPrefix = _config.getString(WebServerConfig.WEBSERVER_UI_URLPREFIX_CONFIG);
    String webDir = _config.getString(WebServerConfig.WEBSERVER_UI_DISKPATH_CONFIG);
    String sessionPath = _config.getString(WebServerConfig.WEBSERVER_SESSION_PATH_CONFIG);
    System.out.println(">> ********************************************* <<");
    System.out.println(">> Application directory            : " + System.getProperty("user.dir"));
    System.out.println(">> REST API available on            : " + webApiUrlPrefix);
    System.out.println(">> Web UI available on              : " + uiUrlPrefix);
    System.out.println(">> Web UI Directory                 : " + webDir);
    System.out.println(">> Cookie prefix path               : " + sessionPath);
    System.out.println(">> Kafka Cruise Control started on  : " + serverUrl());
    System.out.println(">> CORS Enabled ?                   : " + corsEnabled);
    System.out.println(">> Vertx Enabled ?                  : " + vertxEnabled);
    System.out.println(">> ********************************************* <<");
  }

}

Excerpt of the Github Repository

Cruise Control is a product that helps run Apache Kafka clusters at large scale. Due to the popularity of Apache Kafka, many companies have increasingly large Kafka clusters with hundreds of brokers. At LinkedIn, we have 10K+ Kafka brokers, which means broker deaths are an almost daily occurrence and balancing the workload of Kafka also becomes a big overhead.

Kafka Cruise Control is designed to address this operational scalability issue.

JMX Monitoring Stacks

Reference: https://github.com/confluentinc/jmx-monitoring-stacks
Usage & Explanation: Kafka exposes internal metrics via Java Management Extensions (JMX). This repository provides pre-configured dashboards (often using Prometheus and Grafana) to monitor broker health, consumer lag, and throughput. Architects use this to define Service Level Indicators (SLIs).

scrape_configs:
  - job_name: Confluent Cloud
    scrape_interval: 1m
    scrape_timeout: 1m
    honor_timestamps: true
    static_configs:
      - targets:
        - api.telemetry.confluent.cloud
    scheme: https
    basic_auth:
      username: $CONFLUENT_CLOUD_API_KEY
      password: $CONFLUENT_CLOUD_API_SECRET
    metrics_path: /v2/metrics/cloud/export
    params:
      resource.kafka.id: [${CCLOUD_KAFKA_LKC_IDS}]
      resource.connector.id: [${CCLOUD_CONNECT_LCC_IDS}]
      resource.ksql.id: [${CCLOUD_KSQL_LKSQLC_IDS}]
      resource.schema_registry.id: [${CCLOUD_SR_LSRC_IDS}]
  - job_name: Confluent Cost Exporter
    scrape_interval: 5m
    scrape_timeout: 30s
    honor_labels: true 
    metrics_path: /probe  
    static_configs:
      - targets: ['confluent_cost_exporter:7979']

Kafka Connectors

Reference: Various repositories under https://github.com/confluentinc
Usage & Explanation: Instead of writing custom code to move data from a database to Kafka, the book suggests using Kafka Connect. These references provide ready-made “Source” and “Sink” connectors (e.g., Debezium for CDC) to ensure reliable data ingestion and egress.

Deployment and Reliability

Architects must design for failure. The book covers:

Replication Factor: Ensuring data exists on multiple brokers.
In-Sync Replicas (ISR): Understanding the trade-offs between “at-least-once,” “at-most-once,” and “exactly-once” delivery semantics.
Multi-Region Deployment: Strategies like MirrorMaker 2 or Confluent Cluster Linking for disaster recovery and geo-replication.

Synthesis view of Book Chapters (Part 2)

> The chapter’s categorization is based on my own PoV and does not follow the exact actual book’s organization!

A walkthrough of what are my takes from each of the book’s chapters.

Chapter 1 (up to chapter 3-Introductory sections): Introduction to Kafka

This chapter establishes why Kafka exists. Unlike traditional message brokers (like RabbitMQ) that delete messages once they are read, Kafka is a distributed commit log.

The Problem: Traditional architectures often suffer from “spaghetti” integration, where every system needs a direct connection to every other system.
The Solution: Kafka acts as a central nervous system, allowing data producers to send data once and multiple consumers to read it at their own pace.

Chapter 2: Essential Concepts

Before building, you must understand the terminology:

Topics & Partitions: A Topic is a category or feed name. Topics are split into Partitions, which are the fundamental unit of parallelism.
Offsets: Every message in a partition is assigned a unique, sequential ID called an offset. This allows consumers to track exactly where they left off.
Brokers: These are the servers that form the Kafka cluster, storing the data and serving the clients.

Chapter 3: The Architecture of Kafka

This chapter dives into the “Brain” of the operation.

Replication: To prevent data loss, Kafka replicates partitions across multiple brokers. One broker acts as the Leader, and others act as Followers.
Cluster Management: It explains the transition from using ZooKeeper to KRaft, which allows Kafka to manage its own metadata internally, making it much easier to scale to millions of partitions.

Chapter 4 (up to chapter 6-Implementation and Data Flow): Producing Messages

Architecting the “write” side of the system:

Load Balancing: Producers decide which partition to send a message to using a partitioner (often a hash of a key, like a UserID).
Batching & Compression: To achieve high throughput, Kafka batches small messages together and compresses them before sending them over the wire.
Acks (Acknowledgements): You can configure if a producer waits for one broker to receive the data (acks=1) or all replicas (acks=all) to ensure durability.

Chapter 5: Consuming Messages

Architecting the “read” side:

Consumer Groups: This is Kafka’s primary scaling mechanism. If you have a topic with 4 partitions and a group of 4 consumers, each consumer takes one partition.
Rebalancing: The chapter explains what happens when a consumer fails: Kafka automatically redistributes the workload among the remaining healthy consumers.

Chapter 6: Message Delivery Semantics

What is critical for data integrity:

At-least-once: Messages are never lost but may be redelivered if a consumer crashes before committing its offset.
Exactly-once (Transactions): Kafka’s “magic” feature that ensures even if a system fails, the end result is as if the message was processed exactly one time.

Chapter 7 (up to the end-Advanced Ecosystem and Operations)-Kafka Streams

Instead of just moving data, this chapter teaches you how to process it in real-time.

Stateless vs. Stateful: Simple filtering (Stateless) vs. complex operations like “How many orders did this user place in the last hour?” (Stateful).
Windowing: Processing data in time blocks (e.g., 5-minute windows) to identify trends as they happen.

Chapter 8: Kafka Connect

Why write code when you can use a connector?

Source Connectors: Automatically pull data from a database (like MongoDB or Postgres) into Kafka.
Sink Connectors: Automatically push data from Kafka into a storage engine (like S3, Elasticsearch, or Snowflake).

Chapter 9: Security and Operations

The “Day 2” realities of running Kafka:

Encryption: Using TLS to protect data in transit.
Authentication: Using SASL or Kerberos to ensure only authorized apps can read or write data.
Monitoring: Tracking metrics like “Consumer Lag” — the gap between the latest message and where the consumer currently is — which is the most vital health check for any Kafka architect.

Chapter 10: Kafka Projects (I think this one is one of the most

important chapter for me, and also to build a project around Kafka!)

Defining Project Requirements: the foundation of a Kafka project involves translating business logic into technical specifications.

Workflow Identification: Architects must identify event-driven workflows and decompose business processes into discrete events.
Functional Requirements: This includes defining topic names, selecting appropriate message keys for ordering, and determining data types.
Nonfunctional Requirements: These are critical for cluster sizing and include:
Throughput and Latency: Estimating the volume of messages per second.
Durability and Availability: Setting replication factors and min.insync.replicas.
Retention: Defining how long data stays in the cluster based on business needs and disk capacity.

Maintaining Cluster Structure: Once requirements are set, the “source of truth” for the infrastructure must be managed.

Tooling: While CLI and UI tools are useful for exploration, they are insufficient for enterprise-grade management.
Environment Management: Establishing consistent configurations across Development, Test, and Production environments is essential for stability. Testing Kafka Applications: testing in a distributed, asynchronous environment requires a multi-layered approach to ensure reliability and performance.

Chapter 11: Data Governance and Schema Management

As a Kafka cluster grows, the biggest risk isn’t technical failure, but “data rot” — where producers send data that consumers can’t understand.

The Schema Registry: This chapter introduces the Confluent Schema Registry (or similar tools), which acts as a gatekeeper. It ensures that every message sent to a topic follows a predefined format (like Avro, Protobuf, or JSON Schema).
Compatibility Rules: It explains how to manage “Evolution.” For example, if you add a new field to a database, how do you ensure the older consumers don’t crash? The chapter covers Forward, Backward, and Full compatibility strategies.
Data Lineage: It discusses tracking where data comes from and where it goes, which is essential for regulatory compliance (like GDPR or HIPAA).

Chapter 12: Future Trends and Architecture Evolution

This concluding chapter looks at how Kafka is evolving from a simple “tool” into a “cloud-native data backbone.”

Tiered Storage: This is a major architectural shift. Instead of keeping all data on expensive, fast disks on the Kafka brokers, older data is automatically moved to cheaper object storage (like Amazon S3 or Google Cloud Storage). This allows for nearly infinite data retention without ballooning costs.
Serverless Kafka: The rise of “Kafka as a Service” (like Confluent Cloud or Amazon MSK), where architects don’t manage servers at all and instead focus purely on data streams and throughput.
Event-Driven Evolution: The chapter explores how companies are moving toward “Data Mesh” architectures, where Kafka isn’t just a side-tool but the primary way different business departments share information.

Conclusion: Wrapping Up

“Kafka for Architects” serves as a bridge between high-level business requirements and low-level technical implementation. It moves beyond the “how-to” of coding and focuses on the “why” of system design.

The synthesis of the book reveals that successful Kafka implementation relies on three pillars:

Correct Partitioning: The key to throughput and scaling.
Strict Schema Governance: The key to long-term maintainability and preventing system-wide breakages.
Observability: Using tools like Cruise Control and JMX Stacks to manage the inherent complexity of distributed systems.

For anyone entering the streaming space — especially in light of the IBM/Confluent era — understanding these architectural primitives is essential for building resilient, real-time data backbones that can scale with the enterprise.

Last but not least, I’ve gained so much insight from this book! If you’re like me and want to understand the core philosophy of Apache Kafka while also getting hands-on with implementation, this is a must-read. It bridges the gap between the basics and real-world application perfectly.

>>> Thanks for reading <<<

Inside Docling Factory: Building a Multimodal RAG Powerhouse

Alain Airom (Ayrom) — Sat, 02 May 2026 15:25:23 +0000

The vO.1a release of a project on which I’m working on for a while…📍

Intro-TL;DR

We’ve all been there: staring at a pile of messy PDFs, complex XBRL financial reports, and scattered CSVs, wondering how to turn that “dark data” into something an LLM can actually understand. Today, I’m pulling back the curtain on Docling Factory, a project I’ve been refining to solve exactly that.

The purpose and final expectation of Docling Factory is to design itas a multimodal document processing pipeline. It transforms unstructured documents (PDFs, Docx, etc.) into structured formats and provides an interactive chat interface to query those documents using a local or remote LLM.

The aim is to have a set of tools which are more than just a parser; it’s a full-stack document intelligence pipeline that bridges the gap between raw files and meaningful conversation.

🔩 Key Components

Web Interface: Built with Gradio, providing a multi-tabbed UI for uploading, parsing, and chatting.
Parsing Engine (DoclingParser): Leverages the docling library for layout-aware document conversion.
RAG Engine (RAGEngine): Orchestrates semantic search using OpenSearch as a vector database and Ollama or LiteLLM for embeddings and text generation.
Observability: Integrated with OpenLLMetry and a custom MetricsCollector to track latency, token usage, and system health.
LLM Engine: The LLM orchestration layer follows a hybrid approach: local inference is handled by Ollama, while a LiteLLM gateway provides a unified API interface for external model integration. This setup provides the best of both worlds — local execution for standard tasks and an easy ‘escape hatch’ to commercial LLMs via a standardized gateway when higher reasoning capabilities are required.

The Core Engine: Docling & Layout Awareness

At the heart of the system is the DoclingParser. Unlike traditional parsers that treat a page as a flat bag of words, this engine is layout-aware. It identifies headers, tables, and even those tricky images. Using the docling library, the user can convert a complex PDF into clean Markdown while keeping the structure intact.

I’ve baked in support for RapidOCR, EasyOCR, and even macOS Vision. Whether you have a digital-native DOCX or a grainy scan of a 1990s invoice, the parser adapts. It even handles XBRL and CSV files natively, transforming structured data into LLM-friendly formats.

# docling_parser.py
"""
Docling Parser Module - Enhanced Version
Handles document parsing using the Docling library with support for:
- Batch and individual processing
- Multiple output formats (Markdown, HTML, JSON, Multimodal)
- Figure extraction
- Full page OCR with multiple OCR engines
- XBRL document conversion
- CSV file conversion
"""

import os
import logging
from pathlib import Path
from datetime import datetime
from typing import List, Dict, Optional, Union, Callable
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import (
    PdfPipelineOptions,
    EasyOcrOptions,
    RapidOcrOptions,
    TesseractOcrOptions,
    OcrMacOptions
)
from docling_core.types.doc.base import ImageRefMode
from docling_core.types.doc.document import PictureItem, TableItem
import json

#####
#####
#####

def main():
    """Example usage of the enhanced DoclingParser class."""
    parser = DoclingParser(use_gpu=False, output_dir="output")

    # Example: Parse with OCR and figure extraction
    def progress_update(message):
        print(f"Progress: {message}")

    # Batch processing with all features
    def batch_progress(message, current, total):
        percentage = (current / total * 100) if total > 0 else 0
        print(f"[{percentage:.1f}%] {message}")

    results = parser.parse_batch(
        "input",
        output_formats=['markdown', 'html', 'json'],
        export_figures=True,
        export_multimodal=False,
        ocr_engine='easyocr',
        force_ocr=False,
        progress_callback=batch_progress
    )

    # Print summary
    print("\n" + "="*50)
    print("BATCH PROCESSING SUMMARY")
    print("="*50)
    for result in results:
        status_icon = "✓" if result["status"] == "success" else "✗"
        file_name = Path(result['input_file']).name
        if result["status"] == "success":
            formats = ", ".join(result.get('formats', []))
            figures = result.get('figure_count', 0)
            print(f"{status_icon} {file_name}: {formats} ({figures} figures)")
        else:
            print(f"{status_icon} {file_name}: {result.get('error', 'Unknown error')}")
    print("="*50)


if __name__ == "__main__":
    main()

# Made with Bob

Why Multimodal Matters: Documents aren’t just text. They have charts, figures, and diagrams. Docling Factory detects PictureItem elements and extracts them as separate PNGs, or embeds them directly into the Markdown. This means your RAG system doesn't just "read"—it "sees."

RAG & Vector Storage (`rag_engine.py`)

How do the user(s) chat with these documents? I built the RAGEngine to be as flexible as possible. It uses OpenSearch with k-NN (k-Nearest Neighbors) search for lightning-fast vector retrieval. The RAG system enables “Chat with Documents” by indexing parsed text into a vector space.

Vector Database: Uses OpenSearch with k-NN (k-Nearest Neighbors) search enabled. It uses the lucene engine and cosinesimil space type for vector comparisons.

Hybrid Backend

The real magic is the Dual Backend Support. You can run everything locally using Ollama (perfect for privacy-sensitive data) or flip a switch to LiteLLM. LiteLLM acts as a gateway to over 100 providers, letting you use GPT-4, Claude, or Gemini without changing a single line of business logic.

Ollama: For local execution of models like llama3.2 and granite-embedding.

LiteLLM: Acts as an AI Gateway to connect to remote providers (OpenAI, Anthropic) or proxied local models.

# LiteLLM Configuration File
# This file configures the LiteLLM AI Gateway for unified access to multiple LLM providers
# Documentation: https://docs.litellm.ai/docs/proxy/configs

model_list:
  # OpenAI Models (requires OPENAI_API_KEY environment variable)
  - model_name: gpt-4
    litellm_params:
      model: gpt-4
      api_key: os.environ/OPENAI_API_KEY  # Never hardcode API keys

  - model_name: gpt-3.5-turbo
    litellm_params:
      model: gpt-3.5-turbo
      api_key: os.environ/OPENAI_API_KEY  # Never hardcode API keys

  # OpenAI Embeddings
  - model_name: text-embedding-ada-002
    litellm_params:
      model: text-embedding-ada-002
      api_key: os.environ/OPENAI_API_KEY  # Never hardcode API keys

  # Anthropic Claude (requires ANTHROPIC_API_KEY environment variable)
  - model_name: claude-3-sonnet
    litellm_params:
      model: claude-3-sonnet-20240229
      api_key: os.environ/ANTHROPIC_API_KEY  # Never hardcode API keys

  - model_name: claude-3-opus
    litellm_params:
      model: claude-3-opus-20240229
      api_key: os.environ/ANTHROPIC_API_KEY  # Never hardcode API keys

  # Local Ollama models (connect to host Ollama)
  - model_name: ollama/llama3.2
    litellm_params:
      model: ollama/llama3.2:latest
      api_base: http://host.docker.internal:11434

  - model_name: ollama/granite-embedding
    litellm_params:
      model: ollama/granite-embedding:30m
      api_base: http://host.docker.internal:11434

  # Azure OpenAI (requires AZURE_API_KEY, AZURE_API_BASE, AZURE_API_VERSION)
  # - model_name: azure-gpt-4
  #   litellm_params:
  #     model: azure/gpt-4
  #     api_key: os.environ/AZURE_API_KEY  # Never hardcode API keys
  #     api_base: os.environ/AZURE_API_BASE
  #     api_version: os.environ/AZURE_API_VERSION

  # Google Vertex AI (requires GOOGLE_APPLICATION_CREDENTIALS)
  # - model_name: gemini-pro
  #   litellm_params:
  #     model: vertex_ai/gemini-pro
  #     vertex_project: os.environ/VERTEX_PROJECT
  #     vertex_location: os.environ/VERTEX_LOCATION

  # AWS Bedrock (requires AWS credentials)
  # - model_name: bedrock-claude
  #   litellm_params:
  #     model: bedrock/anthropic.claude-v2
  #     aws_region_name: us-east-1

# General settings
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY  # REQUIRED: Set via environment variable, never hardcode
  database_url: os.environ/DATABASE_URL  # PostgreSQL connection string

  # Logging
  success_callback: ["langfuse"]  # Optional: integrate with Langfuse for observability

  # Rate limiting (optional)
  # max_parallel_requests: 100
  # max_budget: 100  # USD

  # Caching (optional)
  # cache: true
  # cache_params:
  #   type: "redis"
  #   host: "redis"
  #   port: 6379

# Router settings for load balancing and fallbacks
router_settings:
  routing_strategy: simple-shuffle  # Options: simple-shuffle, least-busy, usage-based-routing
  model_group_alias:
    gpt-4-group:
      - gpt-4
      - azure-gpt-4  # Fallback to Azure if OpenAI fails

  # Retry settings
  num_retries: 2
  timeout: 600  # seconds

  # Fallback models
  fallbacks:
    - gpt-4: ["gpt-3.5-turbo"]
    - claude-3-opus: ["claude-3-sonnet"]

# Environment variables required:
# - LITELLM_MASTER_KEY: Master key for API authentication
# - DATABASE_URL: PostgreSQL connection string
# - OPENAI_API_KEY: For OpenAI models (optional)
# - ANTHROPIC_API_KEY: For Claude models (optional)
# - AZURE_API_KEY, AZURE_API_BASE, AZURE_API_VERSION: For Azure OpenAI (optional)
# - GOOGLE_APPLICATION_CREDENTIALS: For Google Vertex AI (optional)
# - AWS credentials: For AWS Bedrock (optional)

# Made with Bob

Chunking: Employs RecursiveCharacterTextSplitter with a chunk size of 500 characters and 100-character overlap to ensure context is preserved without exceeding model limits.

# rag_engine.py
"""
RAG Engine Module
Implements Retrieval-Augmented Generation using OpenSearch and Ollama.
Supports document indexing, semantic search, and chat with documents.
"""

import os
import logging
from pathlib import Path
from typing import List, Dict, Optional, Tuple
import json
from datetime import datetime

# OpenSearch
from opensearchpy import OpenSearch, helpers
from opensearchpy.exceptions import NotFoundError

# LLM Clients
import ollama
from litellm import completion, embedding
import litellm

# LangChain for RAG orchestration
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_core.documents import Document

# OpenLLMetry for observability
from traceloop.sdk import Traceloop
from traceloop.sdk.decorators import workflow, task

# OpenTelemetry for metrics
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Metrics collector
from metrics_collector import MetricsCollector, initialize_metrics_collector, get_metrics_collector

#####
#####
#####

# Initialize LLM components based on configuration
        if use_litellm:
            logger.info("Using LiteLLM for embeddings and LLM")
            self.embeddings = LiteLLMEmbeddings(
                model=embedding_model,
                api_base=litellm_api_base,
                api_key=litellm_api_key
            )
            self.llm = LiteLLMLLM(
                model=llm_model,
                api_base=litellm_api_base,
                api_key=litellm_api_key
            )
        else:
            logger.info("Using Ollama for embeddings and LLM")
            self.embeddings = OllamaEmbeddings(model=embedding_model, base_url=ollama_base_url)
            self.llm = OllamaLLM(model=llm_model, base_url=ollama_base_url)

        # Text splitter for chunking
        # Reduced chunk size to avoid exceeding embedding model context length
        self.text_splitter = RecursiveCharacterTextSplitter(
            chunk_size=500,  # Reduced from 1000 to fit within model context
            chunk_overlap=100,  # Reduced overlap proportionally
            length_function=len,
        )

A Word on The RAG Database: OpenSeach RAG

The OpenSearch implementation serves as the high-performance backbone of the Docling Factory’s RAG engine, specifically configured as a vector database to handle complex semantic retrieval. Within the RAGEngine class, the system initializes an OpenSearch client that utilizes k-NN (k-Nearest Neighbors) search, leveraging the lucene engine and cosinesimil space type to measure the similarity between document chunks and user queries. During the indexing phase, the engine converts Markdown chunks into vectors—typically using a 384-dimensional model—and performs bulk uploads into a dedicated index where index.knn is set to true. For retrieval, the search method transforms the user’s prompt into an embedding and queries OpenSearch to return the top k most relevant context fragments based on their vector score, which are then used to augment the LLM's final response.

Observability: Seeing the Unseen

“Black box” AI is a no-go for production. That’s why I integrated OpenLLMetry. Through our MetricsCollector, the application tracks everything: latency, token usage, and even cost estimation. If a model starts acting up or a prompt is getting too expensive, you’ll see it on the Plotly-powered dashboard before it becomes a problem.

The MetricsCollector uses OpenTelemetry to intercept spans from LLM calls. The standalone_dashboard.py script can then generate a visual representation of this data using Plotly, showing error rates, token costs, and P95/P99 latency percentiles.

# metrics_collector.py
"""
OpenLLMetry Metrics Collector
Collects and aggregates metrics from OpenTelemetry traces for dashboard display.
"""

import logging
from typing import Dict, List, Optional
from datetime import datetime, timedelta
from collections import defaultdict
import threading
import time

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, ReadableSpan
from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
from opentelemetry.sdk.resources import Resource

logger = logging.getLogger(__name__)


class MetricsCollector(SpanExporter):
    """
    Custom span exporter that collects metrics from OpenTelemetry spans.
    Stores metrics in memory for dashboard display.
    """

    def __init__(self, max_history: int = 1000):
        """
        Initialize metrics collector.

        Args:
            max_history: Maximum number of spans to keep in history
        """
        self.max_history = max_history
        self.spans: List[Dict] = []
        self.metrics: Dict = {
            "total_requests": 0,
            "total_tokens": 0,
            "total_latency_ms": 0,
            "error_count": 0,
            "operations": defaultdict(int),
            "models_used": defaultdict(int),
            "hourly_requests": defaultdict(int),
            "latency_by_operation": defaultdict(list),
        }
        self.lock = threading.Lock()
        logger.info("MetricsCollector initialized")

######
######
######

Ensuring Reliability: The Docling Factory Test Suite

Building a complex document processing pipeline requires more than just functional code; it requires a rigorous testing framework to ensure that every component — from OCR to vector search — performs predictably under pressure. I’ve implemented a comprehensive suite of unit tests to validate the core logic of the factory.
Document Parsing Validation
The reliability of our ingestion starts with test_docling_parser.py. This test suite ensures that the DoclingParser correctly identifies and processes various file formats and OCR requirements:

Initialization & Formats: Verifies that the parser correctly initializes with or without GPU support and correctly identifies supported input extensions like .pdf, .docx, and .txt.
OCR Logic: Tests the validation of different OCR engines (RapidOCR, EasyOCR, etc.) and ensures that the system fails over to a default engine if an invalid one is specified.
Functional Success: Uses mocking of the DocumentConverter to simulate successful document exports to Markdown and JSON without requiring a full local setup.
Error Handling: Validates that the system gracefully handles “file not found” scenarios and unsupported file types.

RAG & Embedding Accuracy

To ensure our “chat with documents” feature doesn’t hallucinate or fail, test_rag_engine.py provides targeted testing for the retrieval pipeline:

Connectivity Checks: Includes health checks to verify that both the OpenSearch cluster and the Ollama model server are reachable.
Indexing Pipeline: Tests the workflow of splitting text into chunks and generating 384-dimensional embeddings (standard for models like all-minilm).
Semantic Search: Simulates search queries to verify that OpenSearch returns the expected hits and scores.
Embedding & LLM Classes: Provides isolated unit tests for OllamaEmbeddings and OllamaLLM to confirm they correctly format prompts and return responses with the right temperature settings.

# test_rag_engine.py
"""
Unit tests for rag_engine.py module
"""

import unittest
import os
import tempfile
from unittest.mock import Mock, patch, MagicMock
import sys

# Add parent directory to path
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))


class TestRAGEngine(unittest.TestCase):
    """Test cases for RAGEngine class"""

    def setUp(self):
        """Set up test fixtures"""
        self.test_dir = tempfile.mkdtemp()

    def tearDown(self):
        """Clean up test fixtures"""
        import shutil
        if os.path.exists(self.test_dir):
            shutil.rmtree(self.test_dir)

    @patch('rag_engine.OpenSearch')
    @patch('rag_engine.ollama')
    def test_initialization(self, mock_ollama, mock_opensearch):
        """Test RAG engine initialization"""
        from rag_engine import RAGEngine

        rag = RAGEngine(
            opensearch_host="localhost",
            opensearch_port=9200,
            embedding_model="test-embedding",
            llm_model="test-llm",
            enable_tracing=False
        )

        self.assertIsNotNone(rag)
        self.assertEqual(rag.embedding_model, "test-embedding")
        self.assertEqual(rag.llm_model, "test-llm")

    @patch('rag_engine.OpenSearch')
    @patch('rag_engine.ollama')
    def test_health_check(self, mock_ollama, mock_opensearch):
        """Test health check functionality"""
        from rag_engine import RAGEngine

        # Mock OpenSearch client
        mock_client = MagicMock()
        mock_client.ping.return_value = True
        mock_opensearch.return_value = mock_client

        # Mock Ollama client
        mock_ollama_client = MagicMock()
        mock_response = MagicMock()
        mock_response.models = []
        mock_ollama_client.list.return_value = mock_response
        mock_ollama.Client.return_value = mock_ollama_client

        rag = RAGEngine(enable_tracing=False)
        health = rag.health_check()

        self.assertIsInstance(health, dict)
        self.assertIn('opensearch', health)

    @patch('rag_engine.OpenSearch')
    @patch('rag_engine.ollama')
    def test_index_document(self, mock_ollama, mock_opensearch):
        """Test document indexing"""
        from rag_engine import RAGEngine

        # Mock OpenSearch
        mock_client = MagicMock()
        mock_client.indices.exists.return_value = True
        mock_opensearch.return_value = mock_client

        # Mock Ollama embeddings
        mock_ollama.embeddings.return_value = {
            'embedding': [0.1] * 384
        }

        rag = RAGEngine(enable_tracing=False)

        result = rag.index_document(
            file_path="test.pdf",
            content="Test content for indexing",
            metadata={"source": "test"}
        )

        self.assertIsInstance(result, dict)
        self.assertIn('chunks_indexed', result)

    @patch('rag_engine.OpenSearch')
    @patch('rag_engine.ollama')
    def test_search(self, mock_ollama, mock_opensearch):
        """Test semantic search"""
        from rag_engine import RAGEngine

        # Mock OpenSearch search response
        mock_client = MagicMock()
        mock_client.search.return_value = {
            'hits': {
                'hits': [
                    {
                        '_source': {
                            'content': 'Test result',
                            'file_path': 'test.pdf'
                        },
                        '_score': 0.9
                    }
                ]
            }
        }
        mock_opensearch.return_value = mock_client

        # Mock Ollama embeddings
        mock_ollama.embeddings.return_value = {
            'embedding': [0.1] * 384
        }

        rag = RAGEngine(enable_tracing=False)
        results = rag.search("test query", top_k=5)

        self.assertIsInstance(results, list)

    @patch('rag_engine.OpenSearch')
    @patch('rag_engine.ollama')
    def test_get_stats(self, mock_ollama, mock_opensearch):
        """Test getting index statistics"""
        from rag_engine import RAGEngine

        # Mock OpenSearch stats
        mock_client = MagicMock()
        mock_client.count.return_value = {'count': 100}
        mock_client.indices.stats.return_value = {
            'indices': {
                'documents': {
                    'primaries': {
                        'store': {'size_in_bytes': 1024000}
                    }
                }
            }
        }
        mock_opensearch.return_value = mock_client

        rag = RAGEngine(enable_tracing=False)
        stats = rag.get_stats()

        self.assertIsInstance(stats, dict)
        self.assertIn('total_chunks', stats)


class TestOllamaEmbeddings(unittest.TestCase):
    """Test cases for OllamaEmbeddings class"""

    @patch('rag_engine.ollama')
    def test_embed_documents(self, mock_ollama):
        """Test embedding multiple documents"""
        from rag_engine import OllamaEmbeddings

        mock_ollama.embeddings.return_value = {
            'embedding': [0.1] * 384
        }

        embedder = OllamaEmbeddings(model="test-model")
        texts = ["text1", "text2", "text3"]
        embeddings = embedder.embed_documents(texts)

        self.assertIsInstance(embeddings, list)
        self.assertEqual(len(embeddings), 3)

    @patch('rag_engine.ollama')
    def test_embed_query(self, mock_ollama):
        """Test embedding a single query"""
        from rag_engine import OllamaEmbeddings

        mock_ollama.embeddings.return_value = {
            'embedding': [0.1] * 384
        }

        embedder = OllamaEmbeddings(model="test-model")
        embedding = embedder.embed_query("test query")

        self.assertIsInstance(embedding, list)
        self.assertEqual(len(embedding), 384)


class TestOllamaLLM(unittest.TestCase):
    """Test cases for OllamaLLM class"""

    @patch('rag_engine.ollama')
    def test_generate(self, mock_ollama):
        """Test LLM text generation"""
        from rag_engine import OllamaLLM

        mock_ollama.generate.return_value = {
            'response': 'Generated response'
        }

        llm = OllamaLLM(model="test-model")
        response = llm.generate("test prompt")

        self.assertIsInstance(response, str)
        self.assertEqual(response, 'Generated response')

    @patch('rag_engine.ollama')
    def test_generate_with_temperature(self, mock_ollama):
        """Test LLM generation with temperature parameter"""
        from rag_engine import OllamaLLM

        mock_ollama.generate.return_value = {
            'response': 'Generated response'
        }

        llm = OllamaLLM(model="test-model", temperature=0.7)
        response = llm.generate("test prompt")

        self.assertIsInstance(response, str)


if __name__ == '__main__':
    unittest.main()

# Made with Bob

Metrics and Observability

Finally, the test_metrics_collector.py suite ensures that our observability dashboard isn't just showing pretty numbers, but accurate data:

Span Management: Validates the export of OpenTelemetry spans, ensuring that operation names, start times, and end times are captured correctly.
Aggregation Logic: Tests the collector’s ability to sum up token usage (prompt vs. completion) and calculate error counts across different operations.
Data Structures: Verifies that time-series data for hourly requests and latency percentiles are generated in the correct format for the Plotly dashboard.

By maintaining these tests, the application ensure that by adding new features — like new OCR backends or remote LLM providers via LiteLLM — the core foundation of the Docling Factory remains rock solid.

Flexible Processing: From Single Files to Batch Operations

The Docling Factory is engineered for maximum versatility, allowing users to choose between processing individual documents or executing high-volume batch operations. For targeted tasks, the parse_single_file function handles specific uploads via the Gradio interface, while the parse_batch method in the DoclingParser class enables the system to traverse entire directories and convert multiple files in a single pass. Whether you are indexing a single technical manual or a massive archive of financial reports, the architecture scales to meet the demand, ensuring consistent output across all supported formats like Markdown, JSON, and HTML.

CPU or GPU?

To accommodate varying hardware environments, the application is designed to operate seamlessly with or without GPU acceleration. The DoclingParser class includes a use_gpu initialization parameter that toggles the processing backend, and the deployment infrastructure provides dedicated Docker images for both CPU-only and GPU-enabled configurations. This flexibility ensures that the factory can be deployed on standard local machines using CPU-based OCR engines like RapidOCR, or on high-performance servers leveraging NVIDIA GPUs to significantly accelerate the layout analysis and document conversion pipeline.

Cloud Deployment

The Docling Factory features a production-ready cloud deployment architecture built on Kubernetes, supporting highly available and scalable environments. The infrastructure is designed with a multi-container strategy, utilizing Docker for both CPU-optimized and GPU-accelerated versions of the application. To ensure operational stability, the deployment includes:

Orchestration and Scaling: Kubernetes deployments manage multiple replicas of the application, with specific resource limits (up to 8Gi memory and 4000m CPU for GPU nodes) and health checks for both liveness and readiness.
Infrastructure Components: Integrated services include OpenSearch for vector storage, a dedicated LiteLLM gateway **with a PostgreSQL backend for managed LLM access, and an **Ingress controller for secure external traffic management via TLS.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: opensearch
  namespace: docling-factory
  labels:
    app: opensearch
spec:
  replicas: 1
  selector:
    matchLabels:
      app: opensearch
  template:
    metadata:
      labels:
        app: opensearch
    spec:
      containers:
      - name: opensearch
        image: opensearchproject/opensearch:2.11.0
        ports:
        - containerPort: 9200
          name: http
        - containerPort: 9600
          name: performance
        env:
        - name: discovery.type
          value: "single-node"
        - name: OPENSEARCH_JAVA_OPTS
          value: "-Xms512m -Xmx512m"
        - name: DISABLE_SECURITY_PLUGIN
          value: "true"
        - name: DISABLE_INSTALL_DEMO_CONFIG
          value: "true"
        resources:
          requests:
            memory: "1Gi"
            cpu: "500m"
          limits:
            memory: "2Gi"
            cpu: "1000m"
        volumeMounts:
        - name: opensearch-data
          mountPath: /usr/share/opensearch/data
        livenessProbe:
          httpGet:
            path: /_cluster/health
            port: 9200
          initialDelaySeconds: 60
          periodSeconds: 30
          timeoutSeconds: 10
        readinessProbe:
          httpGet:
            path: /_cluster/health
            port: 9200
          initialDelaySeconds: 30
          periodSeconds: 10
          timeoutSeconds: 5
      volumes:
      - name: opensearch-data
        persistentVolumeClaim:
          claimName: opensearch-data-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: opensearch-service
  namespace: docling-factory
  labels:
    app: opensearch
spec:
  type: ClusterIP
  ports:
  - port: 9200
    targetPort: 9200
    protocol: TCP
    name: http
  - port: 9600
    targetPort: 9600
    protocol: TCP
    name: performance
  selector:
    app: opensearch
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: opensearch-data-pvc
  namespace: docling-factory
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: standard

# Made with Bob

Persistent Storage: Robust data management is handled through several Persistent Volume Claims (PVCs), providing up to 50Gi for document output and separate storage for input and logs.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: docling-factory-input-pvc
  namespace: docling-factory
  labels:
    app: docling-factory
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 10Gi
  storageClassName: standard
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: docling-factory-output-pvc
  namespace: docling-factory
  labels:
    app: docling-factory
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 50Gi
  storageClassName: standard
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: docling-factory-logs-pvc
  namespace: docling-factory
  labels:
    app: docling-factory
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  storageClassName: standard

# Made with Bob

GPU Integration: Specialized Kubernetes manifests utilize nodeSelector and https://nvidia.com/gpu resource requests to target nodes with NVIDIA hardware, ensuring high-performance document parsing and layout analysis in cloud environments.
CPU Deployment

# Docling Factory - CPU Version (Optimized Build)
# Multi-stage build with better caching and faster builds

FROM python:3.11-slim as builder

# Set working directory
WORKDIR /app

# Install system dependencies in one layer
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Copy only requirements first for better caching
COPY requirements.txt .

# Install dependencies in stages for better caching
# Stage 1: Install lightweight dependencies first
RUN pip install --no-cache-dir --user \
    numpy>=1.24.0,<2.0.0 \
    pandas>=2.0.0 \
    pillow>=10.0.0 \
    python-docx>=1.1.0 \
    PyPDF2>=3.0.0 \
    python-dateutil>=2.8.2 \
    pathlib>=1.0.1 \
    lxml>=4.9.0 \
    openpyxl>=3.1.0

# Stage 2: Install medium-weight dependencies
RUN pip install --no-cache-dir --user \
    gradio>=4.0.0 \
    streamlit>=1.31.0 \
    plotly>=5.18.0 \
    httpx>=0.24.0 \
    tiktoken>=0.5.0

# Stage 3: Install OpenSearch and LangChain
RUN pip install --no-cache-dir --user \
    opensearch-py>=2.4.0 \
    langchain>=0.1.0 \
    langchain-community>=0.0.20

# Stage 4: Install LLM clients (lightweight)
RUN pip install --no-cache-dir --user \
    ollama>=0.1.0 \
    litellm>=1.0.0

# Stage 5: Install OpenTelemetry (lightweight)
RUN pip install --no-cache-dir --user \
    opentelemetry-api>=1.20.0 \
    opentelemetry-sdk>=1.20.0 \
    opentelemetry-instrumentation>=0.41b0 \
    traceloop-sdk>=0.30.0

# Stage 6: Install Docling (can be slow)
RUN pip install --no-cache-dir --user \
    docling>=2.0.0 \
    docling-core>=2.0.0 \
    docling-parse>=2.0.0 \
    python-xbrl>=1.1.1

# Stage 7: Install CV dependencies (slowest - do last)
RUN pip install --no-cache-dir --user \
    opencv-python-headless>=4.8.0,<5.0.0 \
    scikit-image>=0.21.0 \
    pytesseract>=0.3.10

# Stage 8: Install PyTorch (very slow - separate for better error handling)
RUN pip install --no-cache-dir --user \
    torch>=2.0.0 \
    torchvision>=0.15.0 \
    || echo "PyTorch installation failed, continuing..."

# Stage 9: Install ML dependencies (slow)
RUN pip install --no-cache-dir --user \
    sentence-transformers>=2.2.0 \
    faiss-cpu>=1.7.4 \
    chromadb>=0.4.0 \
    || echo "ML dependencies installation failed, continuing..."

# Stage 10: Install EasyOCR last (slowest)
RUN pip install --no-cache-dir --user \
    easyocr>=1.7.0 \
    || echo "EasyOCR installation failed, continuing..."

# Final stage
FROM python:3.11-slim

# Set working directory
WORKDIR /app

# Install runtime dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    libgomp1 \
    libglib2.0-0 \
    libsm6 \
    libxext6 \
    libxrender-dev \
    libgl1-mesa-glx \
    && rm -rf /var/lib/apt/lists/*

# Copy Python packages from builder
COPY --from=builder /root/.local /root/.local

# Make sure scripts in .local are usable
ENV PATH=/root/.local/bin:$PATH

# Copy application files
COPY docling_parser.py .
COPY app_enhanced.py .
COPY rag_engine.py .
COPY metrics_collector.py .
COPY standalone_dashboard.py .
COPY metrics_dashboard.py .

# Create necessary directories
RUN mkdir -p input output output/figures logs

# Expose Gradio port
EXPOSE 7860

# Set environment variables
ENV GRADIO_SERVER_NAME=0.0.0.0
ENV GRADIO_SERVER_PORT=7860
ENV PYTHONUNBUFFERED=1
ENV OPENSEARCH_HOST=opensearch
ENV OPENSEARCH_PORT=9200
ENV OLLAMA_BASE_URL=http://host.docker.internal:11434
ENV LITELLM_API_BASE=http://litellm:4000
ENV LITELLM_API_KEY=sk-1234

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
    CMD python -c "import requests; requests.get('http://localhost:7860')" || exit 1

# Run the application
CMD ["python", "app_enhanced.py"]

GPU Deployment

# Docling Factory - GPU Version with LiteLLM Support
# Multi-stage build for optimized image size with CUDA support

FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04 as builder

# Set working directory
WORKDIR /app

# Install Python and system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3.11 \
    python3.11-dev \
    python3-pip \
    build-essential \
    git \
    && rm -rf /var/lib/apt/lists/*

# Create symbolic links for python
RUN ln -sf /usr/bin/python3.11 /usr/bin/python && \
    ln -sf /usr/bin/python3.11 /usr/bin/python3

# Copy requirements file
COPY requirements-gpu.txt .

# Install Python dependencies
RUN pip install --no-cache-dir --user -r requirements-gpu.txt

# Final stage
FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04

# Set working directory
WORKDIR /app

# Install Python runtime
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3.11 \
    python3-pip \
    libgomp1 \
    && rm -rf /var/lib/apt/lists/*

# Create symbolic links for python
RUN ln -sf /usr/bin/python3.11 /usr/bin/python && \
    ln -sf /usr/bin/python3.11 /usr/bin/python3

# Copy Python packages from builder
COPY --from=builder /root/.local /root/.local

# Make sure scripts in .local are usable
ENV PATH=/root/.local/bin:$PATH

# Copy application files
COPY docling_parser.py .
COPY app_enhanced.py .
COPY rag_engine.py .
COPY metrics_collector.py .
COPY standalone_dashboard.py .
COPY metrics_dashboard.py .

# Create necessary directories
RUN mkdir -p input output output/figures logs

# Expose Gradio port
EXPOSE 7860

# Set environment variables
ENV GRADIO_SERVER_NAME=0.0.0.0
ENV GRADIO_SERVER_PORT=7860
ENV PYTHONUNBUFFERED=1
ENV CUDA_VISIBLE_DEVICES=0
ENV OPENSEARCH_HOST=opensearch
ENV OPENSEARCH_PORT=9200
ENV OLLAMA_BASE_URL=http://host.docker.internal:11434
ENV LITELLM_API_BASE=http://litellm:4000
ENV LITELLM_API_KEY=sk-1234

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
    CMD python -c "import requests; requests.get('http://localhost:7860')" || exit 1

# Run the application
CMD ["python", "app_enhanced.py"]

apiVersion: apps/v1
kind: Deployment
metadata:
  name: docling-factory-gpu
  namespace: docling-factory
  labels:
    app: docling-factory
    version: gpu
spec:
  replicas: 1
  selector:
    matchLabels:
      app: docling-factory
      version: gpu
  template:
    metadata:
      labels:
        app: docling-factory
        version: gpu
    spec:
      containers:
      - name: docling-factory
        image: docling-factory:gpu-latest
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 7860
          name: http
          protocol: TCP
        envFrom:
        - configMapRef:
            name: docling-factory-config
        env:
        - name: CUDA_VISIBLE_DEVICES
          value: "0"
        resources:
          requests:
            memory: "4Gi"
            cpu: "2000m"
            nvidia.com/gpu: 1
          limits:
            memory: "8Gi"
            cpu: "4000m"
            nvidia.com/gpu: 1
        volumeMounts:
        - name: input-storage
          mountPath: /app/input
        - name: output-storage
          mountPath: /app/output
        - name: logs-storage
          mountPath: /app/logs
        livenessProbe:
          httpGet:
            path: /
            port: 7860
          initialDelaySeconds: 60
          periodSeconds: 30
          timeoutSeconds: 10
          failureThreshold: 3
        readinessProbe:
          httpGet:
            path: /
            port: 7860
          initialDelaySeconds: 30
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 3
      volumes:
      - name: input-storage
        persistentVolumeClaim:
          claimName: docling-factory-input-pvc
      - name: output-storage
        persistentVolumeClaim:
          claimName: docling-factory-output-pvc
      - name: logs-storage
        persistentVolumeClaim:
          claimName: docling-factory-logs-pvc
      nodeSelector:
        accelerator: nvidia-gpu
      tolerations:
      - key: nvidia.com/gpu
        operator: Exists
        effect: NoSchedule

# Made with Bob

The “End of Level 1” Log

So, here I am — about two months into this rabbit hole, and I’m still standing, mostly thanks to the digital wizardry of IBM Bob. Is the Docling Factory “finished”? In the words of every dev ever: Hell no. I’m currently in that glorious “it works on my machine” phase, but the quest log is still overflowing. I’ve got to stress-test the GPU until the fans scream, feed it files so large they have their own gravity, and ensure the unit tests cover more than just the “happy path”. I’m also dreaming of a universal Cloud Object Storage (COS) implementation to make file repo handling truly elite. This is just a fragment of the “to-do” list currently living rent-free in my brain. The code is out there on GitHub, and frankly, I’d love some co-op players for this raid — carrying this entire multimodal stack on my own two shoulders is getting a bit “Atlas-tier” heavy. Pull requests are open, the coffee is brewing, and the evolution has only just begun!

Thanks for reading 🤠

Mamba vs. Transformers: Architecture Comparison

Alain Airom (Ayrom) — Thu, 30 Apr 2026 11:58:36 +0000

My latest studies and understandings of Mamba versus Transformers!

The Core Architectures: Transformers and Mamba

Transformers operate on the principle of Self-Attention, which allows the model to process all tokens in a sequence simultaneously to understand their relationships. By calculating pairwise interactions between every word in a sentence, the model can capture complex, long-range dependencies with high precision. However, this comprehensive “look-at-everything” approach comes with a quadratic computational cost (O(L2)), meaning that as the input length increases, the memory and processing power required grow exponentially. This architecture is the gold standard for tasks requiring deep reasoning and precise data retrieval, though it often struggles with efficiency when handling extremely long documents or real-time streaming.

Mamba introduces a more efficient alternative based on Selective State Space Models (SSMs), which process data linearly (O(L)) rather than quadratically. Unlike the Transformer’s massive memory cache, Mamba utilizes a fixed-size hidden state that acts as a compressed version of the entire preceding sequence, allowing it to maintain performance even as the context grows. Its “selective” mechanism enables the model to dynamically decide which information is important to keep and what can be discarded, effectively solving the traditional memory bottlenecks of older recurrent models. This makes Mamba particularly powerful for high-throughput applications, long-context analysis, and environments where fast, constant-time inference is a priority.

Mamba vs. Traditional Transformers
The primary difference between Mamba and traditional Transformers lies in how they process sequence data. While Transformers rely on the Self-Attention mechanism to “attend” to all previous tokens simultaneously, Mamba utilizes S*elective State Space Models (SSMs)* to maintain a compressed, evolving internal state (Mukhammadiev, 2026; IBM, 2025).

Key Architectural Differences

| Feature             | Traditional Transformer                                     | Mamba (Selective SSM)                                      |
| ------------------- | ----------------------------------------------------------- | ---------------------------------------------------------- |
| **Core Mechanism**  | Self-Attention (every token looks at every other token)     | Selective State Updates (recurrent internal state)         |
| **Complexity**      | **Quadratic** *O*(*L*2)—cost quadruples if sequence doubles | **Linear** *O*(*L*)—cost scales proportionally with length |
| **Memory**          | High (grows with context due to KV Cache)                   | Low (fixed-size "hidden state")                            |
| **Best For**        | Precise retrieval and few-shot reasoning                    | Long context, real-time streaming, and high throughput     |
| **Inference Speed** | Slower as sequences get longer                              | Extremely fast and constant per-token latency              |

Traditional Transformers

Transformers process an entire sequence at once during training. However, during generation (inference), they must store a KV Cache (Key-Value Cache) of all previous tokens to avoid recomputing them, which leads to massive memory consumption for long documents (Mukhammadiev, 2026; Duhan, 2026).

Conceptual Code (Simplified Self-Attention):

import torch
import torch.nn.functional as F

def transformer_attention(query, key, value):
    # query, key, value shape: [batch, seq_len, dim]
    # 1. Compute scores (Every token vs Every token)
    scores = torch.matmul(query, key.transpose(-2, -1)) / (query.size(-1)**0.5)

    # 2. Apply Softmax (Quadratic memory/compute)
    weights = F.softmax(scores, dim=-1)

    # 3. Weighted sum of values
    return torch.matmul(weights, value)

Mamba (Selective SSM)

Mamba acts more like a “smart” Recurrent Neural Network (RNN). It doesn’t look back at every token; instead, it updates a fixed-size hidden state that acts as a compressed memory (Duhan, 2026; IBM, 2025). Mamba’s “Selection” mechanism allows it to decide which information to keep or discard based on the current input, solving the “forgetting” problem of older RNNs (Mukhammadiev, 2026; OpenReview).

Conceptual Code (Simplified SSM Update):

def mamba_ssm_step(x_t, hidden_state, A, B, C, delta):
    # x_t: current token input
    # 1. Discretization (making continuous math digital)
    # delta is input-dependent, allowing "selection"
    dA = torch.exp(delta * A)
    dB = (delta * B)

    # 2. Update the internal "memory" (Hidden State)
    # This is Linear O(L) because it's a step-by-step update
    new_hidden = dA * hidden_state + dB * x_t

    # 3. Generate output
    y_t = C * new_hidden
    return y_t, new_hidden

Why Mamba Matters?

In 2026, Mamba-3 has emerged as a production-ready alternative to Transformers, offering up to 5x higher throughput for long-document tasks (Duhan, 2026; VentureBeat, 2026). While Transformers still excel at exact data retrieval (like a database), Mamba is superior for “inference-first” applications where speed and memory efficiency are critical (Mukhammadiev, 2026; Duhan, 2026).

IBM and Mamba!

As of April 2026, IBM has integrated Mamba architecture into its flagship Granite family and specialized Biomedical Foundation Models to improve efficiency and performance for long-sequence tasks.

IBM Granite 4.0 & 4.1 Family

IBM introduced a Hybrid Mamba-2/Transformer architecture in its Granite 4.0 and 4.1 models. This design combines the efficient state-tracking of Mamba with the precision of standard Transformers, leading to a 70% reduction in GPU memory needs and 2x faster inference.

> Disclaimer: based on my own research!

Key Granite models using this architecture include:

Granite 4.1 LLMs: Granite 4.1 models use a decoder-only dense transformer architecture. The core design choices include Grouped Query Attention (GQA), Rotary Position Embeddings (RoPE), SwiGLU activations, RMSNorm, and shared input/output embeddings. (https://huggingface.co/blog/ibm-granite/granite-4-1)
Granite-H-Small: A 32B parameter model (9B active) designed for heavy-duty enterprise tasks.
Granite-H-Tiny: A 7B parameter model (1B active) optimized for low-latency, high-volume tasks.
Granite-H-Micro: A 3B parameter dense model tailored for local and edge deployments.
Granite-H-Nano: Compact variants (350M and 1B parameters) designed for on-device applications.

IBM Research Biomedical Models

IBM Research utilizes Mamba blocks in specialized models to handle the linear complexity required for genomics and molecular data.

biomed.omics.bl.sm.ma-ted-458m: A multi-domain, sequence-based model trained on biologics, small molecules, and single-cell RNA-seq data.
Bamba: A research hybrid model developed to fuse SSM efficiency with Transformer-level accuracy for large-scale scientific modeling.
Genomics Foundation Models: IBM has analyzed Mamba’s performance in processing over 1 million tokens in genomic sequences, outperforming traditional baselines

Model Comparison Summary

| Model Series     | Type                     | Primary Benefit                                              |
| ---------------- | ------------------------ | ------------------------------------------------------------ |
| **Granite-H**    | Hybrid Mamba/Transformer | Reduces GPU memory by 70% and doubles inference speed.       |
| **Biomed Omics** | Specialized SSM          | Scales linearly to handle extremely long DNA and protein sequences. |
| **Bamba**        | Research Hybrid          | Combines Transformer accuracy with Mamba's linear scaling for scientific discovery. |

That’s a wrap! 🫔

Links, References and Citations

OpenReview: Mamba — Linear-Time Sequence Modeling with Selective State Spaces: https://openreview.net/forum?id=AL1fq05o7H (by Tri Dao and Albert Gu introducing the Selective SSM architecture.)
What is a Mamba Model: https://www.ibm.com/think/topics/mamba-model
Mamba vs Transformer: The Real Shift in AI Architecture (2026): https://medium.com/@uzbrainai/mamba-vs-transformer-the-real-shift-in-ai-architecture-2026-bf758ba278ec (Mukhammadiev, 2026)
New Mamba-3 AI Model Beats Transformers by 4%, Runs 7x Faster: https://winbuzzer.com/2026/03/18/open-source-mamba-3-arrives-to-surpass-transformer-xcxwbn/
The Architecture Wars Are Back: Mamba-3 Challenges Transformers While Nvidia Fights to Keep Them Alive: https://dev.to/taskconcierge/the-architecture-wars-are-back-mamba-3-challenges-transformers-while-nvidia-fights-to-keep-them-fag
Open source Mamba 3 arrives to surpass Transformer architecture with nearly 4% improved language modeling, reduced latency: https://venturebeat.com/technology/open-source-mamba-3-arrives-to-surpass-transformer-architecture-with-nearly
Mamba-3 vs Transformers: Which Architecture Should You Build On?: https://medium.com/@harshduhan/mamba-3-vs-transformers-which-architecture-should-you-build-on-f24cd52b482f

No More Automation from Scratch: Automate and Build Your Terraform with Draw.io Diagrams

Alain Airom (Ayrom) — Tue, 28 Apr 2026 12:44:46 +0000

Creating Terraform Scripts from Draw.io XML Files!

Introduction

The concept and the idea originated from a realization that drawings from open-source tools, such as Draw.io, are essentially structured XML files. If the diagram explicitly maps out an infrastructure architecture, it would be logical to analyze that XML file and programmatically generate corresponding Terraform scripts.

> Disclaimer: note that this application is currently in its alpha stage; as an early-access release, it requires more rigorous, “bulletproof” testing and further functional enhancements before it reaches full maturity. This tool marks the first in a planned series of automation utilities I am developing to significantly accelerate my personal productivity and streamline technical workflows.

A word on the external tool used: Draw.io

The core of this application’s utility is its deep integration with Draw.io, a premier open-source diagramming tool. Rather than forcing users into a proprietary design environment, the generator leverages Draw.io’s flexible, web-based interface and its extensive library of cloud architecture shapes. By treating the exported Draw.io XML as a structured data source, the application can precisely map visual components and their interconnections to valid Terraform resource blocks. This heavy reliance on an open-source standard ensures that users can design their infrastructure using a familiar, free, and highly accessible tool, while the backend handles the complex translation from a visual drawing to production-ready code.

Terraform Script Generator: A Diagram-to-Code Pipeline

The Terraform Script Generator is a web-based utility designed to streamline the translation of cloud infrastructure diagrams, specifically those created in Draw.io, into deployable Terraform configurations. This automation bridges the gap between architectural planning and infrastructure implementation, particularly for Cloud platforms like IBM (but not only), but adaptable to other platforms as well. The generator employs a client-server architecture, utilizing a user-friendly frontend to receive design inputs and a robust backend to handle the analytical heavy lifting.

terraform-builder/
│
├── backend/                      # Backend Python modules
│   ├── app.py                   # Flask API server
│   ├── drawio_parser.py         # XML parser for Draw.io
│   └── terraform_generator.py   # Terraform code generator
│
├── frontend/                     # Frontend web files
│   ├── index.html               # Main UI
│   ├── styles.css               # Styling
│   └── app.js                   # Client-side logic
│
├── k8s/                         # Kubernetes deployment files
│   ├── deployment.yaml          # Deployment and Service manifests
│   ├── configmap.yaml           # Application configuration
│   └── README.md                # Kubernetes deployment guide
│
├── Docs/                        # Documentation
│   └── Architecture.md          # This file
│
├── scripts/                     # Utility scripts
│   ├── start.sh                # Start application
│   ├── stop.sh                 # Stop application
│   └── validate_terraform.py   # Terraform validation
│
├── _diagrams/                   # Example diagrams
│   └── d1.drawio               # Sample IBM Cloud diagram
│
├── _images/                     # Project images
├── _sources/                    # Reference sources
│
├── Dockerfile                   # Docker image definition
├── requirements.txt             # Python dependencies
├── .gitignore                  # Git ignore rules
└── README.md                   # Project documentation

The Backend: Analytical Engine with Flask and Python

At the heart of the system is a Python backend built with the Flask web framework. This application is responsible for orchestrating the overall process, from serving the main user interface to exposing REST API endpoints for diagram parsing and code generation. It integrates two key internal modules: DrawioParser and TerraformGenerator. The application logic is designed for extensibility, capable of handling complex diagrams and multi-stage processing, supporting features like file uploading, health checks, and state management via JSON for multi-step workflows.

# app.py - Main Flask application for the Terraform Builder
"""
Flask Backend for Terraform Builder Application
Provides API endpoints for parsing Draw.io diagrams and generating Terraform code
"""
from flask import Flask, request, jsonify, send_from_directory
from flask_cors import CORS
import os
from drawio_parser import DrawioParser
from terraform_generator import TerraformGenerator

app = Flask(__name__, static_folder='../frontend', static_url_path='')
CORS(app)

# Initialize parsers and generators
parser = DrawioParser()
generator = TerraformGenerator()


@app.route('/')
def index():
    """Serve the main application page"""
    return send_from_directory(app.static_folder, 'index.html')


@app.route('/api/parse', methods=['POST'])
def parse_diagram():
    """Parse a Draw.io diagram and return components"""
    try:
        if 'file' in request.files:
            # Handle file upload
            file = request.files['file']
            if file.filename == '':
                return jsonify({'error': 'No file selected'}), 400

            # Save temporarily and parse
            temp_path = '/tmp/temp_diagram.drawio'
            file.save(temp_path)

            result = parser.parse_file(temp_path)
            os.remove(temp_path)

        elif 'content' in request.json:
            # Handle XML content
            content = request.json['content']
            result = parser.parse_content(content)
        else:
            return jsonify({'error': 'No diagram data provided'}), 400

        return jsonify({
            'success': True,
            'components': result['components'],
            'connections': result['connections'],
            'summary': parser.get_resource_summary()
        })

    except Exception as e:
        return jsonify({'error': str(e)}), 500


@app.route('/api/generate', methods=['POST'])
def generate_terraform():
    """Generate Terraform code from parsed components"""
    try:
        data = request.json
        components = data.get('components', [])
        provider = data.get('provider', 'ibm')

        if not components:
            return jsonify({'error': 'No components provided'}), 400

        # Create generator with selected provider
        gen = TerraformGenerator(provider=provider)

        # Generate Terraform files
        terraform_files = gen.generate_from_components(components)

        return jsonify({
            'success': True,
            'files': terraform_files
        })

    except Exception as e:
        return jsonify({'error': str(e)}), 500


@app.route('/api/parse-and-generate', methods=['POST'])
def parse_and_generate():
    """Parse diagram and generate Terraform code in one step"""
    try:
        provider = 'ibm'  # Default provider
        custom_provider_url = None

        if 'file' in request.files:
            # Handle file upload
            file = request.files['file']
            if file.filename == '':
                return jsonify({'error': 'No file selected'}), 400

            # Save temporarily and parse
            temp_path = '/tmp/temp_diagram.drawio'
            file.save(temp_path)

            result = parser.parse_file(temp_path)
            os.remove(temp_path)

            # Get provider from form data if available
            provider = request.form.get('provider', 'ibm')
            custom_provider_url = request.form.get('custom_provider_url')

        elif 'content' in request.json:
            # Handle XML content
            content = request.json['content']
            provider = request.json.get('provider', 'ibm')
            custom_provider_url = request.json.get('custom_provider_url')
            result = parser.parse_content(content)
        else:
            return jsonify({'error': 'No diagram data provided'}), 400

        # Create generator with selected provider and custom URL if provided
        gen = TerraformGenerator(provider=provider, custom_provider_url=custom_provider_url)

        # Generate Terraform files
        terraform_files = gen.generate_from_components(result['components'])

        response_data = {
            'success': True,
            'components': result['components'],
            'connections': result['connections'],
            'summary': parser.get_resource_summary(),
            'terraform': terraform_files,
            'provider': provider
        }

        # Add custom provider info if used
        if custom_provider_url and gen.custom_provider_config:
            response_data['custom_provider'] = gen.custom_provider_config

        # Add warning if IBM components detected with non-IBM provider
        if provider != 'ibm' and hasattr(gen, 'skipped_resources') and gen.skipped_resources:
            response_data['warning'] = {
                'message': f'This diagram contains {len(gen.skipped_resources)} IBM Cloud-specific component(s) that were not generated for the {provider.upper()} provider.',
                'suggestion': 'Consider selecting "IBM Cloud" as the provider to generate these resources.',
                'skipped_count': len(gen.skipped_resources)
            }

        return jsonify(response_data)

    except Exception as e:
        return jsonify({'error': str(e)}), 500


@app.route('/api/health', methods=['GET'])
def health_check():
    """Health check endpoint"""
    return jsonify({
        'status': 'healthy',
        'service': 'terraform-builder-api'
    })


@app.route('/api/diagram-preview', methods=['POST'])
def diagram_preview():
    """Generate a preview URL for the diagram"""
    try:
        data = request.json
        content = data.get('content', '')

        if not content:
            return jsonify({'error': 'No diagram content provided'}), 400

        # Return the content for client-side rendering
        return jsonify({
            'success': True,
            'content': content,
            'preview_available': True
        })

    except Exception as e:
        return jsonify({'error': str(e)}), 500


@app.route('/api/save-files', methods=['POST'])
def save_files():
    """Save generated Terraform files to timestamped output folder"""
    try:
        from datetime import datetime
        import shutil

        data = request.json
        files = data.get('files', {})
        diagram_name = data.get('diagram_name', 'diagram')

        if not files:
            return jsonify({'error': 'No files provided'}), 400

        # Remove file extension from diagram name
        diagram_name = diagram_name.replace('.drawio', '').replace('.xml', '')

        # Create timestamp
        timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')

        # Create output directory structure
        output_base = 'output'
        output_dir = os.path.join(output_base, f"{diagram_name}_{timestamp}")

        # Create directory if it doesn't exist
        os.makedirs(output_dir, exist_ok=True)

        # Save each file
        saved_files = []
        for filename, content in files.items():
            file_path = os.path.join(output_dir, filename)
            with open(file_path, 'w') as f:
                f.write(content)
            saved_files.append(file_path)

        return jsonify({
            'success': True,
            'output_dir': output_dir,
            'files': saved_files,
            'message': f'Files saved to {output_dir}'
        })

    except Exception as e:
        return jsonify({'error': str(e)}), 500


@app.route('/api/save-and-zip-files', methods=['POST'])
def save_and_zip_files():
    """Save generated Terraform files to timestamped output folder and return as ZIP"""
    try:
        from datetime import datetime
        import shutil
        import zipfile
        from io import BytesIO
        from flask import send_file

        data = request.json
        files = data.get('files', {})
        diagram_name = data.get('diagram_name', 'diagram')

        if not files:
            return jsonify({'error': 'No files provided'}), 400

        # Remove file extension from diagram name
        diagram_name = diagram_name.replace('.drawio', '').replace('.xml', '')

        # Create timestamp
        timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
        folder_name = f"{diagram_name}_{timestamp}"

        # Create output directory structure
        output_base = 'output'
        output_dir = os.path.join(output_base, folder_name)

        # Create directory if it doesn't exist
        os.makedirs(output_dir, exist_ok=True)

        # Save each file to disk
        for filename, content in files.items():
            file_path = os.path.join(output_dir, filename)
            with open(file_path, 'w') as f:
                f.write(content)

        # Create ZIP file in memory
        zip_buffer = BytesIO()
        with zipfile.ZipFile(zip_buffer, 'w', zipfile.ZIP_DEFLATED) as zip_file:
            for filename, content in files.items():
                # Add files to ZIP with folder structure
                zip_file.writestr(f"{folder_name}/{filename}", content)

        zip_buffer.seek(0)
        zip_name = f"{folder_name}.zip"

        # Create response with ZIP file
        return send_file(
            zip_buffer,
            mimetype='application/zip',
            as_attachment=True,
            download_name=zip_name
        )

    except Exception as e:
        return jsonify({'error': str(e)}), 500


if __name__ == '__main__':
    # Run the Flask app
    port = int(os.environ.get('PORT', 5002))
    debug = os.environ.get('DEBUG', 'True').lower() == 'true'

    print(f"Starting Terraform Builder API on port {port}")
    print(f"Debug mode: {debug}")

    app.run(host='0.0.0.0', port=port, debug=debug)

# Made with Bob

Diagram Interpretation: Parsing the Draw.io XML

Draw.io architecture diagrams are essentially saved as structured XML files. The backend utilizes the standard xml.etree.ElementTree library to read this XML and extract the critical components. It parses the nested mxCell elements to identify individual cloud resources based on specific, predefined shape patterns and styles (e.g., IBM Cloud shapes). This interpreter doesn't just list components; it also detects connections between them to understand the relationships and generate resource summaries, laying the foundation for accurate script generation.

# drawio_parser.py - Parser for Draw.io XML files containing IBM Cloud diagrams
"""
Draw.io XML Parser for IBM Cloud Diagrams
Parses Draw.io XML files and extracts IBM Cloud components
"""
import xml.etree.ElementTree as ET
from typing import Dict, List, Any


class DrawioParser:
    """Parser for Draw.io XML files containing cloud diagrams"""

    # Mapping of Draw.io shapes to generic resource types
    # These will be converted to provider-specific resources by the generator
    CLOUD_SHAPES = {
        # Core Cloud resources
        'mxgraph.ibm_cloud.ibm-cloud': 'resource_group',
        'mxgraph.ibm.box;prType=cloud': 'resource_group',

        # VPC and Networking
        'mxgraph.ibm_cloud.ibm-cloud--vpc': 'vpc',
        'mxgraph.ibm.box;prType=vpc': 'vpc',
        'mxgraph.ibm.vpc': 'vpc',
        'mxgraph.ibm_cloud.ibm-cloud--subnets': 'subnet',
        'mxgraph.ibm_cloud.floating-ip': 'floating_ip',
        'mxgraph.ibm_cloud.load-balancer--vpc': 'load_balancer',
        'mxgraph.ibm_cloud.network--public': 'public_gateway',

        # Compute
        'mxgraph.ibm_cloud.server--proxy': 'compute_instance',
        'mxgraph.ibm_cloud.application--web': 'app_service',

        # Storage and Databases
        'mxgraph.ibm_cloud.data--base': 'database',

        # Watson Services (IBM-specific, will be skipped for other providers)
        'mxgraph.ibm_cloud.ibm-watsonx--orchestrate': 'watson_service',
        'mxgraph.ibm_cloud.watsonx-governance': 'watson_service',
        'mxgraph.ibm_cloud.watsonx-ai': 'watson_service',

        # Zones (for organizational purposes)
        'mxgraph.ibm.box;prType=zone': 'zone',
    }

    # Service names for IBM Cloud resources
    SERVICE_NAMES = {
        'watsonx--orchestrate': 'watsonx-orchestrate',
        'watsonx-governance': 'watsonx-governance',
        'watsonx-ai': 'watsonx-ai',
    }

    def __init__(self):
        self.components = []
        self.connections = []

    def parse_file(self, file_path: str) -> Dict[str, Any]:
        """Parse a Draw.io XML file and extract IBM Cloud components"""
        try:
            tree = ET.parse(file_path)
            root = tree.getroot()

            # Find all mxCell elements
            for diagram in root.findall('.//diagram'):
                model = diagram.find('.//mxGraphModel')
                if model is not None:
                    self._parse_model(model)

            return {
                'components': self.components,
                'connections': self.connections
            }
        except Exception as e:
            raise Exception(f"Error parsing Draw.io file: {str(e)}")

    def parse_content(self, xml_content: str) -> Dict[str, Any]:
        """Parse Draw.io XML content string"""
        try:
            # Log the first 200 characters for debugging
            print(f"[DEBUG] Received XML content (first 200 chars): {xml_content[:200]}")
            print(f"[DEBUG] XML content length: {len(xml_content)}")
            print(f"[DEBUG] XML content type: {type(xml_content)}")

            # Validate content
            if not xml_content or not xml_content.strip():
                raise Exception("Empty XML content received")

            if not xml_content.strip().startswith('<'):
                raise Exception(f"Not a diagram file (error on line 1 at column 1: Start tag expected, '<' not found). Received: {xml_content[:100]}")

            root = ET.fromstring(xml_content)

            # Find all mxCell elements
            for diagram in root.findall('.//diagram'):
                model = diagram.find('.//mxGraphModel')
                if model is not None:
                    self._parse_model(model)

            return {
                'components': self.components,
                'connections': self.connections
            }
        except ET.ParseError as e:
            print(f"[ERROR] XML Parse Error: {str(e)}")
            print(f"[ERROR] Content that failed: {xml_content[:500]}")
            raise Exception(f"Not a diagram file (error on line 1 at column 1: Start tag expected, '<' not found)")
        except Exception as e:
            print(f"[ERROR] General parsing error: {str(e)}")
            raise Exception(f"Error parsing Draw.io content: {str(e)}")

    def _parse_model(self, model: ET.Element):
        """Parse the mxGraphModel element"""
        root_element = model.find('.//root')
        if root_element is None:
            return

        for cell in root_element.findall('.//mxCell'):
            self._parse_cell(cell)

    def _parse_cell(self, cell: ET.Element):
        """Parse individual mxCell elements"""
        cell_id = cell.get('id')
        if not cell_id:
            return

        value = cell.get('value', '')
        style = cell.get('style', '')

        # Check if this is a cloud component
        for shape_key, resource_type in self.CLOUD_SHAPES.items():
            if shape_key in style:
                component = self._extract_component(cell_id, value, style, shape_key, resource_type)
                if component:
                    self.components.append(component)
                break

        # Check for connections (edges)
        source = cell.get('source')
        target = cell.get('target')
        if source and target:
            self.connections.append({
                'source': source,
                'target': target,
                'id': cell_id
            })

    def _extract_component(self, cell_id: str, value: str, style: str, shape_key: str, resource_type: str) -> Dict[str, Any]:
        """Extract component information from a cell"""
        # Determine the service name
        service_name = None
        for key, service in self.SERVICE_NAMES.items():
            if key in value.lower() or key in shape_key:
                service_name = service
                break

        # Extract geometry if available
        geometry = self._extract_geometry(style)

        component = {
            'id': cell_id,
            'name': value.strip() if value else self._generate_name(shape_key),
            'type': resource_type,
            'shape': shape_key,
            'service': service_name,
            'geometry': geometry
        }

        return component

    def _extract_geometry(self, style: str) -> Dict[str, Any]:
        """Extract geometry information from style string"""
        geometry = {}
        # This is a simplified extraction - can be enhanced
        return geometry

    def _generate_name(self, shape_key: str) -> str:
        """Generate a default name based on the shape type"""
        # Extract the last part of the shape key
        parts = shape_key.split('.')
        if len(parts) > 0:
            name = parts[-1].replace('-', '_').replace('__', '_')
            return name
        return 'unnamed_resource'

    def get_resource_summary(self) -> Dict[str, int]:
        """Get a summary of resources by type"""
        summary = {}
        for component in self.components:
            resource_type = component['type']
            summary[resource_type] = summary.get(resource_type, 0) + 1
        return summary

# Made with Bob

Code Generation: Turning Components into Terraform

Once the diagrams are decoded into component and connection lists, the backend initiates the script generation phase. It programmatically creates three core Terraform configuration files: main.tf for main resources, variables.tf for parameterization, and providers.tf for provider definitions. This process involves sophisticated logic to map Draw.io shapes to corresponding Terraform resource blocks, sanitize names, manage variables, and format the output according to the HashiCorp Configuration Language (HCL). The system is built for modularity, allowing it to generate standardized code for various resource types and cloud providers.

# terraform_generator.py - Generates Terraform code from parsed diagrams
"""
Terraform Code Generator for IBM Cloud Resources
Generates Terraform configuration files from parsed Draw.io diagrams
"""
from typing import Dict, List, Any
import json


class TerraformGenerator:
    """Generates Terraform configuration for multiple cloud providers"""

    # Resource type mappings: generic type -> provider-specific resource type
    RESOURCE_MAPPINGS = {
        'vpc': {
            'ibm': 'ibm_is_vpc',
            'aws': 'aws_vpc',
            'google': 'google_compute_network',
            'azure': 'azurerm_virtual_network',
            'kubernetes': None  # K8s doesn't have VPC concept
        },
        'subnet': {
            'ibm': 'ibm_is_subnet',
            'aws': 'aws_subnet',
            'google': 'google_compute_subnetwork',
            'azure': 'azurerm_subnet',
            'kubernetes': None
        },
        'compute_instance': {
            'ibm': 'ibm_is_instance',
            'aws': 'aws_instance',
            'google': 'google_compute_instance',
            'azure': 'azurerm_virtual_machine',
            'kubernetes': 'kubernetes_deployment'
        },
        'load_balancer': {
            'ibm': 'ibm_is_lb',
            'aws': 'aws_lb',
            'google': 'google_compute_forwarding_rule',
            'azure': 'azurerm_lb',
            'kubernetes': 'kubernetes_service'
        },
        'database': {
            'ibm': 'ibm_database',
            'aws': 'aws_db_instance',
            'google': 'google_sql_database_instance',
            'azure': 'azurerm_postgresql_server',
            'kubernetes': 'kubernetes_stateful_set'
        },
        'resource_group': {
            'ibm': 'ibm_resource_group',
            'aws': None,  # AWS uses tags instead
            'google': 'google_project',
            'azure': 'azurerm_resource_group',
            'kubernetes': 'kubernetes_namespace'
        },
        'floating_ip': {
            'ibm': 'ibm_is_floating_ip',
            'aws': 'aws_eip',
            'google': 'google_compute_address',
            'azure': 'azurerm_public_ip',
            'kubernetes': None
        },
        'public_gateway': {
            'ibm': 'ibm_is_public_gateway',
            'aws': 'aws_nat_gateway',
            'google': 'google_compute_router_nat',
            'azure': 'azurerm_nat_gateway',
            'kubernetes': None
        },
        'app_service': {
            'ibm': 'ibm_resource_instance',
            'aws': 'aws_elastic_beanstalk_application',
            'google': 'google_app_engine_application',
            'azure': 'azurerm_app_service',
            'kubernetes': 'kubernetes_deployment'
        },
        'watson_service': {
            'ibm': 'ibm_resource_instance',
            'aws': None,  # AWS doesn't have Watson equivalent
            'google': None,  # Google doesn't have Watson equivalent
            'azure': None,  # Azure doesn't have Watson equivalent
            'kubernetes': None
        },
        'zone': {
            'ibm': None,  # Organizational only
            'aws': None,
            'google': 'google_compute_zone',
            'azure': None,
            'kubernetes': None
        }
    }

    # Provider configurations
    PROVIDER_CONFIGS = {
        'ibm': {
            'source': 'IBM-Cloud/ibm',
            'version': '>= 1.60.0',
            'docs': 'https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs'
        },
        'azure': {
            'source': 'hashicorp/azurerm',
            'version': '>= 3.0.0',
            'docs': 'https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs'
        },
        'google': {
            'source': 'hashicorp/google',
            'version': '>= 5.0.0',
            'docs': 'https://registry.terraform.io/providers/hashicorp/google/latest/docs'
        },
        'aws': {
            'source': 'hashicorp/aws',
            'version': '>= 5.0.0',
            'docs': 'https://registry.terraform.io/providers/hashicorp/aws/latest/docs'
        },
        'kubernetes': {
            'source': 'hashicorp/kubernetes',
            'version': '>= 2.0.0',
            'docs': 'https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs'
        },
        'terraform': {
            'source': 'hashicorp/tfe',
            'version': '>= 0.50.0',
            'docs': 'https://registry.terraform.io/providers/hashicorp/tfe/latest/docs'
        },
        'instana': {
            'source': 'instana/instana',
            'version': '>= 3.0.0',
            'docs': 'https://registry.terraform.io/providers/instana/instana/latest/docs'
        },
        'vault': {
            'source': 'hashicorp/vault',
            'version': '>= 4.0.0',
            'docs': 'https://registry.terraform.io/providers/hashicorp/vault/latest/docs'
        },
        'turbonomic': {
            'source': 'IBM/turbonomic',
            'version': '>= 1.0.0',
            'docs': 'https://registry.terraform.io/providers/IBM/turbonomic/latest/docs'
        }
    }

    def __init__(self, provider='ibm', custom_provider_url=None):
        self.provider = provider
        self.custom_provider_url = custom_provider_url
        self.custom_provider_config = None

        # If custom provider URL is provided, parse it
        if custom_provider_url and provider == 'other':
            self.custom_provider_config = self._parse_custom_provider_url(custom_provider_url)
            if self.custom_provider_config:
                self.provider = self.custom_provider_config['name']

        self.resources = []
        self.variables = {}
        self.providers = {}

    def _parse_custom_provider_url(self, url: str) -> Dict[str, str] | None:
        """Parse a GitHub provider URL and extract provider information

        Expected format: https://github.com/{org}/{repo}
        Where repo is typically: terraform-provider-{name}

        Returns:
            Dict with 'name', 'source', 'version', and 'docs' keys
        """
        import re

        # Match GitHub URL pattern
        pattern = r'https://github\.com/([\w-]+)/(terraform-provider-([\w-]+))'
        match = re.match(pattern, url)

        if not match:
            return None

        org = match.group(1)
        repo = match.group(2)
        provider_name = match.group(3)

        # Build provider configuration
        return {
            'name': provider_name,
            'source': f'{org}/{provider_name}',
            'version': '>= 1.0.0',  # Default version constraint
            'docs': f'https://registry.terraform.io/providers/{org}/{provider_name}/latest/docs',
            'github_url': url
        }

    def generate_from_components(self, components: List[Dict[str, Any]]) -> Dict[str, str]:
        """Generate Terraform files from parsed components"""
        self.resources = []
        self.variables = {}

        # Process each component
        for idx, component in enumerate(components):
            resource = self._generate_resource(component, idx)
            if resource:
                self.resources.append(resource)

        # Generate the three required files
        main_tf = self._generate_main_tf()
        variables_tf = self._generate_variables_tf()
        providers_tf = self._generate_providers_tf()

        return {
            'main.tf': main_tf,
            'variables.tf': variables_tf,
            'providers.tf': providers_tf
        }

    def _generate_resource(self, component: Dict[str, Any], idx: int) -> Dict[str, Any] | None:
        """Generate a Terraform resource from a component"""
        generic_type = component.get('type')  # Generic type from parser
        name = component.get('name', f'resource_{idx}')
        service = component.get('service')

        # Sanitize name for Terraform
        tf_name = self._sanitize_name(name)

        # Get provider-specific resource type from mapping
        if generic_type not in self.RESOURCE_MAPPINGS:
            return None

        provider_resource_type = self.RESOURCE_MAPPINGS[generic_type].get(self.provider)

        # If this resource type is not supported by the provider, skip it
        if provider_resource_type is None:
            if not hasattr(self, 'skipped_resources'):
                self.skipped_resources = []
            self.skipped_resources.append({
                'name': name,
                'type': generic_type,
                'reason': f'Not supported by {self.provider} provider'
            })
            return None

        # Generate provider-specific resource based on generic type
        if generic_type == 'vpc':
            return self._generate_vpc_resource_multi(tf_name, name, provider_resource_type)
        elif generic_type == 'subnet':
            return self._generate_subnet_resource(tf_name, name, provider_resource_type)
        elif generic_type == 'compute_instance':
            return self._generate_compute_resource(tf_name, name, provider_resource_type)
        elif generic_type == 'load_balancer':
            return self._generate_load_balancer_resource(tf_name, name, provider_resource_type)
        elif generic_type == 'database':
            return self._generate_database_resource(tf_name, name, provider_resource_type)
        elif generic_type == 'resource_group':
            return self._generate_resource_group_multi(tf_name, name, provider_resource_type)
        elif generic_type == 'floating_ip':
            return self._generate_floating_ip_resource(tf_name, name, provider_resource_type)
        elif generic_type == 'public_gateway':
            return self._generate_gateway_resource(tf_name, name, provider_resource_type)
        elif generic_type == 'app_service':
            return self._generate_app_service_resource(tf_name, name, provider_resource_type)
        elif generic_type == 'watson_service':
            return self._generate_watson_service_resource(tf_name, name, service or '', provider_resource_type)

        return None

    def _generate_vpc_resource(self, tf_name: str, display_name: str) -> Dict[str, Any]:
        """Generate VPC resource configuration"""
        self.variables[f'{tf_name}_name'] = {
            'description': f'Name for the {display_name} VPC',
            'type': 'string',
            'default': display_name
        }

        return {
            'type': 'ibm_is_vpc',
            'name': tf_name,
            'config': {
                'name': f'var.{tf_name}_name',
                'resource_group': 'var.resource_group_id',
                'tags': ['var.tags']
            }
        }

    def _generate_resource_instance(self, tf_name: str, display_name: str, service: str) -> Dict[str, Any]:
        """Generate resource instance configuration for Watson services"""
        if not service:
            service = 'watsonx-ai'

        # Map service names to IBM Cloud service names
        service_map = {
            'watsonx-orchestrate': 'watsonx-orchestrate',
            'watsonx-governance': 'watsonx-governance',
            'watsonx-ai': 'watsonx-ai'
        }

        service_name = service_map.get(service, service)

        self.variables[f'{tf_name}_name'] = {
            'description': f'Name for the {display_name} instance',
            'type': 'string',
            'default': display_name
        }

        self.variables[f'{tf_name}_plan'] = {
            'description': f'Service plan for {display_name}',
            'type': 'string',
            'default': 'lite'
        }

        service_map = {
            'watsonx-orchestrate': 'watsonx-orchestrate',
            'watsonx-governance': 'watsonx-governance',
            'watsonx-ai': 'watsonx-ai'
        }

        service_name = service_map.get(service, service)

        return {
            'type': 'ibm_resource_instance',
            'name': tf_name,
            'config': {
                'name': f'var.{tf_name}_name',
                'service': f'"{service_name}"',
                'plan': f'var.{tf_name}_plan',
                'location': 'var.region',
                'resource_group_id': 'var.resource_group_id',
                'tags': ['var.tags']
            }
        }

    # Multi-provider resource generators

    def _generate_vpc_resource_multi(self, tf_name: str, display_name: str, resource_type: str) -> Dict[str, Any]:
        """Generate VPC/Network resource for any provider"""
        self.variables[f'{tf_name}_name'] = {
            'description': f'Name for the {display_name} network',
            'type': 'string',
            'default': display_name
        }

        config = {'name': f'var.{tf_name}_name'}

        # Provider-specific configurations
        if self.provider == 'ibm':
            config['resource_group'] = 'var.resource_group_id'
            config['tags'] = 'var.tags'
        elif self.provider == 'aws':
            config['cidr_block'] = '"10.0.0.0/16"'
            config['tags'] = 'var.tags'
        elif self.provider == 'google':
            config['project'] = 'var.project_id'
            config['auto_create_subnetworks'] = 'false'
        elif self.provider == 'azure':
            config['location'] = 'var.location'
            config['resource_group_name'] = 'azurerm_resource_group.main.name'
            config['address_space'] = '["10.0.0.0/16"]'
            config['tags'] = 'var.tags'

        return {'type': resource_type, 'name': tf_name, 'config': config}

    def _generate_subnet_resource(self, tf_name: str, display_name: str, resource_type: str) -> Dict[str, Any]:
        """Generate subnet resource for any provider"""
        self.variables[f'{tf_name}_name'] = {
            'description': f'Name for the {display_name} subnet',
            'type': 'string',
            'default': display_name
        }

        config = {'name': f'var.{tf_name}_name'}

        if self.provider == 'ibm':
            config['vpc'] = 'ibm_is_vpc.main.id'
            config['zone'] = '"us-south-1"'
            config['ipv4_cidr_block'] = '"10.0.1.0/24"'
        elif self.provider == 'aws':
            config['vpc_id'] = 'aws_vpc.main.id'
            config['cidr_block'] = '"10.0.1.0/24"'
            config['availability_zone'] = '"us-east-1a"'
            config['tags'] = 'var.tags'
        elif self.provider == 'google':
            config['network'] = 'google_compute_network.main.id'
            config['ip_cidr_range'] = '"10.0.1.0/24"'
            config['region'] = 'var.region'
        elif self.provider == 'azure':
            config['resource_group_name'] = 'azurerm_resource_group.main.name'
            config['virtual_network_name'] = 'azurerm_virtual_network.main.name'
            config['address_prefixes'] = '["10.0.1.0/24"]'

        return {'type': resource_type, 'name': tf_name, 'config': config}

    def _generate_compute_resource(self, tf_name: str, display_name: str, resource_type: str) -> Dict[str, Any]:
        """Generate compute instance resource for any provider"""
        self.variables[f'{tf_name}_name'] = {
            'description': f'Name for the {display_name} instance',
            'type': 'string',
            'default': display_name
        }

        config = {'name': f'var.{tf_name}_name'}

        if self.provider == 'ibm':
            config['profile'] = '"cx2-2x4"'
            config['image'] = '"r006-14140f94-fcc4-11e9-96e7-a72723715315"'
            config['zone'] = '"us-south-1"'
            config['vpc'] = 'ibm_is_vpc.main.id'
            config['primary_network_interface'] = '{subnet = ibm_is_subnet.main.id}'
        elif self.provider == 'aws':
            config['ami'] = '"ami-0c55b159cbfafe1f0"'
            config['instance_type'] = '"t2.micro"'
            config['subnet_id'] = 'aws_subnet.main.id'
            config['tags'] = 'var.tags'
        elif self.provider == 'google':
            config['machine_type'] = '"e2-medium"'
            config['zone'] = '"us-central1-a"'
            config['boot_disk'] = '{initialize_params {image = "debian-cloud/debian-11"}}'
            config['network_interface'] = '{network = google_compute_network.main.id, subnetwork = google_compute_subnetwork.main.id}'
        elif self.provider == 'azure':
            config['location'] = 'var.location'
            config['resource_group_name'] = 'azurerm_resource_group.main.name'
            config['network_interface_ids'] = '[azurerm_network_interface.main.id]'
            config['vm_size'] = '"Standard_B2s"'
            config['os_disk'] = '{caching = "ReadWrite", storage_account_type = "Standard_LRS"}'
        elif self.provider == 'kubernetes':
            config['metadata'] = '{name = var.%s_name, namespace = var.namespace}' % tf_name
            config['spec'] = '{replicas = 2, selector {match_labels = {app = var.%s_name}}, template {metadata {labels = {app = var.%s_name}}, spec {container {name = var.%s_name, image = "nginx:latest"}}}}' % (tf_name, tf_name, tf_name)

        return {'type': resource_type, 'name': tf_name, 'config': config}

    def _generate_load_balancer_resource(self, tf_name: str, display_name: str, resource_type: str) -> Dict[str, Any]:
        """Generate load balancer resource for any provider"""
        self.variables[f'{tf_name}_name'] = {
            'description': f'Name for the {display_name} load balancer',
            'type': 'string',
            'default': display_name
        }

        config = {'name': f'var.{tf_name}_name'}

        if self.provider == 'ibm':
            config['subnets'] = '[ibm_is_subnet.main.id]'
        elif self.provider == 'aws':
            config['load_balancer_type'] = '"application"'
            config['subnets'] = '[aws_subnet.main.id]'
            config['tags'] = 'var.tags'
        elif self.provider == 'google':
            config['ip_protocol'] = '"TCP"'
            config['port_range'] = '"80"'
            config['target'] = 'google_compute_target_pool.main.self_link'
        elif self.provider == 'azure':
            config['location'] = 'var.location'
            config['resource_group_name'] = 'azurerm_resource_group.main.name'
        elif self.provider == 'kubernetes':
            config['metadata'] = '{name = var.%s_name, namespace = var.namespace}' % tf_name
            config['spec'] = '{type = "LoadBalancer", selector = {app = "myapp"}, port {port = 80, target_port = 8080}}'

        return {'type': resource_type, 'name': tf_name, 'config': config}

    def _generate_database_resource(self, tf_name: str, display_name: str, resource_type: str) -> Dict[str, Any]:
        """Generate database resource for any provider"""
        self.variables[f'{tf_name}_name'] = {
            'description': f'Name for the {display_name} database',
            'type': 'string',
            'default': display_name
        }

        config = {'name': f'var.{tf_name}_name'}

        if self.provider == 'ibm':
            config['service'] = '"databases-for-postgresql"'
            config['plan'] = '"standard"'
            config['location'] = 'var.region'
            config['resource_group_id'] = 'var.resource_group_id'
        elif self.provider == 'aws':
            config['engine'] = '"postgres"'
            config['engine_version'] = '"14.7"'
            config['instance_class'] = '"db.t3.micro"'
            config['allocated_storage'] = '20'
            config['username'] = '"admin"'
            config['password'] = '"changeme"'
            config['skip_final_snapshot'] = 'true'
            config['tags'] = 'var.tags'
        elif self.provider == 'google':
            config['database_version'] = '"POSTGRES_14"'
            config['region'] = 'var.region'
            config['settings'] = '{tier = "db-f1-micro"}'
        elif self.provider == 'azure':
            config['location'] = 'var.location'
            config['resource_group_name'] = 'azurerm_resource_group.main.name'
            config['sku_name'] = '"B_Gen5_1"'
            config['version'] = '"11"'
            config['administrator_login'] = '"psqladmin"'
            config['administrator_login_password'] = '"H@Sh1CoR3!"'
        elif self.provider == 'kubernetes':
            config['metadata'] = '{name = var.%s_name, namespace = var.namespace}' % tf_name
            config['spec'] = '{replicas = 1, selector {match_labels = {app = "database"}}, template {metadata {labels = {app = "database"}}, spec {container {name = "postgres", image = "postgres:14"}}}}'

        return {'type': resource_type, 'name': tf_name, 'config': config}

    def _generate_resource_group_multi(self, tf_name: str, display_name: str, resource_type: str) -> Dict[str, Any]:
        """Generate resource group/namespace for any provider"""
        self.variables[f'{tf_name}_name'] = {
            'description': f'Name for the {display_name} resource group',
            'type': 'string',
            'default': display_name
        }

        config = {'name': f'var.{tf_name}_name'}

        if self.provider == 'ibm':
            pass  # IBM resource group only needs name
        elif self.provider == 'google':
            config['project_id'] = f'var.{tf_name}_name'
        elif self.provider == 'azure':
            config['location'] = 'var.location'
        elif self.provider == 'kubernetes':
            config['metadata'] = '{name = var.%s_name}' % tf_name

        return {'type': resource_type, 'name': tf_name, 'config': config}

    def _generate_floating_ip_resource(self, tf_name: str, display_name: str, resource_type: str) -> Dict[str, Any]:
        """Generate floating/elastic IP resource for any provider"""
        self.variables[f'{tf_name}_name'] = {
            'description': f'Name for the {display_name} IP',
            'type': 'string',
            'default': display_name
        }

        config = {'name': f'var.{tf_name}_name'}

        if self.provider == 'ibm':
            config['zone'] = '"us-south-1"'
        elif self.provider == 'aws':
            config['vpc'] = 'true'
            config['tags'] = 'var.tags'
        elif self.provider == 'google':
            config['region'] = 'var.region'
        elif self.provider == 'azure':
            config['location'] = 'var.location'
            config['resource_group_name'] = 'azurerm_resource_group.main.name'
            config['allocation_method'] = '"Static"'

        return {'type': resource_type, 'name': tf_name, 'config': config}

    def _generate_gateway_resource(self, tf_name: str, display_name: str, resource_type: str) -> Dict[str, Any]:
        """Generate NAT gateway resource for any provider"""
        self.variables[f'{tf_name}_name'] = {
            'description': f'Name for the {display_name} gateway',
            'type': 'string',
            'default': display_name
        }

        config = {'name': f'var.{tf_name}_name'}

        if self.provider == 'ibm':
            config['vpc'] = 'ibm_is_vpc.main.id'
            config['zone'] = '"us-south-1"'
        elif self.provider == 'aws':
            config['subnet_id'] = 'aws_subnet.main.id'
            config['allocation_id'] = 'aws_eip.main.id'
            config['tags'] = 'var.tags'
        elif self.provider == 'google':
            config['router'] = 'google_compute_router.main.name'
            config['region'] = 'var.region'
            config['nat_ip_allocate_option'] = '"AUTO_ONLY"'
            config['source_subnetwork_ip_ranges_to_nat'] = '"ALL_SUBNETWORKS_ALL_IP_RANGES"'
        elif self.provider == 'azure':
            config['location'] = 'var.location'
            config['resource_group_name'] = 'azurerm_resource_group.main.name'

        return {'type': resource_type, 'name': tf_name, 'config': config}

    def _generate_app_service_resource(self, tf_name: str, display_name: str, resource_type: str) -> Dict[str, Any]:
        """Generate application service resource for any provider"""
        self.variables[f'{tf_name}_name'] = {
            'description': f'Name for the {display_name} application',
            'type': 'string',
            'default': display_name
        }

        config = {'name': f'var.{tf_name}_name'}

        if self.provider == 'ibm':
            config['service'] = '"cloud-object-storage"'
            config['plan'] = '"lite"'
            config['location'] = 'var.region'
        elif self.provider == 'aws':
            config['description'] = f'"{display_name} application"'
        elif self.provider == 'google':
            config['location_id'] = 'var.region'
        elif self.provider == 'azure':
            config['location'] = 'var.location'
            config['resource_group_name'] = 'azurerm_resource_group.main.name'
            config['app_service_plan_id'] = 'azurerm_app_service_plan.main.id'
        elif self.provider == 'kubernetes':
            config['metadata'] = '{name = var.%s_name, namespace = var.namespace}' % tf_name
            config['spec'] = '{replicas = 3, selector {match_labels = {app = var.%s_name}}, template {metadata {labels = {app = var.%s_name}}, spec {container {name = var.%s_name, image = "nginx:latest", port {container_port = 80}}}}}' % (tf_name, tf_name, tf_name)

        return {'type': resource_type, 'name': tf_name, 'config': config}

    def _generate_watson_service_resource(self, tf_name: str, display_name: str, service: str, resource_type: str) -> Dict[str, Any] | None:
        """Generate Watson service resource (IBM only)"""
        if self.provider != 'ibm':
            return None

        return self._generate_resource_instance(tf_name, display_name, service or 'watsonx-ai')

    def _generate_resource_group(self, tf_name: str, display_name: str) -> Dict[str, Any]:
        """Generate resource group configuration"""
        self.variables[f'{tf_name}_name'] = {
            'description': f'Name for the {display_name} resource group',
            'type': 'string',
            'default': display_name
        }

        return {
            'type': 'ibm_resource_group',
            'name': tf_name,
            'config': {
                'name': f'var.{tf_name}_name'
            }
        }

    def _generate_main_tf(self) -> str:
        """Generate main.tf content"""
        # Use custom provider config if available, otherwise use predefined
        if self.custom_provider_config:
            provider_config = self.custom_provider_config
            provider_name = self.custom_provider_config['name']
        else:
            provider_config = self.PROVIDER_CONFIGS.get(self.provider, self.PROVIDER_CONFIGS['ibm'])
            provider_name = self.provider

        lines = [
            f'# {provider_name.upper()} Terraform Configuration',
            '# Generated from Draw.io diagram',
            f'# Provider: {provider_name}',
            f'# Documentation: {provider_config["docs"]}',
            '',
            '# Terraform configuration',
            'terraform {',
            '  required_version = ">= 1.0"',
            '  required_providers {',
            f'    {provider_name} = {{',
            f'      source  = "{provider_config["source"]}"',
            f'      version = "{provider_config["version"]}"',
            '    }',
            '  }',
            '}',
            ''
        ]

        # Add resources
        if self.resources:
            for resource in self.resources:
                lines.extend(self._format_resource(resource))
                lines.append('')
        else:
            # No resources generated - add helpful message
            lines.append('# No resources generated.')
            if hasattr(self, 'skipped_resources') and self.skipped_resources:
                lines.append('# This diagram contains IBM Cloud-specific components that are not')
                lines.append(f'# supported by the {provider_name} provider.')
                lines.append('#')
                lines.append('# Skipped IBM Cloud resources:')
                for skipped in self.skipped_resources:
                    lines.append(f'#   - {skipped["name"]} ({skipped["type"]})')
                lines.append('#')
                lines.append('# To generate IBM Cloud resources, please select "IBM Cloud" as the provider.')
            lines.append('')

        return '\n'.join(lines)

    def _format_resource(self, resource: Dict[str, Any]) -> List[str]:
        """Format a resource as Terraform HCL"""
        lines = [
            f'resource "{resource["type"]}" "{resource["name"]}" {{'
        ]

        for key, value in resource['config'].items():
            if isinstance(value, list):
                lines.append(f'  {key} = {value[0]}')
            else:
                lines.append(f'  {key} = {value}')

        lines.append('}')
        return lines

    def _generate_variables_tf(self) -> str:
        """Generate variables.tf content"""
        provider_vars = self._get_provider_variables()

        lines = [
            f'# Variables for {self.provider.upper()} resources',
            '# Generated from Draw.io diagram',
            ''
        ]

        # Add provider-specific variables
        lines.extend(provider_vars)
        lines.append('')

        # Add component-specific variables
        for var_name, var_config in self.variables.items():
            lines.append(f'variable "{var_name}" {{')
            lines.append(f'  description = "{var_config["description"]}"')
            lines.append(f'  type        = {var_config["type"]}')
            if 'default' in var_config:
                if isinstance(var_config['default'], str):
                    lines.append(f'  default     = "{var_config["default"]}"')
                else:
                    lines.append(f'  default     = {var_config["default"]}')
            lines.append('}')
            lines.append('')

        return '\n'.join(lines)

    def _generate_providers_tf(self) -> str:
        """Generate providers.tf content"""
        provider_config = self._get_provider_config()

        lines = [
            f'# {self.provider.upper()} Provider Configuration',
            '# Generated from Draw.io diagram',
            ''
        ]

        lines.extend(provider_config)
        lines.append('')

        return '\n'.join(lines)

    def _get_provider_variables(self) -> List[str]:
        """Get provider-specific variables"""
        # For custom providers, return generic variables
        if self.custom_provider_config:
            return [
                'variable "api_key" {',
                '  description = "API Key for authentication"',
                '  type        = string',
                '  sensitive   = true',
                '}',
                '',
                'variable "region" {',
                '  description = "Region for resources"',
                '  type        = string',
                '  default     = "us-south"',
                '}',
                '',
                'variable "tags" {',
                '  description = "Tags for resources"',
                '  type        = list(string)',
                '  default     = ["terraform", "drawio-generated"]',
                '}'
            ]

        if self.provider == 'ibm':
            return [
                'variable "ibmcloud_api_key" {',
                '  description = "IBM Cloud API Key"',
                '  type        = string',
                '  sensitive   = true',
                '}',
                '',
                'variable "region" {',
                '  description = "IBM Cloud region"',
                '  type        = string',
                '  default     = "us-south"',
                '}',
                '',
                'variable "resource_group_id" {',
                '  description = "Resource group ID"',
                '  type        = string',
                '}',
                '',
                'variable "tags" {',
                '  description = "Tags for resources"',
                '  type        = list(string)',
                '  default     = ["terraform", "drawio-generated"]',
                '}'
            ]
        elif self.provider == 'azure':
            return [
                'variable "subscription_id" {',
                '  description = "Azure Subscription ID"',
                '  type        = string',
                '}',
                '',
                'variable "tenant_id" {',
                '  description = "Azure Tenant ID"',
                '  type        = string',
                '}',
                '',
                'variable "location" {',
                '  description = "Azure region"',
                '  type        = string',
                '  default     = "eastus"',
                '}',
                '',
                'variable "tags" {',
                '  description = "Tags for resources"',
                '  type        = map(string)',
                '  default     = {',
                '    Environment = "Development"',
                '    ManagedBy   = "Terraform"',
                '  }',
                '}'
            ]
        elif self.provider == 'google':
            return [
                'variable "project_id" {',
                '  description = "Google Cloud Project ID"',
                '  type        = string',
                '}',
                '',
                'variable "region" {',
                '  description = "Google Cloud region"',
                '  type        = string',
                '  default     = "us-central1"',
                '}',
                '',
                'variable "labels" {',
                '  description = "Labels for resources"',
                '  type        = map(string)',
                '  default     = {',
                '    environment = "development"',
                '    managed_by  = "terraform"',
                '  }',
                '}'
            ]
        elif self.provider == 'aws':
            return [
                'variable "region" {',
                '  description = "AWS region"',
                '  type        = string',
                '  default     = "us-east-1"',
                '}',
                '',
                'variable "tags" {',
                '  description = "Tags for resources"',
                '  type        = map(string)',
                '  default     = {',
                '    Environment = "Development"',
                '    ManagedBy   = "Terraform"',
                '  }',
                '}'
            ]
        elif self.provider == 'kubernetes':
            return [
                'variable "config_path" {',
                '  description = "Path to kubeconfig file"',
                '  type        = string',
                '  default     = "~/.kube/config"',
                '}',
                '',
                'variable "config_context" {',
                '  description = "Kubernetes context to use"',
                '  type        = string',
                '  default     = ""',
                '}',
                '',
                'variable "namespace" {',
                '  description = "Default namespace"',
                '  type        = string',
                '  default     = "default"',
                '}'
            ]
        elif self.provider == 'terraform':
            return [
                'variable "tfe_token" {',
                '  description = "Terraform Cloud/Enterprise API Token"',
                '  type        = string',
                '  sensitive   = true',
                '}',
                '',
                'variable "tfe_hostname" {',
                '  description = "Terraform Cloud/Enterprise hostname"',
                '  type        = string',
                '  default     = "app.terraform.io"',
                '}',
                '',
                'variable "organization" {',
                '  description = "Terraform Cloud/Enterprise organization name"',
                '  type        = string',
                '}'
            ]

        return []

    def _get_provider_config(self) -> List[str]:
        """Get provider-specific configuration"""
        # For custom providers, return generic configuration
        if self.custom_provider_config:
            provider_name = self.custom_provider_config['name']
            return [
                f'provider "{provider_name}" {{',
                '  # Configure provider-specific settings here',
                '  # Refer to provider documentation for available options',
                f'  # Documentation: {self.custom_provider_config["docs"]}',
                '}'
            ]

        if self.provider == 'ibm':
            return [
                'provider "ibm" {',
                '  ibmcloud_api_key = var.ibmcloud_api_key',
                '  region           = var.region',
                '}'
            ]
        elif self.provider == 'azure':
            return [
                'provider "azurerm" {',
                '  features {}',
                '  subscription_id = var.subscription_id',
                '  tenant_id       = var.tenant_id',
                '}'
            ]
        elif self.provider == 'google':
            return [
                'provider "google" {',
                '  project = var.project_id',
                '  region  = var.region',
                '}'
            ]
        elif self.provider == 'aws':
            return [
                'provider "aws" {',
                '  region = var.region',
                '}'
            ]
        elif self.provider == 'kubernetes':
            return [
                'provider "kubernetes" {',
                '  config_path    = var.config_path',
                '  config_context = var.config_context',
                '}'
            ]
        elif self.provider == 'terraform':
            return [
                'provider "tfe" {',
                '  token    = var.tfe_token',
                '  hostname = var.tfe_hostname',
                '}'
            ]

        return []

    def _sanitize_name(self, name: str) -> str:
        """Sanitize a name for use in Terraform"""
        # Remove special characters and replace spaces with underscores
        sanitized = name.lower()
        sanitized = sanitized.replace(' ', '_')
        sanitized = sanitized.replace('-', '_')
        sanitized = sanitized.replace('.', '_')
        # Remove any non-alphanumeric characters except underscores
        sanitized = ''.join(c for c in sanitized if c.isalnum() or c == '_')
        # Ensure it starts with a letter
        if sanitized and not sanitized[0].isalpha():
            sanitized = 'res_' + sanitized
        return sanitized or 'unnamed_resource'

# Made with Bob

Strategic Versatility: From a Curated List to Custom Templates

Current versions of the application excel at interpreting IBM Cloud-specific shapes and generating highly accurate HCL for that environment (to be tested for sure). However, this is only the beginning of our multi-cloud vision. Future iterations will expand this specialized support to other major providers like AWS and Azure, moving beyond generic detection to deep resource mapping. We are also developing a robust “Generator Template” feature that will allow users to extend the system’s capabilities independently; by simply providing a repository URL for any GitHub-hosted Terraform provider, users will eventually be able to generate bespoke configurations for even the most niche infrastructure requirements.

The Front-end — HTML And Javascript

The frontend of the Terraform Builder is a modern, responsive single-page application built using a standard web stack of HTML5, CSS3, and vanilla JavaScript. The interface, defined in index.html, features a clean two-column layout that guides users through the workflow of either creating diagrams in Draw.io or uploading existing XML files. Styling is managed through styles.css, which implements a professional look-and-feel inspired by the IBM Design System, utilizing the IBM Plex font family. The client-side logic resides in app.js, which orchestrates the user interaction—handling drag-and-drop file uploads, managing the provider selection (including custom GitHub templates), and dynamically updating the UI with generated HCL code. This JavaScript layer also facilitates the multi-file preview and download functionality, ensuring a seamless experience without the need for complex frontend frameworks.

Output Samples

The application streamlines the transition from design to deployment by delivering the generated HCL scripts in a structured, timestamped format, ensuring every architectural iteration is captured and organized. By programmatically mapping visual components from a Draw.io diagram directly into main.tf, variables.tf, and providers.tf, the tool dramatically accelerates the infrastructure provisioning process, eliminating the manual overhead of writing boilerplate code. However, while this visual-to-code automation provides a high-speed starting point that reflects the intended design, it is crucial that these scripts are thoroughly reviewed and tested in a development environment before production use. This workflow allows architects to focus on the high-level logic while the application handles the technical translation, significantly reducing time-to-market without bypassing the essential step of human validation.

# IBM Terraform Configuration
# Generated from Draw.io diagram
# Provider: ibm
# Documentation: https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs

# Terraform configuration
terraform {
  required_version = ">= 1.0"
  required_providers {
    ibm = {
      source  = "IBM-Cloud/ibm"
      version = ">= 1.60.0"
    }
  }
}

resource "ibm_resource_group" "ibm_cloud" {
  name = var.ibm_cloud_name
}

resource "ibm_is_vpc" "vpc" {
  name = var.vpc_name
  resource_group = var.resource_group_id
  tags = var.tags
}

resource "ibm_resource_group" "ibm_cloud" {
  name = var.ibm_cloud_name
}

resource "ibm_database" "data_base" {
  name = var.data_base_name
  service = "databases-for-postgresql"
  plan = "standard"
  location = var.region
  resource_group_id = var.resource_group_id
}

resource "ibm_is_public_gateway" "network_public" {
  name = var.network_public_name
  vpc = ibm_is_vpc.main.id
  zone = "us-south-1"
}

resource "ibm_is_instance" "rev_" {
  name = var.rev__name
  profile = "cx2-2x4"
  image = "r006-14140f94-fcc4-11e9-96e7-a72723715315"
  zone = "us-south-1"
  vpc = ibm_is_vpc.main.id
  primary_network_interface = {subnet = ibm_is_subnet.main.id}
}

resource "ibm_resource_instance" "application_web" {
  name = var.application_web_name
  service = "cloud-object-storage"
  plan = "lite"
  location = var.region
}

resource "ibm_resource_group" "ibm_cloud" {
  name = var.ibm_cloud_name
}

resource "ibm_database" "data_base" {
  name = var.data_base_name
  service = "databases-for-postgresql"
  plan = "standard"
  location = var.region
  resource_group_id = var.resource_group_id
}

resource "ibm_is_public_gateway" "network_public" {
  name = var.network_public_name
  vpc = ibm_is_vpc.main.id
  zone = "us-south-1"
}

resource "ibm_is_instance" "rev_" {
  name = var.rev__name
  profile = "cx2-2x4"
  image = "r006-14140f94-fcc4-11e9-96e7-a72723715315"
  zone = "us-south-1"
  vpc = ibm_is_vpc.main.id
  primary_network_interface = {subnet = ibm_is_subnet.main.id}
}

resource "ibm_is_floating_ip" "floating_ip" {
  name = var.floating_ip_name
  zone = "us-south-1"
}

resource "ibm_resource_instance" "application_web" {
  name = var.application_web_name
  service = "cloud-object-storage"
  plan = "lite"
  location = var.region
}

resource "ibm_is_lb" "load_balancer_vpc" {
  name = var.load_balancer_vpc_name
  subnets = [ibm_is_subnet.main.id]
}

resource "ibm_is_floating_ip" "floating_ip" {
  name = var.floating_ip_name
  zone = "us-south-1"
}

# IBM Provider Configuration
# Generated from Draw.io diagram

provider "ibm" {
  ibmcloud_api_key = var.ibmcloud_api_key
  region           = var.region
}

# Variables for IBM resources
# Generated from Draw.io diagram

variable "ibmcloud_api_key" {
  description = "IBM Cloud API Key"
  type        = string
  sensitive   = true
}

variable "region" {
  description = "IBM Cloud region"
  type        = string
  default     = "us-south"
}

variable "resource_group_id" {
  description = "Resource group ID"
  type        = string
}

variable "tags" {
  description = "Tags for resources"
  type        = list(string)
  default     = ["terraform", "drawio-generated"]
}

variable "ibm_cloud_name" {
  description = "Name for the ibm_cloud resource group"
  type        = string
  default     = "ibm_cloud"
}

variable "vpc_name" {
  description = "Name for the VPC network"
  type        = string
  default     = "VPC"
}

variable "data_base_name" {
  description = "Name for the data_base database"
  type        = string
  default     = "data_base"
}

variable "network_public_name" {
  description = "Name for the network_public gateway"
  type        = string
  default     = "network_public"
}

variable "rev__name" {
  description = "Name for the Rev. instance"
  type        = string
  default     = "Rev."
}

variable "application_web_name" {
  description = "Name for the application_web application"
  type        = string
  default     = "application_web"
}

variable "floating_ip_name" {
  description = "Name for the floating_ip IP"
  type        = string
  default     = "floating_ip"
}

variable "load_balancer_vpc_name" {
  description = "Name for the load_balancer_vpc load balancer"
  type        = string
  default     = "load_balancer_vpc"
}

Deployment

Beyond local execution, the Terraform Builder is engineered for seamless cloud-native deployment. The inclusion of a multi-stage Dockerfile ensures the application is fully containerized, providing a consistent environment across different hosting platforms. For teams utilizing orchestration, the project provides a complete set of Kubernetes manifests: deployment.yaml defines a scalable architecture with dual replicas and integrated liveness/readiness probes for high availability, while configmap.yaml centralizes environment-specific settings. This "production-ready" approach allows the generator to be easily hosted on platforms like IBM Cloud Code Engine, Red Hat OpenShift, or any standard Kubernetes cluster, transforming it from a local utility into a shared enterprise service.

Conclusion

In conclusion, the Terraform Builder provides a comprehensive, end-to-end bridge between visual architectural design and automated infrastructure deployment. By combining a sleek, user friendly frontend with a powerful Python-driven backend, the application successfully transforms static Draw.io diagrams into functional, multi-file Terraform configurations. With its production-ready containerization and Kubernetes manifests, the tool is prepared for immediate deployment in cloud-native environments. While currently optimized for IBM Cloud in its alpha release, the foundational architecture is already in place to support a vast ecosystem of providers and custom templates, representing a significant step forward in personal productivity and the democratization of Infrastructure as Code.

>>> Thanks for reading <<<

Markdown Everything: My New Personal Project: HTML/URL to Markdown Converter

Alain Airom (Ayrom) — Sun, 26 Apr 2026 13:05:08 +0000

Simplifying Documentation using IBM Bob to Create My New Personal Project: HTML/URL to Markdown Converter!

Introduction (and spoiler)

I know, I know — take a deep breath and try to remain calm. This project features exactly zero autonomous AI agents, no sophisticated RAG pipelines, and — brace yourselves — not a single “groundbreaking” LLM integration to disrupt the industry. I’m truly sorry to disappoint the hype-train, but as often happens when I’m left to my own devices, I had a burning need for a tool that actually does something simple. So, instead of building a sentient toaster, I decided to create my own URL-to-Markdown converter for Chrome. It’s just a humble extension designed to solve a real problem, though, in a classic display of “do as I say, not as I do,” I naturally just sat back and made Bob do all the actual manual labor to realize it for me. Simple, right?

The Implementation

The application is structured as a modular utility that can handle both local files and live web URLs, converting messy HTML into clean, standardized Markdown. The core logic relies on the Turndown library, enhanced by custom rules for GitHub-Flavored Markdown (GFM).

Core Conversion Engine

At the heart of every script lies the TurndownService. The logic follows a consistent pipeline:

Initialization: Configures headingStyle (ATX vs Setext) and codeBlockStyle (fenced).
Plugin Integration: Uses turndown-plugin-gfm to ensure tables and task lists are preserved.
Custom Rules: Specifically targets elements like <pre> tags to ensure syntax highlighting is maintained in the output.

#!/usr/bin/env node

/**
 * Node.js CLI script to convert HTML files to Markdown
 * Usage: node scripts/convert-file.js <input-file> [output-file]
 */

const fs = require('fs');
const path = require('path');

// Load the converter
const HtmlToMarkdown = require('../src/html-to-markdown.js');

// Verify JSDOM is available for Node.js
try {
  require('jsdom');
} catch (e) {
  console.error('Error: JSDOM is required for Node.js usage.');
  console.error('Install it with: npm install jsdom');
  process.exit(1);
}

// Parse command line arguments
const args = process.argv.slice(2);

if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
  console.log(`
HTML to Markdown Converter - CLI Tool

Usage:
  node scripts/convert-file.js <input-file> [output-file]
  node scripts/convert-file.js --help

Arguments:
  input-file    Path to the HTML file to convert
  output-file   (Optional) Path for the output Markdown file
                If not provided, will create a timestamped file in output/

Options:
  --help, -h    Show this help message

Examples:
  node scripts/convert-file.js input/sample.html
  node scripts/convert-file.js input/sample.html output/result.md
  node scripts/convert-file.js page.html
  `);
  process.exit(0);
}

const inputFile = args[0];
let outputFile = args[1];

// Check if input file exists
if (!fs.existsSync(inputFile)) {
  console.error(`Error: Input file '${inputFile}' not found.`);
  process.exit(1);
}

// Read the HTML file
console.log(`Reading HTML from: ${inputFile}`);
const html = fs.readFileSync(inputFile, 'utf8');

// Create converter instance
const converter = new HtmlToMarkdown({
  headingStyle: 'atx',
  codeBlockStyle: 'fenced',
  bulletListMarker: '-',
  strongDelimiter: '**',
  emDelimiter: '_'
});

// Convert to Markdown
console.log('Converting HTML to Markdown...');
const markdown = converter.convert(html);

// Generate output filename if not provided
if (!outputFile) {
  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
  const inputBasename = path.basename(inputFile, path.extname(inputFile));
  outputFile = path.join('output', `${inputBasename}-${timestamp}.md`);

  // Ensure output directory exists
  const outputDir = path.dirname(outputFile);
  if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir, { recursive: true });
  }
}

// Write the Markdown file
fs.writeFileSync(outputFile, markdown, 'utf8');

console.log(`✓ Conversion successful!`);
console.log(`Output saved to: ${outputFile}`);
console.log(`File size: ${markdown.length} characters`);

// Made with Bob

Data Acquisition Logic

The application handles three distinct entry points:

| Entry Point     | Logic Flow                                                   |
| --------------- | ------------------------------------------------------------ |
| **Local File**  | Reads raw HTML from the filesystem using `fs.readFileSync`.  |
| **Simple URL**  | Fetches remote HTML via `axios`, then parses the DOM.        |
| **Complex URL** | Uses **JSDOM** to simulate a browser environment, allowing for cleaner extraction of titles and metadata before conversion. |

Image Handling & Asset Management

As detailed in Image-Handling.md, the tool doesn't just convert text; it manages media context:

Absolute URL Resolution: Logic converts relative paths (/img/photo.png) into absolute URLs based on the source domain.
Alt-Text Preservation: Ensures accessibility by mapping alt attributes to Markdown image syntax: ![alt](url).

#!/usr/bin/env node

/**
 * Node.js CLI script to convert HTML from a URL to Markdown
 * Usage: node scripts/convert-url.js <url> [output-file]
 */

const fs = require('fs');
const path = require('path');
const https = require('https');
const http = require('http');

// Load the converter
const HtmlToMarkdown = require('../src/html-to-markdown.js');

// Verify JSDOM is available
try {
  require('jsdom');
} catch (e) {
  console.error('Error: JSDOM is required for Node.js usage.');
  console.error('Install it with: npm install jsdom');
  process.exit(1);
}

// Parse command line arguments
const args = process.argv.slice(2);

if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
  console.log(`
HTML to Markdown Converter - URL Fetcher

Usage:
  node scripts/convert-url.js <url> [output-file]
  node scripts/convert-url.js --help

Arguments:
  url           URL of the webpage to convert
  output-file   (Optional) Path for the output Markdown file
                If not provided, will create a timestamped file in output/

Options:
  --help, -h    Show this help message

Examples:
  node scripts/convert-url.js https://example.com
  node scripts/convert-url.js https://example.com output/example.md
  node scripts/convert-url.js https://github.com/user/repo/blob/main/README.md
  `);
  process.exit(0);
}

const url = args[0];
let outputFile = args[1];

// Validate URL
try {
  new URL(url);
} catch (e) {
  console.error(`Error: Invalid URL '${url}'`);
  console.error('Please provide a valid URL starting with http:// or https://');
  process.exit(1);
}

/**
 * Fetch HTML content from URL
 */
function fetchUrl(url) {
  return new Promise((resolve, reject) => {
    const protocol = url.startsWith('https') ? https : http;

    console.log(`Fetching content from: ${url}`);

    const request = protocol.get(url, {
      headers: {
        'User-Agent': 'Mozilla/5.0 (compatible; HTML-to-Markdown-Converter/1.0)'
      }
    }, (response) => {
      // Handle redirects
      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
        console.log(`Following redirect to: ${response.headers.location}`);
        fetchUrl(response.headers.location).then(resolve).catch(reject);
        return;
      }

      if (response.statusCode !== 200) {
        reject(new Error(`HTTP ${response.statusCode}: ${response.statusMessage}`));
        return;
      }

      let data = '';
      response.on('data', chunk => data += chunk);
      response.on('end', () => resolve(data));
    });

    request.on('error', reject);
    request.setTimeout(30000, () => {
      request.destroy();
      reject(new Error('Request timeout after 30 seconds'));
    });
  });
}

/**
 * Extract domain name from URL for filename
 */
function getDomainName(url) {
  try {
    const urlObj = new URL(url);
    return urlObj.hostname.replace(/^www\./, '');
  } catch (e) {
    return 'webpage';
  }
}

// Main execution
(async () => {
  try {
    // Fetch HTML from URL
    const html = await fetchUrl(url);

    if (!html || html.trim().length === 0) {
      console.error('Error: No content received from URL');
      process.exit(1);
    }

    console.log(`✓ Content fetched (${html.length} characters)`);

    // Create converter instance
    const converter = new HtmlToMarkdown({
      headingStyle: 'atx',
      codeBlockStyle: 'fenced',
      bulletListMarker: '-',
      strongDelimiter: '**',
      emDelimiter: '_'
    });

    // Convert to Markdown
    console.log('Converting HTML to Markdown...');
    const markdown = converter.convert(html);

    // Generate output filename if not provided
    if (!outputFile) {
      const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
      const domain = getDomainName(url);
      outputFile = path.join('output', `${domain}-${timestamp}.md`);

      // Ensure output directory exists
      const outputDir = path.dirname(outputFile);
      if (!fs.existsSync(outputDir)) {
        fs.mkdirSync(outputDir, { recursive: true });
      }
    }

    // Write the Markdown file
    fs.writeFileSync(outputFile, markdown, 'utf8');

    console.log(`✓ Conversion successful!`);
    console.log(`Output saved to: ${outputFile}`);
    console.log(`File size: ${markdown.length} characters`);
    console.log(`\nPreview (first 500 characters):`);
    console.log('─'.repeat(60));
    console.log(markdown.substring(0, 500) + (markdown.length > 500 ? '...' : ''));
    console.log('─'.repeat(60));

  } catch (error) {
    console.error(`\n✗ Error: ${error.message}`);

    if (error.code === 'ENOTFOUND') {
      console.error('Could not resolve hostname. Please check the URL and your internet connection.');
    } else if (error.code === 'ECONNREFUSED') {
      console.error('Connection refused. The server may be down or unreachable.');
    } else if (error.message.includes('timeout')) {
      console.error('Request timed out. The server may be slow or unresponsive.');
    }

    process.exit(1);
  }
})();

// Made with Bob

Application Workflow

The following logic flow governs the transition from a URL to a downloaded Markdown file:

Request Phase: User provides a URL or file path.
Extraction Phase: The system fetches the content: it isolates the main content body (often stripping headers/footers if logic is applied).
Transformation Phase: HTML tags are mapped to Markdown equivalents (e.g.,
becomes #) : code blocks are wrapped in triple backticks.
Finalization: Metadata (Title, Date, Source URL) is prepended as Front Matter: the resulting string is saved as a .md file.

Last but not Least: Extension for a Browser

The extension follows the standard Chrome “V3” architecture, distributed across three main functional areas:

The Manifest (Orchestrator)

File: manifest.json
Role: Defines the permissions and entry points. It specifically requests activeTab access to read the page content and downloads permissions to save the final .md file to your computer.

The Popup (User Interface)

Files: popup.html, popup.js

/**
 * Chrome Extension Popup Script
 * Handles user interactions and conversion logic
 */

let currentMarkdown = '';

// Initialize when popup opens
document.addEventListener('DOMContentLoaded', () => {
  const convertBtn = document.getElementById('convert-btn');
  const copyBtn = document.getElementById('copy-btn');
  const downloadBtn = document.getElementById('download-btn');
  const markdownOutput = document.getElementById('markdown-output');
  const headingStyle = document.getElementById('heading-style');
  const codeStyle = document.getElementById('code-style');

  // Convert button click
  convertBtn.addEventListener('click', async () => {
    try {
      showStatus('Converting...', 'info');
      convertBtn.disabled = true;

      // Get the active tab
      const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });

      // Execute script in the page to get HTML
      const results = await chrome.scripting.executeScript({
        target: { tabId: tab.id },
        function: getPageHTML
      });

      if (results && results[0] && results[0].result) {
        const html = results[0].result;

        // Convert HTML to Markdown
        const converter = new HtmlToMarkdown({
          headingStyle: headingStyle.value,
          codeBlockStyle: codeStyle.value
        });

        currentMarkdown = converter.convert(html);
        markdownOutput.value = currentMarkdown;

        // Enable buttons
        copyBtn.disabled = false;
        downloadBtn.disabled = false;

        showStatus('✓ Conversion successful!', 'success');
      } else {
        throw new Error('Could not retrieve page content');
      }
    } catch (error) {
      console.error('Conversion error:', error);
      showStatus('✗ Error: ' + error.message, 'error');
    } finally {
      convertBtn.disabled = false;
    }
  });

  // Copy button click
  copyBtn.addEventListener('click', async () => {
    try {
      await navigator.clipboard.writeText(currentMarkdown);
      showStatus('✓ Copied to clipboard!', 'success');

      // Visual feedback
      const originalText = copyBtn.textContent;
      copyBtn.textContent = '✓ Copied!';
      setTimeout(() => {
        copyBtn.textContent = originalText;
      }, 2000);
    } catch (error) {
      console.error('Copy error:', error);
      showStatus('✗ Failed to copy', 'error');
    }
  });

  // Download button click
  downloadBtn.addEventListener('click', () => {
    try {
      const blob = new Blob([currentMarkdown], { type: 'text/markdown' });
      const url = URL.createObjectURL(blob);
      const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
      const filename = `converted-${timestamp}.md`;

      const a = document.createElement('a');
      a.href = url;
      a.download = filename;
      document.body.appendChild(a);
      a.click();
      document.body.removeChild(a);
      URL.revokeObjectURL(url);

      showStatus('✓ Downloaded!', 'success');
    } catch (error) {
      console.error('Download error:', error);
      showStatus('✗ Failed to download', 'error');
    }
  });

  // Update conversion when options change
  headingStyle.addEventListener('change', () => {
    if (currentMarkdown) {
      convertBtn.click();
    }
  });

  codeStyle.addEventListener('change', () => {
    if (currentMarkdown) {
      convertBtn.click();
    }
  });
});

/**
 * Function to be executed in the page context
 * Gets the HTML content of the page
 */
function getPageHTML() {
  // Get the main content, preferring article or main tags
  const article = document.querySelector('article');
  const main = document.querySelector('main');
  const body = document.body;

  // Return the most relevant content
  if (article) {
    return article.outerHTML;
  } else if (main) {
    return main.outerHTML;
  } else {
    return body.innerHTML;
  }
}

/**
 * Show status message
 */
function showStatus(message, type) {
  const status = document.getElementById('status');
  status.textContent = message;
  status.className = `status ${type}`;
  status.style.display = 'block';

  // Auto-hide after 3 seconds for success messages
  if (type === 'success') {
    setTimeout(() => {
      status.style.display = 'none';
    }, 3000);
  }
}

// Made with Bob

Logic: This is the “control center.”
Configuration: It allows users to toggle settings like “Heading Style” (ATX vs. Setext) and “Code Block Style” (Fenced vs. Indented) directly from a dropdown.
Communication: When the “Convert” button is clicked, popup.js sends a message to the content script to grab the page data.
Trigger: Once the Markdown is returned, it creates a Blob and triggers a download via the Chrome Downloads API.

The Content Script (The “Brain”)

File: content.js
Logic: This script lives inside the webpage you are viewing.
Extraction: It scrapes the current DOM, targeting the document.body.innerHTML.
Transformation: It bundles the Turndown library logic to convert that HTML string into Markdown on the fly.
Metadata: It automatically grabs the page <title> and URL to create a header for your document.

/**
 * Content Script
 * Runs in the context of web pages
 * Can be used for additional features like context menu conversion
 */

// Listen for messages from the extension
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  if (request.action === 'getHTML') {
    // Get the HTML content
    const html = document.documentElement.outerHTML;
    sendResponse({ html });
  }
  return true;
});

// Optional: Add keyboard shortcut for quick conversion
document.addEventListener('keydown', (e) => {
  // Ctrl+Shift+M or Cmd+Shift+M to trigger conversion
  if ((e.ctrlKey || e.metaKey) && e.shiftKey && e.key === 'M') {
    e.preventDefault();
    // Open the extension popup programmatically
    chrome.runtime.sendMessage({ action: 'openPopup' });
  }
});

console.log('HTML to Markdown extension loaded');

// Made with Bob

Technical Stack Summary

Runtime: Node.js
Parsing: jsdom (for DOM manipulation)
Conversion: turndown + turndown-plugin-gfm
HTTP Client: axios
CLI Assets: create-icons.sh (for generating Chrome Extension icons)

Note from Bob: The logic is designed to be “plug-and-play.” Whether you are running a script in the terminal or clicking the extension button, the underlying conversion rules remain identical to ensure consistent output quality.

Conclusion

To wrap this all up, there is a distinct, borderline-obsessive satisfaction in using a tool where you know every single line of the source code. Sure, there are dozens of converters out there, but this one is my precious code, and that makes it inherently superior.

The real kicker? The entire transition from “I have a burning need” to a fully functional Chrome extension and CLI suite happened in less than 30 minutes. By offloading the heavy lifting to Bob — who, per my strict instructions, ensured everything was backed by unit tests — the development cycle was essentially at warp speed.

>>> Thanks for reading <<<