flextool 4.0.0__py3-none-any.whl

flextool/model_builder/build_model.py

@@ -0,0 +1,589 @@
+"""Mock-up model builder for FlexTool.
+
+Reads a YAML specification and generates a FlexTool-compatible JSON file
+that can be imported into an initialized Spine database.
+"""
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import yaml
+
+from flextool.model_builder.encoding import (
+    make_array,
+    make_map,
+    make_time_series,
+    model_data_to_json_serializable,
+    param_value,
+)
+from flextool.model_builder.names import get_location_names
+from flextool.model_builder.profiles import (
+    generate_autocorrelated_series,
+    generate_constant_series,
+    pert_integer_sample,
+    pert_sample,
+)
+
+
+class ModelBuilder:
+    """Builds a FlexTool model JSON from a YAML specification."""
+
+    def __init__(self, spec: dict, seed: int | None = None):
+        self.spec = spec
+        self.rng = np.random.default_rng(seed)
+        self.profile_length: int = spec.get("profile_lengths", 8760)
+        self.alternative = "generated"
+        self.scenario = "generated_scenario"
+
+        # Accumulators for JSON output
+        self.entities: list[list] = []
+        self.parameter_values: list[list] = []
+        self.entity_alternatives: list[list] = []
+
+        # Internal tracking
+        self.location_names: dict[str, list[str]] = {}  # group -> [names]
+        self.location_distances: dict[str, list[float]] = {}  # group -> [distances]
+        self.grid_nodes: dict[str, list[str]] = {}  # grid_name -> [node_names]
+        self.fuel_nodes: dict[str, str] = {}  # fuel_name -> node_name
+        self.profile_entities: set[str] = set()  # track created profile entities
+        self.timestep_keys: list[str] = [f"t{i+1:04d}" for i in range(self.profile_length)]
+
+    def build(self) -> dict:
+        """Execute the full build pipeline and return the JSON structure."""
+        self._build_node_locations()
+        self._build_grids()
+        self._build_fuels()
+        self._build_profiles_and_demand()
+        self._build_storages()
+        self._build_technologies()
+        self._build_model_infrastructure()
+
+        return {
+            "entities": self.entities,
+            "parameter_values": self.parameter_values,
+            "alternatives": [[self.alternative, "Generated by model_builder"]],
+            "scenarios": [[self.scenario, True, "Generated scenario"]],
+            "scenario_alternatives": [
+                [self.scenario, self.alternative, None]
+            ],
+            "entity_alternatives": self.entity_alternatives,
+        }
+
+    # -- Helpers --
+
+    def _add_entity(self, entity_class: str, name: str | list[str], description: str | None = None) -> None:
+        self.entities.append([entity_class, name, description])
+        self.entity_alternatives.append([entity_class, [name] if isinstance(name, str) else name, self.alternative, True])
+
+    def _add_param(self, entity_class: str, entity_name: str | list[str], parameter: str, value: Any) -> None:
+        self.parameter_values.append(
+            param_value(entity_class, entity_name, parameter, value, self.alternative)
+        )
+
+    # -- Node Locations --
+
+    def _build_node_locations(self) -> None:
+        node_locations = self.spec.get("node_locations", {})
+        for group_name, group_spec in node_locations.items():
+            count = group_spec["number"]
+            names = get_location_names(count)
+            self.location_names[group_name] = names
+
+            # Sample distances between consecutive nodes
+            dist = group_spec["distribution"]
+            distances = pert_sample(
+                self.rng, dist["min"], dist["mode"], dist["max"], size=count
+            ).tolist()
+            self.location_distances[group_name] = distances
+
+    # -- Grids --
+
+    def _build_grids(self) -> None:
+        grids = self.spec.get("grids", {})
+        for grid_name, grid_spec in grids.items():
+            node_group = grid_spec["node_group"]
+            locations = self.location_names.get(node_group, [])
+            if not locations:
+                continue
+
+            # Create grid nodes
+            node_names = [f"{loc}_{grid_name}" for loc in locations]
+            self.grid_nodes[grid_name] = node_names
+
+            # Create a group for this grid
+            group_name = f"grid_{grid_name}"
+            self._add_entity("group", group_name)
+
+            for node_name in node_names:
+                self._add_entity("node", node_name)
+                self._add_param("node", node_name, "node_type", "balance")
+                self._add_entity("group__node", [group_name, node_name])
+
+            # Connections
+            if "connections_per_node" in grid_spec:
+                self._build_connections(grid_name, grid_spec, node_group)
+
+    def _build_connections(self, grid_name: str, grid_spec: dict, node_group: str) -> None:
+        node_names = self.grid_nodes[grid_name]
+        distances = self.location_distances.get(node_group, [])
+        n_nodes = len(node_names)
+
+        if n_nodes < 2:
+            return
+
+        # Compute cumulative distance from first node (1D layout)
+        cum_dist = [0.0]
+        for i in range(1, n_nodes):
+            cum_dist.append(cum_dist[-1] + distances[i])
+
+        # Sample target connections per node
+        conn_spec = grid_spec["connections_per_node"]["distribution"]
+        target_conns = pert_integer_sample(
+            self.rng, conn_spec["min"], conn_spec["mode"], conn_spec["max"], size=n_nodes
+        )
+
+        # Track actual connection count per node
+        actual_conns = [0] * n_nodes
+        created_connections: set[tuple[int, int]] = set()
+
+        cost_per_kw_per_km = grid_spec.get("cost-per-kw-per-km", 0)
+        cost_per_kw = grid_spec.get("cost-per-kw", 0)
+        loss_per_100km = grid_spec.get("loss-per-100km", 0)
+
+        # Pass 1: chain consecutive nodes to guarantee a connected graph.
+        # On the 1D layout this is the minimum spanning tree.
+        for i in range(n_nodes - 1):
+            pair = (i, i + 1)
+            created_connections.add(pair)
+            actual_conns[i] += 1
+            actual_conns[i + 1] += 1
+            self._create_connection_entity(
+                node_names, cum_dist, pair, cost_per_kw, cost_per_kw_per_km, loss_per_100km
+            )
+
+        # Pass 2: add extra connections using nearest-neighbor logic,
+        # respecting the remaining target count per node.
+        for i in range(n_nodes):
+            if actual_conns[i] >= target_conns[i]:
+                continue
+
+            # Sort other nodes by distance
+            others = sorted(
+                range(n_nodes),
+                key=lambda j: abs(cum_dist[j] - cum_dist[i])
+            )
+
+            for j in others:
+                if j == i:
+                    continue
+                if actual_conns[i] >= target_conns[i]:
+                    break
+                if actual_conns[j] >= target_conns[j]:
+                    continue
+                pair = (min(i, j), max(i, j))
+                if pair in created_connections:
+                    continue
+
+                created_connections.add(pair)
+                actual_conns[i] += 1
+                actual_conns[j] += 1
+                self._create_connection_entity(
+                    node_names, cum_dist, pair, cost_per_kw, cost_per_kw_per_km, loss_per_100km
+                )
+
+    def _create_connection_entity(
+        self,
+        node_names: list[str],
+        cum_dist: list[float],
+        pair: tuple[int, int],
+        cost_per_kw: float,
+        cost_per_kw_per_km: float,
+        loss_per_100km: float,
+    ) -> None:
+        """Create a single connection entity with its parameters."""
+        node_a = node_names[pair[0]]
+        node_b = node_names[pair[1]]
+        conn_name = f"conn_{node_a}__{node_b}"
+        dist_km = abs(cum_dist[pair[1]] - cum_dist[pair[0]])
+
+        self._add_entity("connection", conn_name)
+        self._add_entity("connection__node__node", [conn_name, node_a, node_b])
+
+        invest_cost = cost_per_kw + cost_per_kw_per_km * dist_km
+        self._add_param("connection", conn_name, "invest_cost", invest_cost)
+        self._add_param("connection", conn_name, "invest_method", "invest_no_limit")
+        self._add_param("connection", conn_name, "transfer_method", "regular")
+        self._add_param("connection", conn_name, "lifetime", 40)
+        self._add_param("connection", conn_name, "discount_rate", 0.05)
+
+        if loss_per_100km > 0 and dist_km > 0:
+            efficiency = max(0.01, 1.0 - (loss_per_100km * dist_km / 100.0))
+            self._add_param("connection", conn_name, "efficiency", efficiency)
+
+    # -- Fuels --
+
+    def _build_fuels(self) -> None:
+        fuels = self.spec.get("fuels", {})
+        for fuel_name, fuel_spec in fuels.items():
+            # Create commodity
+            self._add_entity("commodity", fuel_name)
+            self._add_param("commodity", fuel_name, "price", fuel_spec["price"])
+
+            # Create fuel node (single node for the whole model)
+            node_name = f"{fuel_name}_source"
+            self._add_entity("node", node_name)
+            self._add_param("node", node_name, "node_type", "balance")
+            self.fuel_nodes[fuel_name] = node_name
+
+            # Link commodity to node
+            self._add_entity("commodity__node", [fuel_name, node_name])
+
+    # -- Profiles & Demand --
+
+    def _build_profiles_and_demand(self) -> None:
+        profile_specs = self.spec.get("profiles", {})
+        grids = self.spec.get("grids", {})
+
+        # Build demand for each grid
+        for grid_name, grid_spec in grids.items():
+            demand_spec = grid_spec.get("demand")
+            if not demand_spec:
+                continue
+
+            node_names = self.grid_nodes.get(grid_name, [])
+            if not node_names:
+                continue
+
+            source_profile_name = demand_spec["source"]
+            source_spec = profile_specs.get(source_profile_name, {})
+            dist = demand_spec.get("distribution", {})
+            nodes_with_demand = demand_spec.get("nodes_with_demand", len(node_names))
+
+            # Select which nodes get demand
+            if nodes_with_demand < len(node_names):
+                demand_indices = sorted(
+                    self.rng.choice(len(node_names), size=nodes_with_demand, replace=False)
+                )
+            else:
+                demand_indices = list(range(len(node_names)))
+
+            for idx in demand_indices:
+                node_name = node_names[idx]
+
+                # Sample annual demand
+                annual_demand = float(pert_sample(
+                    self.rng, dist["min"], dist["mode"], dist["max"], size=1
+                )[0])
+
+                # Generate demand profile
+                ts = self._generate_profile_series(source_spec)
+
+                # Set inflow (demand profile shape) and annual_flow on node
+                self._add_param("node", node_name, "inflow", make_time_series(ts.tolist()))
+                self._add_param("node", node_name, "annual_flow", annual_demand)
+                self._add_param("node", node_name, "inflow_method", "scale_to_annual_flow")
+
+    def _generate_profile_series(self, profile_spec: dict) -> np.ndarray:
+        """Generate a time series from a profile specification."""
+        if "constant" in profile_spec:
+            return generate_constant_series(profile_spec["constant"], self.profile_length)
+
+        ac = profile_spec.get("auto_correlate", {})
+        dist = ac.get("distribution", {})
+        return generate_autocorrelated_series(
+            self.rng,
+            self.profile_length,
+            ac.get("pattern_length_average", 24),
+            ac.get("pattern_length_st_dev", 0),
+            dist.get("min", 0),
+            dist.get("mode", 0.5),
+            dist.get("max", 1.0),
+        )
+
+    def _ensure_profile_entity(self, profile_name: str, profile_spec: dict, location: str) -> str:
+        """Create a per-node profile entity and return its name."""
+        entity_name = f"{profile_name}_{location}"
+        if entity_name not in self.profile_entities:
+            self.profile_entities.add(entity_name)
+            self._add_entity("profile", entity_name)
+            ts = self._generate_profile_series(profile_spec)
+            self._add_param("profile", entity_name, "profile", make_time_series(ts.tolist()))
+        return entity_name
+
+    # -- Storages --
+
+    def _build_storages(self) -> None:
+        storages = self.spec.get("storages", {})
+        for grid_name, storage_types in storages.items():
+            node_names = self.grid_nodes.get(grid_name, [])
+            if not node_names:
+                continue
+
+            for storage_type_name, storage_spec in storage_types.items():
+                storage_params = storage_spec.get("storage", {})
+                conn_params = storage_spec.get("connection", {})
+                ratio = storage_spec.get("fix_storage_to_connection_ratio")
+
+                # Determine the node_group to get location names
+                grid_spec = self.spec.get("grids", {}).get(grid_name, {})
+                node_group = grid_spec.get("node_group", "")
+                locations = self.location_names.get(node_group, [])
+
+                for i, grid_node in enumerate(node_names):
+                    location = locations[i] if i < len(locations) else f"loc{i}"
+                    storage_node_name = f"{storage_type_name}_{location}_{grid_name}"
+                    conn_name = f"{storage_type_name}_conn_{location}_{grid_name}"
+
+                    # Storage node
+                    self._add_entity("node", storage_node_name)
+                    self._add_param("node", storage_node_name, "node_type", "storage")
+                    self._add_param("node", storage_node_name, "invest_method", "invest_no_limit")
+                    self._add_param("node", storage_node_name, "storage_binding_method", "bind_within_solve")
+                    self._add_param("node", storage_node_name, "lifetime", storage_params.get("lifetime", 20))
+                    self._add_param("node", storage_node_name, "discount_rate", storage_params.get("discount_rate", 0.05))
+                    if "invest_cost" in storage_params:
+                        self._add_param("node", storage_node_name, "invest_cost", storage_params["invest_cost"])
+
+                    # Storage connection (grid_node <-> storage_node)
+                    self._add_entity("connection", conn_name)
+                    self._add_entity("connection__node__node", [conn_name, grid_node, storage_node_name])
+                    self._add_param("connection", conn_name, "invest_method", "invest_no_limit")
+                    self._add_param("connection", conn_name, "transfer_method", "regular")
+                    self._add_param("connection", conn_name, "lifetime", conn_params.get("lifetime", 20))
+                    self._add_param("connection", conn_name, "discount_rate", conn_params.get("discount_rate", 0.05))
+                    if "invest_cost" in conn_params:
+                        self._add_param("connection", conn_name, "invest_cost", conn_params["invest_cost"])
+                    if "efficiency" in conn_params:
+                        self._add_param("connection", conn_name, "efficiency", conn_params["efficiency"])
+
+                    # Constraint to tie storage capacity to connection capacity
+                    if ratio is not None:
+                        constraint_name = f"tie_{storage_type_name}_{location}_{grid_name}"
+                        self._add_entity("constraint", constraint_name)
+                        self._add_param("constraint", constraint_name, "sense", "equal")
+                        self._add_param("constraint", constraint_name, "constant", 0.0)
+
+                        # Node coefficient: +1 per MWh of storage
+                        node_coeff = make_map([constraint_name], [1.0], index_name="constraint")
+                        self._add_param("node", storage_node_name, "constraint_invested_capacity_coeff", node_coeff)
+
+                        # Connection coefficient: -ratio per MW of connection
+                        conn_coeff = make_map([constraint_name], [-ratio], index_name="constraint")
+                        self._add_param("connection", conn_name, "constraint_invested_capacity_coeff", conn_coeff)
+
+    # -- Technologies --
+
+    def _build_technologies(self) -> None:
+        technologies = self.spec.get("technologies", {})
+        profile_specs = self.spec.get("profiles", {})
+
+        for source_name, sinks in technologies.items():
+            for sink_name, techs in sinks.items():
+                for tech_name, tech_spec in techs.items():
+                    self._build_tech_units(source_name, sink_name, tech_name, tech_spec, profile_specs)
+
+    def _build_tech_units(
+        self,
+        source_name: str,
+        sink_name: str,
+        tech_name: str,
+        tech_spec: dict,
+        profile_specs: dict,
+    ) -> None:
+        """Create units for a technology across all nodes in the sink grid."""
+        # Determine source node(s) and sink nodes
+        is_fuel_source = source_name in self.fuel_nodes
+        is_profile_source = source_name in self.spec.get("profiles", {})
+
+        sink_nodes = self.grid_nodes.get(sink_name, [])
+        if not sink_nodes:
+            return
+
+        # For profile source, get the profile spec
+        profile_spec = profile_specs.get(source_name) if is_profile_source else None
+
+        # Determine the node_group for location names
+        sink_grid_spec = self.spec.get("grids", {}).get(sink_name, {})
+        sink_node_group = sink_grid_spec.get("node_group", "")
+        sink_locations = self.location_names.get(sink_node_group, [])
+
+        # Source grid nodes (for grid-to-grid technologies)
+        source_nodes = self.grid_nodes.get(source_name, [])
+        source_grid_spec = self.spec.get("grids", {}).get(source_name, {})
+        source_grid_spec.get("node_group", "")
+
+        for i, sink_node in enumerate(sink_nodes):
+            location = sink_locations[i] if i < len(sink_locations) else f"loc{i}"
+            unit_name = f"{tech_name}_{location}_{sink_name}"
+
+            self._add_entity("unit", unit_name)
+
+            # Unit parameters
+            self._add_param("unit", unit_name, "invest_method", "invest_no_limit")
+            self._add_param("unit", unit_name, "lifetime", tech_spec.get("lifetime", 20))
+            self._add_param("unit", unit_name, "discount_rate", tech_spec.get("discount_rate", 0.05))
+            if "conversion_method" in tech_spec:
+                self._add_param("unit", unit_name, "conversion_method", tech_spec["conversion_method"])
+            if "efficiency" in tech_spec:
+                self._add_param("unit", unit_name, "efficiency", tech_spec["efficiency"])
+            if "efficiency_at_min_load" in tech_spec:
+                self._add_param("unit", unit_name, "efficiency_at_min_load", tech_spec["efficiency_at_min_load"])
+            if "min_load" in tech_spec:
+                self._add_param("unit", unit_name, "min_load", tech_spec["min_load"])
+            if "invest_cost" in tech_spec:
+                self._add_param("unit", unit_name, "invest_cost", tech_spec["invest_cost"])
+            if "startup_method" in tech_spec:
+                self._add_param("unit", unit_name, "startup_method", tech_spec["startup_method"])
+            if "startup_cost" in tech_spec:
+                self._add_param("unit", unit_name, "startup_cost", tech_spec["startup_cost"])
+
+            # Output node relationship
+            self._add_entity("unit__outputNode", [unit_name, sink_node])
+
+            # Input node relationship
+            if is_fuel_source:
+                fuel_node = self.fuel_nodes[source_name]
+                self._add_entity("unit__inputNode", [unit_name, fuel_node])
+            elif is_profile_source:
+                # Profile-based source: unit takes from the same node (like VRE)
+                # Input is the output node itself (single-node conversion)
+                # Actually for VRE, we just need outputNode + profile, no inputNode
+                # Link profile
+                profile_entity = self._ensure_profile_entity(source_name, profile_spec, location)
+                self._add_entity("unit__node__profile", [unit_name, sink_node, profile_entity])
+                self._add_param(
+                    "unit__node__profile",
+                    [unit_name, sink_node, profile_entity],
+                    "profile_method",
+                    "upper_limit",
+                )
+            else:
+                # Grid-to-grid: find the matching source node at same location
+                if source_nodes and i < len(source_nodes):
+                    source_node = source_nodes[i]
+                    self._add_entity("unit__inputNode", [unit_name, source_node])
+
+    # -- Model Infrastructure --
+
+    def _build_model_infrastructure(self) -> None:
+        """Create model, solve, timeline, timeset, and period entities."""
+        # Timeline
+        timeline_name = "generated_timeline"
+        self._add_entity("timeline", timeline_name)
+        # All hourly timesteps
+        durations = make_map(
+            self.timestep_keys,
+            [1.0] * self.profile_length,
+        )
+        self._add_param("timeline", timeline_name, "timestep_duration", durations)
+
+        # Timeset
+        timeset_name = "generated_timeset"
+        self._add_entity("timeset", timeset_name)
+        self._add_param("timeset", timeset_name, "timeline", timeline_name)
+
+        # Solve
+        solve_name = "generated_solve"
+        self._add_entity("solve", solve_name)
+        self._add_param("solve", solve_name, "solve_mode", "single_solve")
+        self._add_param("solve", solve_name, "solver", "highs")
+        self._add_param(
+            "solve", solve_name, "period_timeset",
+            make_map(["p2025"], [timeset_name]),
+        )
+        self._add_param(
+            "solve", solve_name, "invest_periods",
+            make_array(["p2025"]),
+        )
+        self._add_param(
+            "solve", solve_name, "realized_periods",
+            make_array(["p2025"]),
+        )
+        self._add_param(
+            "solve", solve_name, "years_represented",
+            make_map(["p2025"], [1.0], index_name="period"),
+        )
+
+        # Model
+        model_name = "generated_model"
+        self._add_entity("model", model_name)
+        self._add_param(
+            "model", model_name, "solves",
+            make_array([solve_name]),
+        )
+
+
+def build_model(
+    yaml_path: str | Path,
+    output_path: str | Path | None = None,
+    seed: int | None = None,
+    db_url: str | None = None,
+) -> dict:
+    """Build a FlexTool model from a YAML specification file.
+
+    Can output to JSON file and/or import directly into a Spine database.
+
+    Args:
+        yaml_path: Path to the YAML specification file.
+        output_path: Optional path for the output JSON file.
+                     If None and no db_url, uses the YAML filename with .json extension.
+        seed: Optional random seed for reproducibility.
+        db_url: Optional database URL for direct import (e.g. 'sqlite:///path.sqlite').
+                If provided, imports data directly using spinedb_api.
+
+    Returns:
+        The generated model data dictionary (with raw Python values).
+    """
+    yaml_path = Path(yaml_path)
+    with open(yaml_path) as f:
+        spec = yaml.safe_load(f)
+
+    builder = ModelBuilder(spec, seed=seed)
+    result = builder.build()
+
+    print(f"Generated model from: {yaml_path}")
+    print(f"  Entities: {len(result['entities'])}")
+    print(f"  Parameter values: {len(result['parameter_values'])}")
+
+    # Write JSON file
+    if output_path is not None or db_url is None:
+        if output_path is None:
+            output_path = yaml_path.with_suffix(".json")
+        output_path = Path(output_path)
+        json_data = model_data_to_json_serializable(result)
+        with open(output_path, "w") as f:
+            json.dump(json_data, f, indent=2)
+        print(f"  JSON written to: {output_path}")
+
+    # Direct database import
+    if db_url is not None:
+        from spinedb_api import DatabaseMapping, import_data
+
+        with DatabaseMapping(db_url) as db:
+            num, log = import_data(db, **result)
+            print(f"  Database import: {num} items")
+            if log:
+                for entry in log[:10]:
+                    print(f"    WARNING: {entry}")
+            db.commit_session("Imported generated model")
+        print(f"  Imported to: {db_url}")
+
+    return result
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate a FlexTool mock-up model from YAML specification")
+    parser.add_argument("yaml_file", help="Path to the YAML specification file")
+    parser.add_argument("-o", "--output", help="Output JSON file path")
+    parser.add_argument("--db", help="Database URL for direct import (e.g. sqlite:///path.sqlite)")
+    parser.add_argument("--seed", type=int, help="Random seed for reproducibility")
+    args = parser.parse_args()
+
+    build_model(args.yaml_file, args.output, args.seed, args.db)
+
+
+if __name__ == "__main__":
+    main()

