arachne::ariadne::candidate_planner Class Reference

#include <include/ariadne/candidates.hpp>

Static Public Member Functions
static nlohmann::ordered_json	configuration_values (const candidate_configuration &configuration={})
static nlohmann::ordered_json	build (const nlohmann::json &external_graph, const candidate_configuration &configuration={})
static nlohmann::ordered_json	write_plan (const nlohmann::json &materialization, const std::filesystem::path &destination, std::string storage_ref, std::string product_snapshot_id, std::string product_snapshot_sha256, const candidate_configuration &configuration, std::string created_at)
static nlohmann::ordered_json	enrichment_fetch_plan (const nlohmann::json &candidate_pool, const nlohmann::json &available_profiles, std::string source_name, std::string locator, std::string created_at)

Detailed Description

Definition at line 20 of file candidates.hpp.

Member Function Documentation

build()

nlohmann::ordered_json arachne::ariadne::candidate_planner::build ( const nlohmann::json & external_graph, const candidate_configuration & configuration = {} )

staticnodiscard

Definition at line 782 of file candidates.cpp.

  {
    validate_configuration(configuration);
    const auto graph = parse_graph(external_graph);
    auto pool = rank_pool(graph, configuration);
    const auto pool_count = pool.size();
    group_and_select(pool, graph, configuration);
 
    const auto values = configuration_values(configuration);
    const auto configuration_hash
        = crypto::sha256(arachnespace::contracts::canonical_json(values));
 
    nlohmann::ordered_json plan {
        { "artifact_type", "research_candidate_graph_materialization_v1" },
        { "format_version", 1 },
        { "source_snapshot",
          { { "snapshot_id", graph.source_snapshot_id },
            { "storage_ref", graph.source_storage_ref },
            { "sha256", graph.source_sha256 } } },
        { "algorithm",
          { { "name", "wikidata_art_multi_pass" },
            { "version", "1.0.0" },
            { "configuration_sha256", configuration_hash } } },
        { "groups", nlohmann::ordered_json::array() },
        { "candidates", nlohmann::ordered_json::array() },
        { "works", nlohmann::ordered_json::array() },
        { "relations", nlohmann::ordered_json::array() },
    };
 
    std::vector<std::size_t> group_candidates(configuration.group_count, 0);
    std::vector<std::size_t> group_works(configuration.group_count, 0);
    std::set<std::size_t> emitted_works;
    for (const auto& candidate : pool) {
        const auto& agent = graph.agents[candidate.agent_index];
        const auto candidate_id = "candidate-" + agent.id;
        ++group_candidates.at(candidate.group - 1);
        group_works.at(candidate.group - 1) += candidate.claimed_works.size();
        plan["candidates"].push_back(
            { { "candidate_id", candidate_id },
              { "external_id", agent.id },
              { "label", agent.label },
              { "kind", "candidate" },
              { "rank", candidate.rank },
              { "coverage",
                static_cast<double>(candidate.coverage_basis_points) / 100.0 },
              { "group_id", "group-" + std::to_string(candidate.group) },
              { "selection_reasons",
                { selection_explanation(candidate),
                  "Candidate state was recomputed from the declared source and "
                  "product coverage; no prior grey-node state was reused." } },
              { "source_snapshot_id", graph.source_snapshot_id },
              { "attributes",
                { { "coverage_basis_points", candidate.coverage_basis_points },
                  { "parsed_children", candidate.parsed_children },
                  { "gray_children", candidate.gray_children },
                  { "total_active_children", candidate.total_children },
                  { "grouping_score",
                    std::round(candidate.grouping_score * 100000000.0)
                        / 100000000.0 },
                  { "profile", agent.profile },
                  { "ranked_pool_size", pool_count },
                  { "noncanonical", true } } } }
        );
        for (const auto work_index : candidate.claimed_works) {
            const auto& work = graph.works[work_index];
            const auto work_id = "candidate-work-" + work.id;
            if (emitted_works.emplace(work_index).second) {
                plan["works"].push_back(
                    { { "work_id", work_id },
                      { "candidate_id", candidate_id },
                      { "external_id", work.id },
                      { "label", work.label },
                      { "source_snapshot_id", graph.source_snapshot_id },
                      { "attributes",
                        { { "noncanonical", true },
                          { "soft_guidance", true } } } }
                );
            }
            plan["relations"].push_back(
                { { "relation_id",
                    "suggestion_"
                        + crypto::sha256(agent.id + "\n" + work.id)
                              .substr(0, 24) },
                  { "source_id", candidate_id },
                  { "target_id", work_id },
                  { "relation_type", "research_suggestion" },
                  { "weight", 1.0 },
                  { "provenance",
                    { { "origin", "algorithmic_external" },
                      { "source_snapshot_id", graph.source_snapshot_id },
                      { "algorithm_version", "1.0.0" },
                      { "explanation",
                        "The work was an unclaimed graph neighbor; this soft "
                        "suggestion does not reserve or verify it." } } },
                  { "attributes", { { "soft_guidance", true } } } }
            );
        }
    }
    for (std::size_t group = 0; group < configuration.group_count; ++group) {
        plan["groups"].push_back(
            { { "group_id", "group-" + std::to_string(group + 1) },
              { "label",
                "Research suggestion group " + std::to_string(group + 1) },
              { "order", group },
              { "candidate_count", group_candidates[group] },
              { "rationale",
                "Balanced deterministic grouping by available profile and "
                "temporal features." },
              { "attributes",
                { { "work_count", group_works[group] },
                  { "soft_guidance", true } } } }
        );
    }
    auto sorted_works
        = plan["works"].get<std::vector<nlohmann::ordered_json>>();
    std::ranges::sort(sorted_works, [](const auto& left, const auto& right) {
        return id_less(
            left.at("work_id").template get_ref<const std::string&>(),
            right.at("work_id").template get_ref<const std::string&>()
        );
    });
    plan["works"] = std::move(sorted_works);
    const std::string canonical_without_id = plan.dump();
    plan["plan_id"] = "candidate_plan_"
        + crypto::sha256(canonical_without_id).substr(0, 32);
    return plan;
}

