Bump version. Minor documentation updates. search runs by dict of params.

Author: deyandyankov

.gitignore

@@ -1,6 +1,6 @@
 *.jl.*.cov
 *.jl.cov
 *.jl.mem
-/Manifest.toml
+Manifest.toml
 /docs/build/
 mlruns

Project.toml

@@ -1,7 +1,7 @@
 name = "MLFlowClient"
 uuid = "64a0f543-368b-4a9a-827a-e71edb2a0b83"
 authors = ["@deyandyankov and contributors"]
-version = "0.1.0"
+version = "0.2.0"
 
 [deps]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"

docs/src/index.md

@@ -4,13 +4,9 @@ CurrentModule = MLFlowClient
 
 # MLFlowClient
 
-[MLFlowClient](https://github.com/JuliaAI/MLFlowClient.jl) is a [Julia](https://julialang.org/) package for working with [MLFlow](https://mlflow.org/) using the REST [API v2.0](https://www.mlflow.org/docs/latest/rest-api.html).
-
-`MLFlowClient` allows you to create and manage `MLFlow` experiments, runs, and log metrics and artifacts. If you are not familiar with `MLFlow` and its concepts, please refer to [MLFlow documentation](https://mlflow.org/docs/latest/index.html).
-
-## Limitations
-- no authentication support.
-- when storing artifacts, the assumption is that MLFlow and this library run on the same server. Artifacts are stored using plain filesystem operations. Therefore, `/mlruns` or the specified `artifact_location` must be accessible to both the MLFlow server (read), and this library (write).
+```@docs
+MLFlowClient
+```
 
 ## Installation
 

docs/src/reference.md

@@ -6,6 +6,8 @@ CurrentModule = MLFlowClient
 
 # Types
 
+TODO: Document accessors.
+
 ```@docs
 MLFlow
 MLFlowExperiment
@@ -43,3 +45,12 @@ logparam
 logmetric
 logartifact
 ```
+
+# Utilities
+
+```@docs
+mlfget
+mlfpost
+uri
+generatefilterfromparams
+```

src/MLFlowClient.jl

@@ -25,11 +25,17 @@ export
     MLFlowExperiment,
     MLFlowRunStatus,
     MLFlowRunInfo,
+    get_run_id,
     MLFlowRunData,
+    get_params,
     MLFlowRunDataMetric,
-    MLFlowRun
+    MLFlowRun,
+    get_info,
+    get_data
 
 include("utils.jl")
+export
+    generatefilterfromparams
 
 include("experiments.jl")
 export

src/runs.jl

@@ -118,6 +118,7 @@ Searches for runs in an experiment.
 
 # Keywords
 - `filter::String`: filter as defined in [MLFlow documentation](https://mlflow.org/docs/latest/rest-api.html#search-runs)
+- `filter_params::AbstractDict{K,V}`: if provided, `filter` is automatically generated based on `filter_params` using [`generatefilterfromparams`](@ref). One can only provide either `filter` or `filter_params`, but not both.
 - `run_view_type::String`: one of `ACTIVE_ONLY`, `DELETED_ONLY`, or `ALL`.
 - `max_results::Integer`: 50,000 by default.
 - `order_by::String`: as defined in [MLFlow documentation](https://mlflow.org/docs/latest/rest-api.html#search-runs)
@@ -129,13 +130,23 @@ Searches for runs in an experiment.
 """
 function searchruns(mlf::MLFlow, experiment_ids::AbstractVector{<:Integer};
                     filter::String="",
+                    filter_params::AbstractDict{K,V}=Dict{}(),
                     run_view_type::String="ACTIVE_ONLY",
                     max_results::Int64=50000,
                     order_by::AbstractVector{<:String}=["attribute.start_time"],
                     page_token::String=""
-                    )
+                    ) where {K,V}
     endpoint = "runs/search"
     run_view_type ∈ ["ACTIVE_ONLY", "DELETED_ONLY", "ALL"] || error("Unsupported run_view_type = $run_view_type")
+
+    if length(filter_params) > 0 && length(filter) > 0
+        error("Can only use either filter or filter_params, but not both at the same time.")
+    end
+
+    if length(filter_params) > 0
+        filter = generatefilterfromparams(filter_params)
+    end
+
     kwargs = (
         experiment_ids=experiment_ids,
         filter=filter,
@@ -169,3 +180,7 @@ function searchruns(mlf::MLFlow, experiment_ids::AbstractVector{<:Integer};
 end
 searchruns(mlf::MLFlow, experiment_id::Integer; kwargs...) =
     searchruns(mlf, [experiment_id]; kwargs...)
+searchruns(mlf::MLFlow, exp::MLFlowExperiment; kwargs...) =
+    searchruns(mlf, exp.experiment_id; kwargs...)
+searchruns(mlf::MLFlow, exps::AbstractVector{MLFlowExperiment}; kwargs...) =
+    searchruns(mlf, [getfield.(exps, :experiment_id)]; kwargs...)

src/types.jl

@@ -13,18 +13,18 @@ Base type which defines location and version for MLFlow API service.
 - `MLFlow()` - defaults to `MLFlow("http://localhost:5000")`
 
 # Examples
-``` julia-repl
-julia> mlf = MLFlow()
-MLFlow("http://localhost:5000", 2.0)
+
+```@example
+mlf = MLFlow()
 ```
 
 """
 struct MLFlow
     baseuri::String
     apiversion
-    MLFlow(baseuri; apiversion=2.0) = new(baseuri, apiversion)
 end
-MLFlow() = MLFlow("http://localhost:5000")
+MLFlow(baseuri; apiversion=2.0) = MLFlow(baseuri, apiversion)
+MLFlow() = MLFlow("http://localhost:5000", 2.0)
 
 """
     MLFlowExperiment
@@ -50,18 +50,14 @@ struct MLFlowExperiment
     experiment_id::Integer
     tags::Any
     artifact_location::String
-
-    MLFlowExperiment(name, lifecycle_stage, experiment_id, tags, artifact_location) =
-        new(name, lifecycle_stage, experiment_id, tags, artifact_location)
-   
-    function MLFlowExperiment(exp::Dict{String,Any})
-        name = get(exp, "name", missing)
-        lifecycle_stage = get(exp, "lifecycle_stage", missing)
-        experiment_id = parse(Int, get(exp, "experiment_id", missing))
-        tags = get(exp, "tags", missing)
-        artifact_location = get(exp, "artifact_location", missing)
-        MLFlowExperiment(name, lifecycle_stage, experiment_id, tags, artifact_location)
-    end
+end
+function MLFlowExperiment(exp::Dict{String,Any})
+    name = get(exp, "name", missing)
+    lifecycle_stage = get(exp, "lifecycle_stage", missing)
+    experiment_id = parse(Int, get(exp, "experiment_id", missing))
+    tags = get(exp, "tags", missing)
+    artifact_location = get(exp, "artifact_location", missing)
+    MLFlowExperiment(name, lifecycle_stage, experiment_id, tags, artifact_location)
 end
 
 
@@ -79,7 +75,6 @@ Represents the status of an MLFlow Run.
 """
 struct MLFlowRunStatus
     status::String
-
     function MLFlowRunStatus(status::String)
         acceptable_statuses = ["RUNNING", "SCHEDULED", "FINISHED", "FAILED", "KILLED"]
         status ∈ acceptable_statuses || error("Invalid status $status - choose one of $acceptable_statuses")
@@ -114,39 +109,24 @@ struct MLFlowRunInfo
     end_time::Union{Int64,Missing}
     artifact_uri::String
     lifecycle_stage::String
-
-    function MLFlowRunInfo(run_id, experiment_id, status, start_time, end_time, artifact_uri, lifecycle_stage)
-        new(run_id, experiment_id, status, start_time, end_time, artifact_uri, lifecycle_stage)
-    end
-
-    function MLFlowRunInfo(info::Dict{String,Any})
-        run_id = get(info, "run_id", missing)
-        experiment_id = get(info, "experiment_id", missing)
-        status = get(info, "status", missing)
-        start_time = get(info, "start_time", missing)
-        end_time = get(info, "end_time", missing)
-        artifact_uri = get(info, "artifact_uri", "")
-        lifecycle_stage = get(info, "lifecycle_stage", "")
-
-        if !ismissing(experiment_id)
-            experiment_id = parse(Int64, experiment_id)
-        end
-
-        if !ismissing(status)
-            status = MLFlowRunStatus(status)
-        end
-
-        if !ismissing(start_time)
-            start_time = parse(Int64, start_time)
-        end
-
-        if !ismissing(end_time)
-            end_time = parse(Int64, end_time)
-        end
-
-        MLFlowRunInfo(run_id, experiment_id, status, start_time, end_time, artifact_uri, lifecycle_stage)
-    end
 end
+function MLFlowRunInfo(info::Dict{String,Any})
+    run_id = get(info, "run_id", missing)
+    experiment_id = get(info, "experiment_id", missing)
+    status = get(info, "status", missing)
+    start_time = get(info, "start_time", missing)
+    end_time = get(info, "end_time", missing)
+    artifact_uri = get(info, "artifact_uri", "")
+    lifecycle_stage = get(info, "lifecycle_stage", "")
+
+    experiment_id = ismissing(experiment_id) ? experiment_id : parse(Int64, experiment_id)
+    status = ismissing(status) ? status : MLFlowRunStatus(status)
+    start_time = ismissing(start_time) ? start_time : parse(Int64, start_time)
+    end_time = ismissing(end_time) ? end_time : parse(Int64, end_time)
+
+    MLFlowRunInfo(run_id, experiment_id, status, start_time, end_time, artifact_uri, lifecycle_stage)
+end
+get_run_id(runinfo::MLFlowRunInfo) = runinfo.run_id
 
 """
     MLFlowRunDataMetric
@@ -169,13 +149,13 @@ struct MLFlowRunDataMetric
     value::Float64
     step::Int64
     timestamp::Int64
-    function MLFlowRunDataMetric(d::Dict{String,Any})
-        key = d["key"]
-        value = d["value"]
-        step = parse(Int64, d["step"])
-        timestamp = parse(Int64, d["timestamp"])
-        new(key, value, step, timestamp)
-    end
+end
+function MLFlowRunDataMetric(d::Dict{String,Any})
+    key = d["key"]
+    value = d["value"]
+    step = parse(Int64, d["step"])
+    timestamp = parse(Int64, d["timestamp"])
+    MLFlowRunDataMetric(key, value, step, timestamp)
 end
 
 
@@ -198,20 +178,21 @@ struct MLFlowRunData
     metrics::Vector{MLFlowRunDataMetric}
     params::Union{Dict{String,String},Missing}
     tags
-    function MLFlowRunData(data::Dict{String,Any})
-        metrics = haskey(data, "metrics") ? MLFlowRunDataMetric.(data["metrics"]) : MLFlowRunDataMetric[]
-        if haskey(data, "params")
-            params = Dict{String,String}()
-            for p in data["params"]
-                params[p["key"]] = p["value"]
-            end
-        else
-            params = Dict{String,String}()
+end
+function MLFlowRunData(data::Dict{String,Any})
+    metrics = haskey(data, "metrics") ? MLFlowRunDataMetric.(data["metrics"]) : MLFlowRunDataMetric[]
+    if haskey(data, "params")
+        params = Dict{String,String}()
+        for p in data["params"]
+            params[p["key"]] = p["value"]
         end
-        tags = haskey(data, "tags") ? data["tags"] : missing
-        new(metrics, params, tags)
+    else
+        params = Dict{String,String}()
     end
+    tags = haskey(data, "tags") ? data["tags"] : missing
+    MLFlowRunData(metrics, params, tags)
 end
+get_params(rundata::MLFlowRunData) = rundata.params
 
 """
     MLFlowRun
@@ -233,23 +214,14 @@ Represents an MLFlow run.
 struct MLFlowRun
     info::Union{MLFlowRunInfo,Missing}
     data::Union{MLFlowRunData,Missing}
-
-    function MLFlowRun(rundata::MLFlowRunData)
-        info = missing
-        new(info, rundata)
-    end
-    function MLFlowRun(runinfo::MLFlowRunInfo)
-        data = missing
-        new(runinfo, data)
-    end
-    function MLFlowRun(info::Dict{String,Any})
-        info = MLFlowRunInfo(info)
-        data = missing
-        new(info, data)
-    end
-    function MLFlowRun(info::Dict{String,Any}, data::Dict{String,Any})
-        info = MLFlowRunInfo(info)
-        data = MLFlowRunData(data)
-        new(info, data)
-    end
 end
+MLFlowRun(rundata::MLFlowRunData) =
+    MLFlowRun(missing, rundata)
+MLFlowRun(runinfo::MLFlowRunInfo) =
+    MLFlowRun(runinfo, missing)
+MLFlowRun(info::Dict{String,Any}) =
+    MLFlowRun(MLFlowRunInfo(info), missing)
+MLFlowRun(info::Dict{String,Any}, data::Dict{String,Any}) =
+    MLFlowRun(MLFlowRunInfo(info), MLFlowRunData(data))
+get_info(run::MLFlowRun) = run.info
+get_data(run::MLFlowRun) = run.data

src/utils.jl

@@ -4,9 +4,8 @@
 Retrieves an URI based on `mlf`, `endpoint`, and, optionally, `query`.
 
 # Examples
-``` julia-repl
-julia> MLFlowClient.uri(mlf, "experiments/get", Dict(:experiment_id=>10))
-URI("http://localhost/api/2.0/mlflow/experiments/get?experiment_id=10")
+```@example
+MLFlowClient.uri(mlf, "experiments/get", Dict(:experiment_id=>10))
 ```
 """
 function uri(mlf::MLFlow, endpoint="", query=missing)
@@ -48,3 +47,26 @@ function mlfpost(mlf, endpoint; kwargs...)
     end
 end
 
+"""
+    generatefilterfromparams(filter_params::AbstractDict{K,V}) where {K,V}
+
+Generates a `filter` string from `filter_params` dictionary.
+
+# Arguments
+- `filter_params`: dictionary to use for filter generation.
+
+# Returns
+A string that can be passed as `filter` to [`searchruns`](@ref).
+
+# Examples
+
+```@example
+generatefilterfromparams(Dict("paramkey1" => "paramvalue1", "paramkey2" => "paramvalue2"))
+```
+"""
+function generatefilterfromparams(filter_params::AbstractDict{K,V}) where {K,V}
+    length(filter_params) > 0 || return ""
+    # NOTE: may have issues with escaping.
+    filters = ["param.\"$(k)\" = \"$(v)\"" for(k, v) ∈ filter_params ]
+    join(filters, " and ")
+end