flextool/model_builder/encoding.py

@@ -0,0 +1,67 @@
+"""Helpers for building parameter values for FlexTool model data.
+
+Uses spinedb_api Map/Array objects for complex values. Provides two output modes:
+- Raw Python objects for direct import via spinedb_api.import_data()
+- Base64-encoded JSON for writing importable JSON files
+"""
+
+import base64
+from typing import Any
+
+from spinedb_api import Map, Array, to_database
+
+
+def make_map(
+    keys: list[str], values: list[float | str], index_name: str | None = None
+) -> Map:
+    """Build a spinedb_api Map (rank-1)."""
+    return Map(keys, values, index_name=index_name)
+
+
+def make_array(values: list[str], index_name: str | None = None) -> Array:
+    """Build a spinedb_api Array."""
+    return Array(values, index_name=index_name)
+
+
+def make_time_series(
+    timestep_values: list[float], num_timesteps: int | None = None
+) -> Map:
+    """Build a time series Map with t0001..tNNNN keys."""
+    n = num_timesteps or len(timestep_values)
+    keys = [f"t{i+1:04d}" for i in range(n)]
+    return Map(keys, list(timestep_values[:n]))
+
+
+def param_value(
+    entity_class: str,
+    entity_name: str | list[str],
+    parameter: str,
+    value: Any,
+    alternative: str,
+) -> list:
+    """Build a single parameter_values entry with raw Python value."""
+    return [entity_class, entity_name, parameter, value, alternative]
+
+
+def encode_for_json(value: Any) -> list:
+    """Encode a value to [base64_string, type_string] for JSON file output."""
+    db_value, db_type = to_database(value)
+    b64 = base64.b64encode(db_value).decode("utf-8")
+    return [b64, db_type]
+
+
+def model_data_to_json_serializable(data: dict) -> dict:
+    """Convert model data with raw Python values to JSON-serializable format.
+
+    Encodes all parameter values from raw objects (Map, Array, float, str)
+    to [base64, type] tuples suitable for JSON output.
+    """
+    result = dict(data)
+    if "parameter_values" in result:
+        encoded_pvs = []
+        for pv in result["parameter_values"]:
+            entity_class, entity_name, param, value, alt = pv
+            encoded = encode_for_json(value)
+            encoded_pvs.append([entity_class, entity_name, param, encoded, alt])
+        result["parameter_values"] = encoded_pvs
+    return result