feat(json): introduce ujson bridge and dual-backend JSON support

Author: wangzhaode

.github/workflows/build.yml

@@ -9,6 +9,9 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        backend: [nlohmann, rapidjson]
 
     steps:
     - uses: actions/checkout@v3
@@ -22,7 +25,11 @@ jobs:
       run: |
         mkdir build
         cd build
-        cmake ..
+        if [ "${{ matrix.backend }}" = "rapidjson" ]; then
+          cmake .. -DUJSON_USE_RAPIDJSON=ON
+        else
+          cmake ..
+        fi
         make
 
     - name: Run Tests

CMakeLists.txt

@@ -8,7 +8,13 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 add_library(jinja INTERFACE)
 target_include_directories(jinja INTERFACE . third_party)
 
+option(UJSON_USE_RAPIDJSON "Use RapidJSON backend" OFF)
+if(UJSON_USE_RAPIDJSON)
+    add_definitions(-DUJSON_USE_RAPIDJSON)
+    include_directories(third_party/rapidjson/include)
+endif()
+
 # Test
 enable_testing()
 add_executable(test_main tests/test_main.cpp)
-target_link_libraries(test_main jinja)
+target_link_libraries(test_main jinja)

README.md

@@ -11,15 +11,21 @@ It focuses on supporting the subset of Jinja2 used by modern Large Language Mode
 ## Features
 
 - **C++11 Compatible**: Ensures maximum compatibility across older compiler versions and embedded systems.
-- **Lightweight**: Minimal dependencies (only `nlohmann/json`).
+- **Flexible JSON Backend**: Supports both `nlohmann/json` (default) and `RapidJSON` via a unified `ujson` bridge.
+- **Lightweight**: Minimal dependencies, with all required headers included in `third_party/`.
 - **LLM Focused**: Native support for `messages`, `tools`, `add_generation_prompt`, and special tokens.
-- **Strictly Typed**: Uses `nlohmann::json` for context management.
+- **Unified Context**: Uses `jinja::json` (an alias to `ujson::json`) for seamless context management.
 - **Custom Function Interop**: Easily inject C++ functions (e.g., `strftime_now`) into templates.
-- **Robust**: Validated against official Python `transformers` outputs using fuzzy matching tests.
+- **Robust**: Validated against official Python `transformers` outputs using fuzzy matching tests on 390+ cases.
 
 ## Integration
 
-The library is a single header file. Just copy `jinja.hpp` to your project's include directory (or root).
+### Headers
+The library consists of two main headers:
+- `jinja.hpp`: Core template engine.
+- `third_party/ujson.hpp`: Unified JSON bridge.
+
+Just copy the `jinja.hpp` and `third_party` directory to your project.
 
 ### Feature Checking (Versioning)
 
@@ -58,6 +64,13 @@ cmake ..
 make
 ```
 
+### Enable RapidJSON Backend
+To use `RapidJSON` instead of `nlohmann/json` for better performance:
+```bash
+cmake .. -DUJSON_USE_RAPIDJSON=ON
+```
+*Note: Ensure `third_party/rapidjson` is available.*
+
 ### Run Tests
 
 The project includes a comprehensive test suite based on real-world model templates.
@@ -78,7 +91,7 @@ int main() {
     std::string template_str = "Hello {{ name }}!";
     jinja::Template tpl(template_str);
 
-    nlohmann::json context;
+    jinja::json context;
     context["name"] = "World";
 
     std::string result = tpl.render(context);
@@ -96,15 +109,15 @@ int main() {
 std::string chat_template_str = "...";
 jinja::Template tpl(chat_template_str);
 
-nlohmann::json messages = nlohmann::json::array({
+jinja::json messages = jinja::json::array({
     {{"role", "user"}, {"content", "Hello!"}}
 });
 
 // Apply template
 std::string prompt = tpl.apply_chat_template(
     messages,
     true, // add_generation_prompt
-    nlohmann::json::array() // tools
+    jinja::json::array() // tools
 );
 ```
 
