Knom - Knowledge Machine

Knom is a forward-chaining inference engine for Notation3 (N3), a rule-based semantic web language that extends RDF with logical formulas and rules. It implements stratified reasoning to efficiently handle recursive rules and complex logical dependencies.

Features

• Stratified Reasoning: Automatic analysis and stratification of rule dependencies for efficient forward-chaining inference
• Graph Terms: Full support for N3 graph terms (formulas) with proper scoping and unquoting
• Built-in Predicates: Comprehensive set of N3 built-ins including:
  • Logic operations (log:includes, log:forAllIn)
  • Math comparisons (math:lessThan, math:greaterThan, etc.)
  • String operations (string:ord, string comparisons)
• Recursive Rules: Support for recursive rule definitions with automatic cycle detection
• Blank Node Handling: Proper blank node scoping and instantiation
• Variable Binding: Sophisticated pattern matching with variable binding across graph formulas

Installation

Prerequisites

• Python 3.10 or higher
• pip package manager

From Source

# Clone the repository
git clone https://github.com/eyusupov/knom
cd knom

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install .

# For development (includes test dependencies)
pip install ".[test]"

Usage

Command Line

Knom provides a simple command-line interface for processing N3 files:

# Run inference on an N3 file

./tools/knom examples/socrates.n3

# The output will be the inferred triples in N3 format

Examples

Basic Inference (Socrates)

# examples/socrates.n3
@prefix : <http://example.com/>.

:socrates :a :human.
:human :a :mortal.

{
  ?x :a ?y.
  ?y :a ?z
} => {
  ?x :a ?z 
}.

Running this will infer that :socrates :a :mortal.

Graph Terms and Quoted Formulas

# examples/superman.n3
@prefix : <http://example.com/>.

:steven :says { :superman :can :fly }.

{
  :steven :says ?x
} => ?x.

This demonstrates unquoting - the formula { :superman :can :fly } is extracted and asserted.

As a Python Library

from rdflib import Graph
from knom.stratified import stratified
from knom.util import split_rules_and_facts

# Load your N3 file
g = Graph().parse("your_file.n3")

# Split into rules and facts
rules, facts = split_rules_and_facts(g)

# Run stratified inference
inferred = stratified(facts, rules)

# Serialize the results
print(inferred.serialize(format="n3"))

Built-in Predicates

Knom supports a growing set of N3 built-in predicates:

Logic Built-ins

• log:includes - Tests if one graph includes another
• log:forAllIn - Universal quantification over a graph

Math Built-ins

• math:lessThan - Numeric less-than comparison
• math:greaterThan - Numeric greater-than comparison
• math:notLessThan - Numeric greater-than-or-equal comparison
• math:notGreaterThan - Numeric less-than-or-equal comparison

String Built-ins

• string:ord - Character/string ordering operations
• string:notLessThan - String comparison
• string:notGreaterThan - String comparison

Development

Running Tests

The project uses pytest for testing:

# Run all tests
pytest

# Run with coverage
pytest --cov=knom

# Run specific test file
pytest tests/test_stratify_rules.py

Code Quality

The project uses ruff for linting and formatting:

# Check linting
ruff check .

# Format code
ruff format .

# Type checking (if configured)
mypy knom

Project Structure

knom/
├── knom/                 # Main package
│   ├── __init__.py      # Core inference engine
│   ├── stratified.py    # Stratified reasoning implementation
│   ├── typing.py        # Type definitions
│   ├── builtins/        # Built-in predicate implementations
│   └── util/            # Utility functions
├── tests/               # Test suite
│   └── n3/             # N3 test files
├── examples/           # Example N3 files
└── tools/              # Command-line tools

How It Works

Knom implements a forward-chaining inference engine with stratified evaluation:

1. Rule Analysis: Rules are analyzed to detect dependencies and potential recursion
2. Stratification: Rules are organized into strata (layers) based on their dependencies
3. Inference: Each stratum is evaluated in order, with recursive rules handled specially
4. Saturation: The process continues until no new facts can be derived

The stratified approach ensures termination for well-founded rule sets and efficient evaluation of recursive rules.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Development Setup

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (pytest)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Code Style

• Follow PEP 8 guidelines
• Use type hints where appropriate
• Add tests for new features
• Update documentation as needed

Roadmap

• Additional N3 built-in predicates
• Performance optimizations for large rule sets
• Better error messages and debugging support
• Better lists handling
• Integration with existing RDF tools and libraries

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Acknowledgments

• The N3 community for the language specification
• RDFLib for RDF processing capabilities
• Contributors and users of the project

Links

• Notation3 Introduction
• N3 Specification
• RDFLib Documentation

Citation

If you use Knom in your research, please cite:

@software{knom2024,
  author = {Yusupov, Eldar},
  title = {Knom: A Knowledge Machine for Notation3},
  year = {2024},
  url = {https://github.com/eyusupov/knom}
}