Implementation:Mlc ai Mlc llm JSON Parser

Overview

The JSON Parser header at cpp/support/json_parser.h provides a comprehensive set of utilities for parsing JSON strings and extracting typed values from JSON objects and arrays. Built on top of the picojson library, it offers both exception-throwing and Result-returning variants of lookup functions, making it suitable for both strict validation and graceful error handling contexts within MLC LLM.

Purpose

JSON configuration is pervasive in MLC LLM -- model configs, engine configs, and generation parameters are all represented as JSON. This header centralizes JSON parsing logic and provides:

• String-to-object parsing with and without result-based error handling.
• Typed key lookup from JSON objects with required, optional, and default-value semantics.
• Typed index lookup from JSON arrays.
• Template specializations for TVM-specific types such as DataType and symbolic shape tuples.
• Result-returning variants of all lookup functions for non-throwing error propagation.

Core Parsing Functions

ParseToJSONObject

inline picojson::object ParseToJSONObject(const std::string& json_str);

Parses a JSON string into a picojson::object. Uses CHECK macros to assert that parsing succeeds and the result is indeed a JSON object, making it suitable for cases where malformed input should be a fatal error.

ParseToJSONObjectWithResultReturn

inline Result<picojson::object> ParseToJSONObjectWithResultReturn(const std::string& json_str);

A non-throwing alternative that returns a Result<picojson::object>. On parse failure or type mismatch, it returns a Result::Error containing a descriptive error message.

Lookup Functions

The header provides a family of Lookup function templates with several variants:

Required Lookup

template <typename ValueType>
ValueType Lookup(const picojson::object& json, const std::string& key);

template <typename ValueType>
ValueType Lookup(const picojson::array& json, int index);

Retrieves a value by key (from an object) or by index (from an array), asserting that the key/index exists and the value has the expected type. Throws on failure via CHECK.

Lookup with Default

template <typename ValueType>
inline ValueType LookupOrDefault(const picojson::object& json, const std::string& key,
                                 const ValueType& default_value);

Returns the default value if the key is missing or the value is null. Asserts correct type if the key is present.

Optional Lookup

template <typename ValueType>
inline std::optional<ValueType> LookupOptional(const picojson::object& json,
                                               const std::string& key);

Returns std::nullopt if the key is missing or null. Asserts correct type if present.

Result-Returning Variants

Each of the above has a corresponding *WithResultReturn version:

template <typename ValueType>
inline Result<ValueType> LookupWithResultReturn(const picojson::object& json,
                                                const std::string& key);

template <typename ValueType>
inline Result<ValueType> LookupOrDefaultWithResultReturn(const picojson::object& json,
                                                         const std::string& key,
                                                         const ValueType& default_value);

template <typename ValueType>
inline Result<std::optional<ValueType>> LookupOptionalWithResultReturn(
    const picojson::object& json, const std::string& key);

These return Result::Error instead of throwing when keys are missing or types mismatch, enabling error propagation without exceptions.

Template Specializations

DataType

template <>
inline tvm::runtime::DataType Lookup(const picojson::object& json, const std::string& key);

template <>
inline tvm::runtime::DataType Lookup(const picojson::array& json, int index);

Specializations that first look up the value as a std::string, then convert it to a tvm::runtime::DataType via details::DTypeFromString.

SymShapeTuple

The SymShapeTuple struct represents shapes that may contain symbolic dimension names:

struct SymShapeTuple {
  tvm::ffi::Shape shape_values;
  std::vector<std::string> sym_names;

  tvm::ffi::Shape ToStatic(const picojson::object& model_config);
};

Each dimension is either a concrete int64_t value or a symbolic name (stored as -1 in shape_values with the name in sym_names). The ToStatic method resolves symbolic names by looking up their values in a model configuration JSON object.

Template specializations for Lookup and LookupOrDefault on SymShapeTuple parse JSON arrays that may contain mixed integers and strings.

Helper Namespace: details

namespace details {
  inline tvm::runtime::DataType DTypeFromString(const std::string& s);
  inline SymShapeTuple SymShapeTupleFromArray(const picojson::array& shape);
}

• DTypeFromString -- Converts a string representation (e.g., "float32") to a TVM DataType.
• SymShapeTupleFromArray -- Parses a JSON array of integers and strings into a SymShapeTuple.

Dependencies

• picojson.h -- Underlying JSON library.
• tvm/ffi/container/shape.h -- TVM shape container.
• tvm/runtime/data_type.h -- TVM data type support.
• tvm/runtime/logging.h -- CHECK assertion macros.
• result.h -- The Result<T> type for non-throwing error handling.

File Location

• Source file: cpp/support/json_parser.h
• Namespace: mlc::llm::json
• Header guard: MLC_LLM_SUPPORT_JSON_PARSER_H_