ATLAS.Kernel.JsonEngine 0.0.1

ATLAS.Kernel.JsonEngine - JSON Query, Graph & AI Engine

ATLAS platform JSON processing library. Provides:

• JSON Core: parse JSON, navigate with simplified JSONPath/dot paths, and evaluate basic conditions.
• SQL over JSON: run a compact SELECT / FROM / WHERE / ORDER BY / LIMIT dialect over JsonNode arrays.
• Graph operations: build dependency graphs from JSON, traverse with BFS/DFS, find paths, and calculate PageRank.
• Indexes: simple, composite, and lightweight full-text in-memory indexes.
• AI Query pipeline: translate simple natural language into an executable AI QUERY pipeline.

Current project files and namespaces are named ATLAS.Kernel.JsonEngine. The README keeps ATLAS.Kernel.JsonEngine as the public library name, but code examples use the namespace that exists in source.

Architecture

ATLAS.Kernel.JsonEngine/
+-- Source/
|   +-- ATLAS.Kernel.JsonEngine/                <- Core library
|   |   +-- JsonCore.cs                          <- JSON parsing, path navigation, typed getters, conditions
|   |   +-- SQL/
|   |   |   +-- JsonSqlEngine.cs                 <- SQL-like query executor over JsonNode arrays
|   |   |   +-- Interfaces/
|   |   |       +-- IJsonSqlEngine.cs            <- Injectable SQL engine contract
|   |   +-- Graph/
|   |   |   +-- JsonGraph.cs                     <- Graph builder, BFS, DFS, path finding, PageRank
|   |   |   +-- Interfaces/
|   |   |       +-- IJsonGraph.cs                <- Injectable graph contract
|   |   +-- Index/
|   |   |   +-- JsonIndexEngine.cs               <- Simple, composite, and full-text indexes
|   |   +-- AI/
|   |       +-- JsonAiNl.cs                      <- Rule-based natural language to AI QUERY translator
|   |       +-- JsonAiEngine.cs                  <- AI QUERY execution pipeline
|   |
|   +-- ATLAS.Kernel.JsonEngine.Benchmark/       <- BenchmarkDotNet performance harness
|       +-- Benchmark.cs
|       +-- Program.cs
|
+-- SourceClient/
|   +-- ATLAS.Kernel.JsonEngine.Client.csproj   <- Console demo project
|   +-- Program.cs                               <- End-to-end demo: JSON -> graph -> NL -> AI QUERY
|
+-- Tests/
    +-- ATLAS.Kernel.JsonEngine.Tests/           <- xUnit + Moq tests
        +-- JsonCoreTests.cs
        +-- JsonGraphTests.cs
        +-- JsonAiNlTests.cs
        +-- JsonAiEngineTests.cs
        +-- JsonAiEngineMoqTests.cs

Applied Design Principles

Requirements

No database, Redis, Docker, or external service is required.

Quick Start

# 1. Restore dependencies
dotnet restore ATLAS.Kernel.JsonEngine.slnx

# 2. Build the solution
dotnet build ATLAS.Kernel.JsonEngine.slnx

# 3. Run tests
dotnet test ATLAS.Kernel.JsonEngine.slnx

# 4. Run the console demo
dotnet run --project SourceClient/ATLAS.Kernel.JsonEngine.Client.csproj

Add as a Project Reference

dotnet add <your-project>.csproj reference Source/ATLAS.Kernel.JsonEngine/ATLAS.Kernel.JsonEngine.csproj

Basic Usage

using ATLAS.Kernel.JsonEngine;

var root = JsonCore.Parse("""
{
  "item": {
    "id": "A",
    "name": "Motor",
    "price": { "value": 120 }
  }
}
""")!;

var id = JsonCore.GetString(root, "item.id");
var price = JsonCore.GetDouble(root, "item.price.value");
var expensive = JsonCore.EvalCondition(root["item"]!, "price.value > 50");

JSONPath Navigation

var node = JsonCore.JsonPath(root, "$.item.price.value");

Supported path style:

JsonCore.Get(...), GetString(...), and GetDouble(...) use simple dot paths such as item.price.value.

SQL over JSON

JsonSqlEngine executes a small SQL-like dialect over JSON arrays.

using ATLAS.Kernel.JsonEngine;
using ATLAS.Kernel.JsonEngine.SQL;

var root = JsonCore.Parse("""
{
  "items": [
    { "id": "A", "name": "Motor", "price": { "value": 120 } },
    { "id": "B", "name": "Bolt", "price": { "value": 5 } },
    { "id": "C", "name": "Shaft", "price": { "value": 40 } }
  ]
}
""")!;