References arachne::ariadne::candidate_configuration::group_count, arachne::crypto::sha256(), and arachne::ariadne::anonymous_namespace{candidates.cpp}::validate_configuration().

Here is the call graph for this function:

configuration_values()

nlohmann::ordered_json arachne::ariadne::candidate_planner::configuration_values ( const candidate_configuration & configuration = {} )

staticnodiscard

Canonical values whose hash identifies one candidate run policy.

Definition at line 767 of file candidates.cpp.

  {
    validate_configuration(configuration);
    return {
        { "candidate_pool_size", configuration.pool_size },
        { "final_target", configuration.target_size },
        { "group_count", configuration.group_count },
        { "gray_bonus_basis_points", configuration.gray_bonus_basis_points },
        { "quality_weight", configuration.quality_weight },
        { "grey_node_policy", "recompute" },
        { "tie_breaker", "stable-id" },
    };
}

References arachne::ariadne::candidate_configuration::gray_bonus_basis_points, arachne::ariadne::candidate_configuration::group_count, arachne::ariadne::candidate_configuration::pool_size, arachne::ariadne::candidate_configuration::quality_weight, arachne::ariadne::candidate_configuration::target_size, and arachne::ariadne::anonymous_namespace{candidates.cpp}::validate_configuration().

Here is the call graph for this function:

enrichment_fetch_plan()

nlohmann::ordered_json arachne::ariadne::candidate_planner::enrichment_fetch_plan ( const nlohmann::json & candidate_pool, const nlohmann::json & available_profiles, std::string source_name, std::string locator, std::string created_at )

staticnodiscard

