# ai4wa/docs2kg architecture

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

- Interactive diagram: https://gitdiagram.com/ai4wa/docs2kg
- Repository: https://github.com/ai4wa/docs2kg

## Overview

##### Main Components
a. Command Line Interface (CLI) – Represented by the Docs2KG command line entry (cli.py) that offers multiple commands (process-document, batch-process, neo4j, etc.).
b. Digitization Module – Shown by the “digitization” folder with submodules for image-based (e.g., PDF OCR via pdf_docling) and native digital document parsing (e.g., ebook and HTML parsing).
c. Agents Module – Under the “agents” directory, include both the base agents and specialized ones (e.g., cloud, hf, ollama, function agents). These are responsible for tasks such as Named Entity Recognition (NER) and other LLM interactions.
d. Knowledge Graph Construction – Split into:
- MetaKG (metadata extraction) found in kg_construction/metadata_kg.
- LayoutKG (layout extraction) found in kg_construction/layout_kg.
- SemanticKG (content/NER extraction) in kg_construction/semantic_kg.
e. Utility and Configuration – Components like config management, constants, timers, and neo4j loader (in utils) that support underlying operations.
f. External Integrations – Such as the integration with external LLM services (e.g., the agent “ollama” and possibly “hf” for Hugging Face) and database operations (Neo4j via docs2kg neo4j command).

##### Relationships and Data Flow
- From the CLI, branch the process into two parallel pathways:
- Document Ingestion & Digitization:
→ Documents enter the digitization module where different paths are applied based on document type (image-based or native).
- Agent Processing:
→ Once digitization is completed, documents (or their extracted content) are passed to the appropriate agent modules for NER and further language model-based processing.
- These streams then converge into the Knowledge Graph Construction component, where the MetaKG, LayoutKG, and SemanticKG modules process the outputs to form a unified knowledge graph.
- Optionally, note the human-LLM collaborative interface (illustrated by the provided screenshots in the README) as an adjunct component that allows human review and enhancement of the generated graph.

##### Architectural Patterns & Design Principles
- Modularity and separation of concerns: Each major function (digitization, agent-based processing, and KG construction) is encapsulated in its own module/subsystem.
- That the design supports both bottom-up (document parsing) and top-down (LLM-driven graph refinement) processing flows.
- Dependencies with configuration management (via config files like config.example.yml and setup scripts) and CI/CD elements (e.g., GitHub workflows for linting and docs) which keep the codebase integrated and tested.

