json_path

json_path

Lightweight JSON dot-path extractor for instrument output parsing.

Used by the instrument plugin system (PluginCliBackend) to extract result text, error messages, and token counts from CLI instrument output. This is NOT full JSONPath — it's a minimal extractor covering the patterns observed across all researched CLI instruments.

Supported syntax

key — top-level key key.subkey — nested access key[0] — array index key. — wildcard: iterate all values, return first match key..subkey — wildcard with nested access

Examples:

extract_json_path(data, "result") → data["result"] extract_json_path(data, "error.message") → data["error"]["message"] extract_json_path(data, "items[0]") → data["items"][0] extract_json_path(data, "models.*.tokens") → first data["models"][k]["tokens"]

Functions

extract_json_path

extract_json_path(data, path)

Extract a value from nested data using a dot-path.

Returns the first matching value, or None if the path doesn't resolve. Wildcards (*) iterate all values in a dict and return the first match.

Parameters:

Name	Type	Description	Default
data	Any	Parsed JSON data (typically a dict).	required
path	str	Dot-separated path string, e.g. "error.message", "models.*.tokens".	required

Returns:

Type	Description
Any | None	The extracted value, or None if not found.

Source code in src/marianne/utils/json_path.py

def extract_json_path(data: Any, path: str) -> Any | None:
    """Extract a value from nested data using a dot-path.

    Returns the first matching value, or None if the path doesn't resolve.
    Wildcards (*) iterate all values in a dict and return the first match.

    Args:
        data: Parsed JSON data (typically a dict).
        path: Dot-separated path string, e.g. "error.message", "models.*.tokens".

    Returns:
        The extracted value, or None if not found.
    """
    if not path or data is None:
        return None

    segments = path.split(".")
    current: Any = data

    for i, segment in enumerate(segments):
        if current is None:
            return None

        if segment == "*":
            # Wildcard: iterate all values, recurse with remaining path
            if not isinstance(current, dict):
                return None
            remaining = ".".join(segments[i + 1:])
            if not remaining:
                # Wildcard at end — return first value
                for val in current.values():
                    return val
                return None
            for val in current.values():
                result = extract_json_path(val, remaining)
                if result is not None:
                    return result
            return None

        current = _extract_segment(current, segment)

    return current

extract_json_path_all

extract_json_path_all(data, path)

Extract ALL matching values from nested data using a dot-path.

Like extract_json_path but collects all wildcard matches instead of returning only the first. Useful for aggregating token counts across multiple models.

Parameters:

Name	Type	Description	Default
data	Any	Parsed JSON data (typically a dict).	required
path	str	Dot-separated path string with wildcards.	required

Returns:

Type	Description
list[Any]	List of all matching values (may be empty).

Source code in src/marianne/utils/json_path.py

def extract_json_path_all(data: Any, path: str) -> list[Any]:
    """Extract ALL matching values from nested data using a dot-path.

    Like extract_json_path but collects all wildcard matches instead of
    returning only the first. Useful for aggregating token counts across
    multiple models.

    Args:
        data: Parsed JSON data (typically a dict).
        path: Dot-separated path string with wildcards.

    Returns:
        List of all matching values (may be empty).
    """
    if not path or data is None:
        return []

    segments = path.split(".")
    return _collect_all(data, segments, 0)