Knowledge Graph

A comprehensive Java-based knowledge graph system for modeling, analyzing, and visualizing complex entity relationships and their evolution over time.

Overview

This Knowledge Graph implementation provides a robust framework for representing interconnected entities, their relationships, and temporal events. It excels at modeling complex organizational structures, ownership hierarchies, contractual relationships, and temporal changes within networks of entities.

The system is designed to support sophisticated graph analytics, relationship inference, compliance checking, and visualization capabilities while maintaining data quality and provenance.

Key Features

• Rich Entity Modeling: Support for various entity types including corporate structures, individuals, trusts, partnerships, government bodies, and assets
• Typed Relationships: Comprehensive relationship modeling with specialized types for ownership, control, employment, contracts, and more
• Temporal Awareness: Track changes over time with event modeling and temporal context for relationships
• Data Quality: Built-in validation framework for ensuring data consistency and compliance
• Confidence Tracking: Record and evaluate the confidence of assertions with detailed breakdown and reasoning
• Provenance: Track the source and justification for each entity, relationship, and event

System Requirements

• Java 17 or higher
• Maven 3.6+ for building

Getting Started

Installation

Clone the repository and build the project:

git clone [email protected]:cynthiasystems/KnowledgeGraph.git
cd KnowledgeGraph
make install

Quick Start

Run the application:

make run

Development

Build System

This project uses Maven for dependency management and building, with convenient Make targets for common operations:

# Setup, format, verify and install the project
make all

# Install dependencies and build the project
make install

# Compile and package without running tests
make build

# Run tests
make test

# Run tests and quality checks
make verify

# Clean build artifacts
make clean

# Format code according to Google Java Style Guide
make format

# Generate documentation
make docs

Code Quality

The project maintains high code quality standards through automated checks:

• Checkstyle: Enforces coding style based on Google Java Style Guide
• PMD: Analyzes code for potential problems and best practices
• SpotBugs: Performs static analysis to detect bugs
• JaCoCo: Measures test coverage
• Spotless: Automatically formats code

These checks run automatically during the build process and can be triggered individually:

# Run just code formatting
make format

# Check formatting without making changes
make check-format

Project Structure

KnowledgeGraph/
├── src/
│   ├── main/java/io/cynthia/kg/
│   │   ├── model/      # Entity, relationship, and event models
│   │   ├── validation/ # Validation framework
│   │   ├── storage/    # Graph persistence layer
│   │   ├── query/      # Query and traversal capabilities
│   │   └── api/        # API interfaces
│   └── test/
├── config/             # Configuration files for code quality tools
│   ├── checkstyle/
│   ├── pmd/
│   └── spotbugs/
├── .github/workflows/  # CI/CD pipelines
└── docs/               # Documentation

Core Concepts

Entity Types

The knowledge graph supports various entity types including:

• Corporate entities (corporations, LLCs, LLPs)
• Natural persons (individuals)
• Legal arrangements (trusts)
• Public entities (government bodies, associations)
• Physical and financial assets

Each entity type has specific attributes and metadata that can be captured in the graph.

Relationship Types

Relationships between entities are categorized into several types:

• Ownership & Control: Direct/indirect ownership, board control, management control
• Professional: Employment, advisory, representation
• Contractual: Contracts, financial flows, debt
• Personal: Family and personal connections
• Regulatory: Regulatory oversight, filing requirements, licenses

Temporal Framework

The system models time through:

• Point-in-time events
• Temporal context for relationships (effective dates, expiry dates)
• Change tracking across the graph

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details on how to contribute to this project.

Development Environment Setup

The project is IDE-agnostic and supports seamless development in:

• IntelliJ IDEA
• Eclipse
• NetBeans
• VS Code

The included .gitignore file ensures that IDE-specific files don't pollute the repository.

Commit Guidelines

Code quality checks run automatically on commit through pre-commit hooks. To set up the hooks:

make setup-hooks

License

This Knowledge Graph project is available under a dual licensing model designed to balance open source collaboration with commercial viability.

The primary license is the GNU Affero General Public License v3.0 (AGPL-3.0), which allows for free use, modification, and distribution, provided that all modifications are also made available under the same license terms. This license specifically addresses network services, requiring that if you modify the software and provide it as a service over a network, you must make your modified source code available to the users of that service.

For businesses and organizations that wish to incorporate this software into proprietary applications without the obligations imposed by the AGPL-3.0, a Commercial License is available. This option provides the right to use, modify, and distribute the software without the requirement to disclose your source code modifications.

The commercial license is particularly valuable if you:

• Need to integrate the Knowledge Graph into proprietary software
• Cannot or do not want to open-source your modifications
• Require dedicated technical support or custom development

For commercial licensing inquiries, please contact:

• Cynthia Systems
• Email: [email protected]
• Website: https://cynthiasystems.com/

For the full license details, see the LICENSE file in the repository.

Acknowledgments

Open Source Libraries

This project builds upon the work of many outstanding open source projects:

• Jackson Framework - For JSON processing and data binding capabilities
• Apache Commons - For essential utilities including Collections, IO, Lang3, Math3, and Text
• HNSWLib - For approximate nearest neighbor search and vector similarity capabilities
• PicoCLI - For building robust command-line interfaces
• Lombok - For reducing boilerplate code and enhancing developer productivity
• SLF4J - For flexible logging infrastructure
• JUnit - For comprehensive test frameworks

Code Quality Tools

Our development process is enhanced by these excellent tools:

• Checkstyle - For enforcing code style standards
• PMD - For source code analysis
• SpotBugs - For static code analysis and bug detection
• JaCoCo - For code coverage measurement
• Spotless with Google Java Format - For consistent code formatting

Industry Innovators

We acknowledge the following organizations whose work in knowledge visualization and structured data representation has been inspirational:

• Neo4j, TigerGraph, ArangoDB - For pioneering work in graph database technologies
• Ontotext, Stardog - For semantic knowledge graph platforms and solutions
• StructureFlow, Jigsaw, Juristic - For innovations in visual representation of complex legal and business relationships

This project aims to build upon these foundations while bringing new capabilities and perspectives to the knowledge graph domain.