Definition at line 986 of file candidates.cpp.

  {
    if (!candidate_pool.is_array() || !available_profiles.is_object()
        || source_name.empty() || locator.empty() || created_at.empty()) {
        throw std::invalid_argument("invalid enrichment planning input");
    }
    std::vector<std::string> missing;
    for (const auto& candidate : candidate_pool) {
        const auto id = candidate.contains("external_id")
            ? required_string(candidate, "external_id", "candidate")
            : required_string(candidate, "id", "candidate");
        if (!available_profiles.contains(id)) {
            missing.push_back(id);
        }
    }
    std::ranges::sort(missing, id_less);
    nlohmann::ordered_json result {
        { "contract", "fetch_plan_v1" },
        { "format_version", 1 },
        { "plan_id", "" },
        { "source", std::move(source_name) },
        { "requests",
          nlohmann::ordered_json::array(
              { { { "request_id", "candidate-profile-enrichment" },
                  { "locator", std::move(locator) },
                  { "purpose", "candidate profile enrichment" },
                  { "entities", missing },
                  { "fields",
                    { "gender", "country", "field", "occupation", "movement",
                      "genre", "language", "activity_dates" } },
                  { "follow_up", true } } }
          ) },
        { "created_at", std::move(created_at) },
    };
    result["plan_id"]
        = "fetch_plan_" + crypto::sha256(result.dump()).substr(0, 32);
    return result;
}

References arachne::crypto::sha256().

Here is the call graph for this function:

write_plan()

nlohmann::ordered_json arachne::ariadne::candidate_planner::write_plan ( const nlohmann::json & materialization, const std::filesystem::path & destination, std::string storage_ref, std::string product_snapshot_id, std::string product_snapshot_sha256, const candidate_configuration & configuration, std::string created_at )

staticnodiscard

Publish a resolved materialization artifact and return its validated research_candidate_graph_plan_v1 control contract.

Definition at line 912 of file candidates.cpp.

  {
    if (!materialization.is_object()
        || materialization.value("artifact_type", "")
            != "research_candidate_graph_materialization_v1"
        || materialization.value("format_version", 0) != 1
        || storage_ref.empty()) {
        throw std::invalid_argument(
            "plan publication requires a resolved candidate materialization"
        );
    }
    for (const auto* field : { "groups", "candidates", "works", "relations" }) {
        if (!materialization.contains(field)
            || !materialization.at(field).is_array()) {
            throw std::invalid_argument(
                std::string("candidate materialization requires array ") + field
            );
        }
    }
    const auto values = configuration_values(configuration);
    const auto configuration_hash
        = crypto::sha256(arachnespace::contracts::canonical_json(values));
    if (!materialization.contains("algorithm")
        || !materialization.at("algorithm").is_object()
        || materialization.at("algorithm").value("configuration_sha256", "")
            != configuration_hash) {
        throw std::invalid_argument(
            "candidate configuration does not match materialization"
        );
    }
    const std::string bytes = materialization.dump(2) + "\n";
    nlohmann::ordered_json contract {
        { "contract", "research_candidate_graph_plan_v1" },
        { "format_version", 1 },
        { "plan_id", materialization.at("plan_id") },
        { "source_snapshot", materialization.at("source_snapshot") },
        { "product_snapshot",
          { { "snapshot_id", std::move(product_snapshot_id) },
            { "sha256", std::move(product_snapshot_sha256) } } },
        { "algorithm_version",
          materialization.at("algorithm").at("name").get<std::string>() + "-"
              + materialization.at("algorithm")
                    .at("version")
                    .get<std::string>() },
        { "configuration",
          { { "sha256", configuration_hash }, { "values", values } } },
        { "plan_artifact",
          { { "storage_ref", std::move(storage_ref) },
            { "sha256", crypto::sha256(bytes) },
            { "byte_length", bytes.size() },
            { "media_type", "application/json" } } },
        { "summary",
          { { "candidate_count", materialization.at("candidates").size() },
            { "edge_count", materialization.at("relations").size() },
            { "group_count", materialization.at("groups").size() } } },
        { "created_at", std::move(created_at) },
    };
    const auto validation = arachnespace::contracts::validate(
        arachnespace::contracts::contract_name::research_candidate_graph_plan,
        contract
    );
    if (!validation.valid()) {
        throw std::invalid_argument(
            "generated research_candidate_graph_plan_v1 contract is invalid"
        );
    }
    publish_immutable_file(destination, bytes);
    return contract;
}

References arachne::ariadne::anonymous_namespace{candidates.cpp}::publish_immutable_file(), arachnespace::contracts::research_candidate_graph_plan, and arachne::crypto::sha256().

Here is the call graph for this function:

---

The documentation for this class was generated from the following files:

• candidates.hpp
• candidates.cpp