API and Web UI Service Reference

SparlectraApiArtifact

Metadata for one file produced or discovered by run_sparlectra_api. Artifact paths are absolute so callers do not need to know Sparlectra's internal file naming or working-directory conventions.

SparlectraApiResult

Stable, non-interactive result returned by run_sparlectra_api. Each result has a unique run_id and a schema_version for transport consumers. The raw_result field contains the underlying SparlectraRunResult for a completed solver invocation and is nothing for input or configuration errors. Use the serialization helpers for transport-safe representations that omit raw_result by default.

Dotted configuration keys accepted from GUI/API override input.

validate_gui_config_overrides(config_overrides) -> Dict{String,Any}

Validate GUI-supplied dotted configuration keys and return the equivalent nested configuration dictionary. Only GUI_EDITABLE_CONFIG_KEYS are accepted. Invalid keys, types, enum values, and ranges throw ArgumentError before power-flow execution.

collect_sparlectra_api_artifacts(output_dir) -> Vector{SparlectraApiArtifact}

Discover files beneath an API run directory and return deterministic artifact metadata. This is the only filename-discovery contract needed by GUI clients.

run_sparlectra_api(; casefile, config_file, output_dir, config_overrides=Dict(),
                    performance_timing=:off, run_diagnostics=false,
                    detailed_result_csv=false,
                    detailed_result_csv_format="technical",
                    detailed_result_csv_semicolon=false) -> SparlectraApiResult

Run one MATPOWER power-flow case through a stable, non-interactive API contract. The function validates GUI overrides, writes effective_config.yaml, delegates the numerical work to run_sparlectra, captures textual output in run.log, writes result.json, discovers all generated files, and returns structured status and artifact metadata. The input configuration template is never modified. performance_timing may be :off, :compact, or :full and writes a single-run performance.log; run_diagnostics=true captures existing PowerFlow diagnostic printers in diagnose.log; and detailed_result_csv=true writes Excel-friendly bus-voltage and branch-flow CSV artifacts. Optional detailed_result_csv_format accepts technical, excel_de, or excel_us. The legacy detailed_result_csv_semicolon=true maps to excel_de when the explicit format is omitted. Artifact generation does not change PowerFlow run success.

get_powerflow_result(run_id::AbstractString) -> Dict{String,Any}

Return serialized metadata for a registered local PowerFlow service run.

If the run ID is unknown, return a structured service failure dictionary instead of throwing, so Web UI callers can render a stable error response.

start_powerflow_run(request::AbstractDict; case_directory=nothing) -> Dict{String,Any}

Start one local PowerFlow service run above run_sparlectra_api. The request must provide casefile, config_file, and output_root; optional config_overrides are forwarded to the programmatic API. A unique run ID is chosen before execution, and all generated files are written beneath output_root/run_id. Completed API runs, including failed runs with a result.json, are registered in memory and in the persistent run index. Public service failures are returned as structured dictionaries.

When case_directory is provided by a trusted caller, bare .m case names are resolved there through ensure_casefile and remain the executed source. Generated Julia cache files in that directory are hidden from the Web UI service path: explicit .jl requests resolve to a matching .m source when present and are rejected otherwise.

delete_all_powerflow_runs(; output_root::AbstractString) -> Dict{String,Any}

Delete all safely registered PowerFlow run directories beneath output_root. Entries that cannot be validated or removed remain indexed and are reported in failed_runs; deletion never follows an indexed path outside the output root.

delete_powerflow_run(run_id::AbstractString; output_root::AbstractString) -> Dict{String,Any}

Delete one registered PowerFlow run beneath output_root. The run ID must be a safe index entry whose directory is exactly <output_root>/<run_id>; arbitrary paths and unregistered directories are never removed.

list_powerflow_runs(output_root::AbstractString) -> Vector{Dict{String,Any}}

List runs from the persistent index for a future run-history UI. Each entry has an available flag; missing directories, missing result.json files, and unsafe indexed paths are described by a structured reason instead of raising.

load_powerflow_run_index(output_root::AbstractString) -> Dict{String,Any}

Load the persistent PowerFlow run index beneath output_root. A missing or unreadable index returns an empty transport-safe index. Invalid top-level content is reported through reason and message without throwing.

refresh_powerflow_run_registry!(output_root::AbstractString) -> Dict{String,Any}

Reload valid PowerFlow service runs from the persistent index under output_root into the in-process registry. Runs that were active when the Web UI stopped are marked as stale aborted results before registration, while invalid or missing entries are reported in unavailable_runs.

list_powerflow_artifacts(run_id::AbstractString)

Return transport-safe metadata for artifacts currently available for a registered local PowerFlow service run. Unknown run IDs are returned as a structured service failure dictionary.

resolve_powerflow_artifact(run_id::AbstractString, artifact_name::AbstractString)

Resolve an artifact by its metadata name, never by an arbitrary filesystem path. Absolute paths, traversal components, Windows-style paths, missing files, and artifacts escaping the selected run directory are returned as structured failures.

Convert artifact metadata to a transport-safe dictionary.

to_dict(result::SparlectraApiResult; include_raw_result=false) -> Dict{String,Any}

Convert an API result to a transport-safe dictionary. raw_result is omitted by default because the solved network is not a stable JSON/YAML transport type.

Serialize an API result as JSON without an additional JSON package.

Convert an API result to a transport-safe NamedTuple.

Serialize an API result as YAML without an additional YAML package.