var sql = new JsonSqlEngine();

var rows = sql.Execute(root, """
SELECT id, name, price.value
FROM $.items[*]
WHERE price.value > 20
ORDER BY name ASC
LIMIT 10
""");

Supported SQL Clauses

Supported Condition Operators

Graph Engine

JsonGraph builds a directed graph from JSON nodes. Each node is stored by an ID field, and edges are read from a dependency array.

using ATLAS.Kernel.JsonEngine;
using ATLAS.Kernel.JsonEngine.Graph;

var root = JsonCore.Parse("""
{
  "items": [
    { "id": "A", "dependencies": ["B", "C"] },
    { "id": "B", "dependencies": [] },
    { "id": "C", "dependencies": ["B"] }
  ]
}
""")!;

var graph = new JsonGraph();
graph.Build(root, "$.items", "id", "dependencies");

var bfs = graph.Bfs("A");
var dfs = graph.Dfs("A");
var path = graph.FindPath("A", "B");
var pageRank = graph.PageRank();

Graph Methods

Index Engine

JsonIndexEngine creates in-memory indexes over a JsonArray.

using ATLAS.Kernel.JsonEngine;
using ATLAS.Kernel.JsonEngine.Index;

var items = JsonCore.JsonPath(root, "$.items")!.AsArray();

var byName = JsonIndexEngine.BuildSimpleIndex(items, "name");
var motors = JsonIndexEngine.Find(byName, "Motor");

var byNameAndPrice = JsonIndexEngine.BuildCompositeIndex(items, "name", "price.value");
var matches = JsonIndexEngine.FindComposite(byNameAndPrice, "Motor", "120");

var fullText = JsonIndexEngine.BuildFullTextIndex(items, "name");
var search = JsonIndexEngine.FullTextSearch(fullText, "motor");

AI QUERY Pipeline

JsonAiEngine executes a small pipeline language intended for JSON search, graph expansion, ranking, and projection.

AI QUERY:
  FIND items WHERE price.value > 50
  THEN GRAPH EXPAND dependencies[*] UP TO 3 LEVELS
  THEN RANK BY PAGERANK
  RETURN id, name, price.value

Pipeline Steps

Natural Language Helper

JsonAiNl.ToAiQuery(...) is a rule-based helper that converts simple supported user text into an AI QUERY.

using ATLAS.Kernel.JsonEngine.AI;

var aiQuery = JsonAiNl.ToAiQuery(
    "Muestrame los items caros y sus dependencias ordenadas por importancia"
);

The current rule set is Spanish-oriented and recognizes these patterns:

End-to-End Execution

using ATLAS.Kernel.JsonEngine;
using ATLAS.Kernel.JsonEngine.AI;
using ATLAS.Kernel.JsonEngine.Graph;
using ATLAS.Kernel.JsonEngine.SQL;

var root = JsonCore.Parse(jsonText)!;

var graph = new JsonGraph();
graph.Build(root, "$.items", "id", "dependencias");

var sqlEngine = new JsonSqlEngine();
var aiQuery = JsonAiNl.ToAiQuery(
    "Muestrame los items caros y sus dependencias ordenadas por importancia"
);

var result = JsonAiEngine.Execute(root, graph, aiQuery, sqlEngine);

Testing and Mocking

The AI pipeline accepts IJsonGraph and IJsonSqlEngine, so tests can isolate behavior with mocks.

var result = JsonAiEngine.Execute(
    root,
    mockGraph.Object,
    aiQuery,
    mockSql.Object
);

Run the full test suite:

dotnet test ATLAS.Kernel.JsonEngine.slnx

Run only the test project:

dotnet test Tests/ATLAS.Kernel.JsonEngine.Tests/ATLAS.Kernel.JsonEngine.Tests.csproj

With coverage:

dotnet test --collect:"XPlat Code Coverage"

Benchmarks

Run BenchmarkDotNet benchmarks:

dotnet run -c Release --project Source/ATLAS.Kernel.JsonEngine.Benchmark/ATLAS.Kernel.JsonEngine.Benchmark.csproj

Current benchmark coverage:

Limitations

This library intentionally implements compact in-memory engines, not full standards-compliant parsers.

Versioning

Directory.Build.props currently defines:

License

This project is distributed under the GNU General Public License v3.0 (GPL-3.0).

This means the software is free to use, modify, and redistribute, provided that:

• The original copyright notice is preserved.
• Proper attribution is given to the original creators.
• Any derivative work distributed must remain under the same GPL license terms.

For full license terms, see the LICENSE file included in this repository.