##### Technologies and Frameworks
- Use of Python as the main programming language.
- External libraries and dependencies such as SpaCy (for language processing, as indicated by the spaCy download command) and possibly libraries related to LLM integration.
- Mention containerization support (as shown in the “docker-compose.yml” under examples/compose) and CI workflows which further support deployment and testing strategies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User("User"):::external
    CLI("CLI - Docs2KG Entry Point"):::cli
    User -->|"CLIInvocation"| CLI

    %% Document Ingestion & Digitization
    subgraph "Document Ingestion & Digitization"
        DIGIT("Document Digitization"):::digitization
        IMAGE("Image-based (PDF OCR)"):::digitization
        EBOOK("eBook Parsing"):::digitization
        HTML("HTML Parsing"):::digitization
        WORD("Word Document Parsing"):::digitization
    end
    CLI -->|"StartProcess"| DIGIT
    DIGIT -->|"RouteTo"| IMAGE
    DIGIT -->|"RouteTo"| EBOOK
    DIGIT -->|"RouteTo"| HTML
    DIGIT -->|"RouteTo"| WORD

    %% Agent Processing
    subgraph "Agent Processing"
        AGENT("Agent Processing"):::agent
        BASE("Base Agent"):::agent
        CLOUD("Cloud Agent"):::agent
        HF("HF Agent"):::agent
        OLLAMA("Ollama Agent"):::agent
        FUNC("FuncAgent(ner)"):::agent
    end
    IMAGE -->|"ExtractedContent"| AGENT
    EBOOK -->|"ExtractedContent"| AGENT
    HTML -->|"ExtractedContent"| AGENT
    WORD -->|"ExtractedContent"| AGENT
    AGENT -->|"Distribute"| BASE
    AGENT -->|"Distribute"| CLOUD
    AGENT -->|"Distribute"| HF
    AGENT -->|"Distribute"| OLLAMA
    AGENT -->|"Distribute"| FUNC

    %% Knowledge Graph Construction
    subgraph "Knowledge Graph Construction"
        KG("KG Construction"):::kg
        METAKG("MetaKG(MetadataExtraction)"):::kg
        LAYOUTKG("LayoutKG(LayoutExtraction)"):::kg
        SEMANTICKG("SemanticKG(Content/NERExtraction)"):::kg
    end
    BASE ---|"ProcessedData"| KG
    CLOUD ---|"ProcessedData"| KG
    HF ---|"ProcessedData"| KG
    OLLAMA ---|"ProcessedData"| KG
    FUNC ---|"ProcessedData"| KG
    KG -->|"Layering"| METAKG
    KG -->|"Layering"| LAYOUTKG
    KG -->|"Layering"| SEMANTICKG

    %% Utility and Configuration
    subgraph "Utility & Configuration"
        NEO4J_LOADER("Neo4j Loader"):::utility
    end
    KG -->|"GraphBuild"| NEO4J_LOADER

    %% External Integrations
    subgraph "External Integrations"
        NEO4J_DB("Neo4j Database"):::external
        DEPLOY("ContainerDeployment"):::external
    end
    NEO4J_LOADER -->|"LoadGraph"| NEO4J_DB
    NEO4J_LOADER -->|"Deploy"| DEPLOY

    %% Human-LLM Collaboration Interface
    HUMAN("Human-LLMCollaborationInterface"):::external
    KG -->|"HumanRefinement"| HUMAN

    %% Click Events
    click CLI "https://github.com/ai4wa/docs2kg/blob/develop/Docs2KG/cli.py"
    click DIGIT "https://github.com/ai4wa/docs2kg/tree/develop/Docs2KG/digitization"
    click IMAGE "https://github.com/ai4wa/docs2kg/blob/develop/Docs2KG/digitization/image/pdf_docling.py"
    click EBOOK "https://github.com/ai4wa/docs2kg/blob/develop/Docs2KG/digitization/native/ebook.py"
    click HTML "https://github.com/ai4wa/docs2kg/blob/develop/Docs2KG/digitization/native/html_parser.py"
    click WORD "https://github.com/ai4wa/docs2kg/blob/develop/Docs2KG/digitization/native/word_docling.py"
    click BASE "https://github.com/ai4wa/docs2kg/blob/develop/Docs2KG/agents/base.py"
    click CLOUD "https://github.com/ai4wa/docs2kg/blob/develop/Docs2KG/agents/cloud.py"
    click HF "https://github.com/ai4wa/docs2kg/blob/develop/Docs2KG/agents/hf.py"
    click OLLAMA "https://github.com/ai4wa/docs2kg/blob/develop/Docs2KG/agents/ollama.py"
    click FUNC "https://github.com/ai4wa/docs2kg/blob/develop/Docs2KG/agents/func/ner_llm_judge.py"
    click METAKG "https://github.com/ai4wa/docs2kg/blob/develop/Docs2KG/kg_construction/metadata_kg/metadata_kg.py"
    click LAYOUTKG "https://github.com/ai4wa/docs2kg/blob/develop/Docs2KG/kg_construction/layout_kg/layout_kg.py"
    click SEMANTICKG "https://github.com/ai4wa/docs2kg/tree/develop/Docs2KG/kg_construction/semantic_kg"
    click NEO4J_LOADER "https://github.com/ai4wa/docs2kg/blob/develop/Docs2KG/utils/neo4j_loader.py"
    click DEPLOY "https://github.com/ai4wa/docs2kg/blob/develop/examples/compose/docker-compose.yml"

    %% Styles
    classDef cli fill:#FAD02E,stroke:#333,stroke-width:2px;
    classDef digitization fill:#9FE2BF,stroke:#333,stroke-width:2px;
    classDef agent fill:#81D4FA,stroke:#333,stroke-width:2px;
    classDef kg fill:#FFAB91,stroke:#333,stroke-width:2px;
    classDef utility fill:#CE93D8,stroke:#333,stroke-width:2px;
    classDef external fill:#C5E1A5,stroke:#333,stroke-width:2px;
```