@@ -113,7 +126,7 @@ std::string prompt = tpl.apply_chat_template(
 You can register custom C++ functions to be called from within the template.
 
 ```cpp
-tpl.add_function("strftime_now", [](const std::vector<nlohmann::json>& args) {
+tpl.add_function("strftime_now", [](const std::vector<jinja::json>& args) {
     // Return current time string
     return "2025-12-16";
 });

README_CN.md

@@ -11,12 +11,12 @@
 ## 特性
 
 - **C++11 兼容**：确保在旧版编译器和嵌入式系统上的最大兼容性。
-- **易于集成**：核心库仅包含**一个头文件** (`jinja.hpp`，位于根目录)，非常方便拷贝并集成到任何项目中。
-- **轻量级**：依赖极少 (仅依赖 `nlohmann/json`，已包含在项目中)。
+- **灵活的 JSON 后端**：通过统一的 `ujson` 桥接层支持 `nlohmann/json` (默认) 和 `RapidJSON`。
+- **轻量级**：依赖极少，所有必要头文件均已包含在 `third_party/` 目录下。
 - **专注 LLM**：原生支持 `messages`, `tools`, `add_generation_prompt` 以及特殊 token 的处理。
-- **类型安全**：使用 `nlohmann::json` 进行上下文管理。
+- **统一上下文**：使用 `jinja::json` (即 `ujson::json` 的别名) 进行无缝的上下文管理。
 - **自定义函数**：支持轻松注入 C++ 函数 (如 `strftime_now`) 到模板中。
-- **健壮性**：通过模糊匹配测试，与官方 Python `transformers` 输出进行对齐验证。
+- **健壮性**：通过 390+ 条测试用例验证，与官方 Python `transformers` 输出进行对齐。
 
 ## 支持的模型
 
@@ -43,6 +43,13 @@ cmake ..
 make
 ```
 
+### 开启 RapidJSON 后端
+为了获得更好的性能，可以切换到 `RapidJSON` 后端：
+```bash
+cmake .. -DUJSON_USE_RAPIDJSON=ON
+```
+*注：请确保 `third_party/rapidjson` 存在。*
+
 ### 运行测试
 
 本项目包含一个基于真实模型模板的全面测试套件。
@@ -63,7 +70,7 @@ int main() {
     std::string template_str = "Hello {{ name }}!";
     jinja::Template tpl(template_str);
 
-    nlohmann::json context;
+    jinja::json context;
     context["name"] = "World";
 
     std::string result = tpl.render(context);
@@ -81,15 +88,15 @@ int main() {
 std::string chat_template_str = "...";
 jinja::Template tpl(chat_template_str);
 
-nlohmann::json messages = nlohmann::json::array({
+jinja::json messages = jinja::json::array({
     {{"role", "user"}, {"content", "你好！"}}
 });
 
 // 应用模板
 std::string prompt = tpl.apply_chat_template(
     messages,
     true, // add_generation_prompt
-    nlohmann::json::array() // tools
+    jinja::json::array() // tools
 );
 ```
 
@@ -98,7 +105,7 @@ std::string prompt = tpl.apply_chat_template(
 你可以注册自定义 C++ 函数，供模板内部调用。
 
 ```cpp
-tpl.add_function("strftime_now", [](const std::vector<nlohmann::json>& args) {
+tpl.add_function("strftime_now", [](const std::vector<jinja::json>& args) {
     // 返回当前时间字符串
     return "2025-12-16";
 });

doc/implementation_details.md

@@ -27,7 +27,7 @@ The engine follows a standard compiler/interpreter pipeline:
 3.  **AST (`Node` hierarchy)**:
     *   Base `Node` class with virtual `render(Context&, string& out)` method.
     *   Nodes: `TextNode`, `PrintNode`, `ForStmt`, `IfNode`, `SetNode`, `MacroNode`.
-    *   Expressions (`Expr` hierarchy) evaluate to `nlohmann::json` values.
+    *   Expressions (`Expr` hierarchy) evaluate to `jinja::json` values.
 
 4.  **Interpreter / Renderer (`Template::render`)**:
     *   Iterates through root nodes and calls `render`.
@@ -65,8 +65,11 @@ The engine follows a standard compiler/interpreter pipeline:
 
 ## Key Implementation Features
 
-### 1. JSON Data Model
-We utilize `nlohmann::json` as the unified data type for all variables. This simplifies type checking and allows easy integration with JSON-based LLM APIs.
+### 1. Unified JSON Bridge (`ujson`)
+We utilize a custom bridge layer called `ujson` (Universal JSON) to abstract the underlying JSON library.
+*   **Default**: Uses `nlohmann/json` for ease of use and standard compliance.
+*   **High Performance**: Supports `RapidJSON` (via `UJSON_USE_RAPIDJSON`) for faster parsing and reduced memory overhead, which is critical for high-throughput LLM serving.
+*   **Abstraction**: All internal logic uses `ujson::json`, exposed as `jinja::json` to the user.
 
 ### 2. Custom Function / Filter Dispatch
 *   **Filters**: Implemented in `FilterExpr`. Standard Jinja2 filters like `safe`, `tojson`, `trim`, `lower` are hardcoded.

doc/implementation_details_CN.md

@@ -27,7 +27,7 @@
 3.  **抽象语法树 (AST - `Node` 层次结构)**:
     *   基类 `Node` 具有虚函数 `render(Context&, string& out)`。
     *   节点类型：`TextNode`, `PrintNode`, `ForStmt`, `IfNode`, `SetNode`, `MacroNode`。
-    *   表达式 (`Expr` 层次结构) 计算结果为 `nlohmann::json` 值。
+    *   表达式 (`Expr` 层次结构) 计算结果为 `jinja::json` 值。
 
 4.  **解释器 / 渲染器 (Interpreter / Renderer - `Template::render`)**:
     *   遍历根节点并调用 `render`。
@@ -65,8 +65,11 @@
 
 ## 关键实现特性
 
-### 1. JSON 数据模型
-我们使用 `nlohmann::json` 作为所有变量的统一数据类型。这简化了类型检查，并允许与基于 JSON 的 LLM API 轻松集成。
+### 1. 统一 JSON 桥接层 (`ujson`)
+我们实现了一个名为 `ujson` (Universal JSON) 的轻量级桥接层，用于抽象底层的 JSON 库。
+*   **默认配置**：使用 `nlohmann/json`，兼顾易用性和标准兼容性。
+*   **高性能需求**：支持 `RapidJSON` 后端 (通过 `UJSON_USE_RAPIDJSON` 开启)，提供更快的解析速度和更低的内存开销，这对于高并发的 LLM 推理服务至关重要。
+*   **抽象封装**：内部所有逻辑均基于 `ujson::json` 编写，并通过 `jinja::json` 别名暴露给用户。
 
 ### 2. 自定义函数 / 过滤器分发
 *   **过滤器 (Filters)**: 在 `FilterExpr` 中实现。标准的 Jinja2 过滤器如 `safe`, `tojson`, `trim`, `lower` 是硬编码的。

jinja.hpp

@@ -15,19 +15,23 @@
  limitations under the License.
  */
 
-#pragma once
-
 #include <string>
-#include <memory>
 #include <vector>
 #include <map>
 #include <functional>
-#include <algorithm>
+#include <memory>
 #include <sstream>
+#include <algorithm>
 #include <iostream>
+#include <fstream>
+#include <regex>
+#include <initializer_list>
+#include <ctime>
+#include <iomanip>
+#include <chrono>
 
 // External dependency: nlohmann/json
-#include <nlohmann/json.hpp>
+#include "third_party/ujson.hpp"
 
 #define JINJA_VERSION_MAJOR 0
 #define JINJA_VERSION_MINOR 0
@@ -42,8 +46,9 @@
 
 namespace jinja {
 
-using json = nlohmann::json;
-using json = nlohmann::json;
+using json = ujson::json;
+
+
 using Argument = std::pair<std::string, json>;
 using UserFunction = std::function<json(const std::vector<Argument>&)>;
 
@@ -558,8 +563,6 @@ class Lexer {
 
 
 // --- Helpers ---
-using json = nlohmann::json;
-
 class Context; // Forward declaration
 
 struct Node {
@@ -571,7 +574,12 @@ struct Macro;
 
 // Forward declarations
 static bool is_truthy(const json& val);
-static const json UNDEFINED = {{"__jinja_undefined__", true}};
+static json undefined_init() {
+    json j = json::object();
+    j["__jinja_undefined__"] = true;
+    return j;
+}
+static const json UNDEFINED = undefined_init();
 
 inline bool is_undefined(const json& val) {
     return val.is_object() && val.contains("__jinja_undefined__");
@@ -619,27 +627,25 @@ class Context {
         return nullptr;
     }
 
-    json& get(const std::string& name) {
+    json get(const std::string& name) {
         // Search from top to bottom
         for (auto it = scopes.rbegin(); it != scopes.rend(); ++it) {
             if (it->contains(name)) {
                 return (*it)[name];
             }
         }
         JINJA_LOG("Context: Variable '" << name << "' not found, returning UNDEFINED");
-        static json undefined_val = UNDEFINED;
-        return undefined_val;
+        return UNDEFINED;
     }
 
-    const json& get(const std::string& name) const {
+    json get(const std::string& name) const {
         // Const version
         for (auto it = scopes.rbegin(); it != scopes.rend(); ++it) {
             if (it->contains(name)) {
                 return (*it)[name];
             }
         }
-        static const json undefined_val = UNDEFINED;
-        return undefined_val;
+        return UNDEFINED;
     }
 
     void set(const std::string& name, json val) {
@@ -1284,7 +1290,7 @@ struct SetNode : Node {
             // But Expr::evaluate returns value. We need reference.
             // Context needs to support getting reference.
             if (auto* var = dynamic_cast<VarExpr*>(attr->object.get())) {
-                 json& obj = context.get(var->name);
+                 json obj = context.get(var->name);
                  if (!obj.is_null()) {
                      obj[attr->name] = val;
                  }

tests/test_main.cpp

@@ -8,10 +8,9 @@
 #include <regex>
 // #define JINJA_DEBUG
 #include "jinja.hpp"
-#include <nlohmann/json.hpp>
 #include <chrono>
 
-using json = nlohmann::json;
+using json = ujson::json;
 
 namespace Color {
     const std::string RESET   = "\033[0m";
@@ -92,7 +91,7 @@ int main(int argc, char** argv) {
         if (!model_filter.empty() && model_id.find(model_filter) == std::string::npos) {
             continue;
         }
-        json& model_data = it.value();
+        json model_data = it.value();
         total_models++;
 
         std::cout << "\n" << Color::BLUE << Color::BOLD << "┏━━ Model: " << model_id << Color::RESET << std::endl;
@@ -225,4 +224,4 @@ int main(int argc, char** argv) {
         std::cout << "\n✨ All tests passed! ✨" << std::endl;
         return 0;
     }
-}
+}