@jetta/blocks-allocator 0.0.0-stage → 0.1.0

package/src/optimizer_connection_errors.js

@@ -0,0 +1,50 @@
+/**
+ * If the optimizer call failed due to a peer-closed HTTP socket or a temporary
+ * NATS failure, returns a clearer Error; otherwise returns the original error.
+ * @param {Error} error - Error from `@jetta/lp-framework`.
+ * @param {number} elapsed_ms - Time spent in optimize() until failure.
+ * @param {number} block_count - Blocks in the LP model.
+ * @param {number} restriction_count - Restrictions registered on the optimizer instance.
+ * @returns {Error} Original or wrapped error.
+ */
+function enrich_optimizer_http_error(error, elapsed_ms, block_count, restriction_count)
+{
+    const message = String(error?.message ?? '')
+    const is_socket_peer = error?.code === 'UND_ERR_SOCKET'
+        || message.includes('other side closed')
+    const is_nats_temporary = error?.name === 'OptimizerNatsTemporaryError'
+        || message.toLowerCase().includes('nats request failed')
+        || message.toLowerCase().includes('no responders')
+    if (!is_socket_peer && !is_nats_temporary)
+    {
+        return error
+    }
+
+    const model_context = `while solving an LP with ${block_count} blocks and ${restriction_count} restrictions`
+    const immediate_close_threshold_ms = 1000
+    let guidance
+    if (is_nats_temporary)
+    {
+        guidance = 'NATS request-reply timed out or had no responders '
+            + '(worker scaled to zero, stream lag, or cold start). '
+            + 'Wait for KEDA to scale python-optimizer-nats and/or raise OPTIMIZER_NATS_TIMEOUT_MS.'
+    }
+    else if (elapsed_ms < immediate_close_threshold_ms)
+    {
+        guidance = 'This usually means the optimizer connection was reset (pod restart, failed liveness/readiness probe, or dying endpoint), not a slow CPLEX solve.'
+    }
+    else
+    {
+        guidance = 'This is usually a server or proxy read/worker timeout on a large model. '
+            + 'Raise the optimizer timeout, or reduce candidate blocks in the allocation input.'
+    }
+
+    const prefix = is_nats_temporary
+        ? `Optimizer NATS request failed after ${elapsed_ms} ms`
+        : `Optimizer closed the HTTP connection after ${elapsed_ms} ms`
+    const wrapped = new Error(`${prefix} ${model_context}. ${guidance}`)
+    wrapped.cause = error
+    return wrapped
+}
+
+module.exports = { enrich_optimizer_http_error }

package/src/relational/Relational_Error_Codes.js

@@ -0,0 +1,7 @@
+const RELATION_ERROR_CODES = Object.freeze({
+    COLOCATION_VIOLATION: 'RELATION_COLOCATION_VIOLATION',
+    ALLOCATION_INCOMPLETE: 'RELATION_ALLOCATION_INCOMPLETE',
+    CONFIG_MISMATCH: 'RELATION_CONFIG_MISMATCH'
+})
+
+module.exports = RELATION_ERROR_CODES

package/src/relational/finalize_relational_allocation.js

@@ -0,0 +1,20 @@
+const { validate_transport_colocation } = require('../validation/Relational_Colocation_Validator')
+const { validate_relational_completeness } = require('../validation/Relational_Completeness_Validator')
+const {
+    normalize_relational_proportional_allocation
+} = require('../validation/Relational_Proportional_Normalizer')
+
+/**
+ * Normalizes proportional relational amounts and validates completeness and co-location.
+ * @param {object} transport - Allocated transport to finalize.
+ * @param {object[]} item_list - Remaining items after allocation (may be empty).
+ * @returns {void}
+ */
+function finalize_relational_allocation(transport, item_list)
+{
+    normalize_relational_proportional_allocation(transport, item_list)
+    validate_relational_completeness(transport, item_list)
+    validate_transport_colocation(transport)
+}
+
+module.exports = finalize_relational_allocation

package/src/relational/has_relational_items.js

@@ -0,0 +1,11 @@
+/**
+ * Returns whether any item in the list belongs to a relational group.
+ * @param {object[]} item_list
+ * @returns {boolean}
+ */
+function has_relational_items(item_list)
+{
+    return item_list.some(item => item.get_relational_group_id && item.get_relational_group_id())
+}
+
+module.exports = has_relational_items

package/src/relational/is_relational_error_code.js

@@ -0,0 +1,15 @@
+const RELATION_ERROR_CODES = require('./Relational_Error_Codes')
+
+const RELATIONAL_ERROR_CODE_SET = new Set(Object.values(RELATION_ERROR_CODES))
+
+/**
+ * Whether a value is a known relational allocation error code.
+ * @param {unknown} code
+ * @returns {boolean}
+ */
+function is_relational_error_code(code)
+{
+    return RELATIONAL_ERROR_CODE_SET.has(code)
+}
+
+module.exports = is_relational_error_code

package/src/relational/resolve_relational_container_sequences.js

@@ -0,0 +1,29 @@
+const Cargo_Profile = require('../models/Cargo_Profile')
+const has_relational_items = require('./has_relational_items')
+
+/**
+ * Returns container sequences to allocate. When relational co-location is enforced
+ * and relational items remain, only the first container sequence is used.
+ * @param {object} transport - Allocation transport with container sequences.
+ * @param {object[]} item_list - Items still to allocate.
+ * @returns {Array<number|string>} Container sequence list for this allocate pass.
+ */
+function resolve_relational_container_sequences(transport, item_list)
+{
+    const all_sequences = transport.get_container_sequence_list()
+
+    if (!Cargo_Profile.enforce_relational_group_co_location())
+    {
+        return all_sequences
+    }
+
+    const has_relational_items_present = has_relational_items(item_list)
+    if (!has_relational_items_present || all_sequences.length === 0)
+    {
+        return all_sequences
+    }
+
+    return [all_sequences[0]]
+}
+
+module.exports = resolve_relational_container_sequences

package/src/run_core_allocation.js

@@ -0,0 +1,118 @@
+const { performance } = require('perf_hooks')
+const Allocation_Flow = require('./Allocation_Flow')
+const build_input_state = require('./input_preparation/State_Builder')
+const { SUCCESS, ERROR } = require('./IO/Answer_Status')
+const build_output_answer = require('./IO/Output_Builder')
+const run_validations = require('./validation/Validation_Runner')
+const Config = require('./models/Cargo_Profile')
+const { Logger } = require('@jetta/logger')
+const {
+    count_allocated_items_in_transport,
+    count_preloaded_items_in_input,
+} = require('./IO/count_allocated_items')
+const { parse_allocation_request } = require('./validation/schemas/allocation_request_schema')
+const create_error_response = require('./IO/create_error_response')
+const { run_with_existing_tracer, get_tracer } = require('./tracing/Allocation_Tracer')
+const { TRACE_CONTEXT } = require('./tracing/Trace_Context')
+
+const logger = new Logger('Blocks Wall Allocation')
+
+/**
+ * Runs one allocation request.
+ * @param {object} input_data
+ * @param {{ object_store?: { get_object: Function }, tracer?: object }} [dependencies]
+ * @returns {Promise<string>}
+ */
+async function run_core_allocation(input_data, dependencies = {})
+{
+    const execute = () => run_blocks_wall_allocation(input_data, dependencies)
+    if (dependencies.tracer)
+    {
+        return run_with_existing_tracer(dependencies.tracer, execute)
+    }
+    return execute()
+}
+
+/**
+ * @param {object} input_data
+ * @param {{ object_store?: { get_object: Function } }} dependencies
+ * @returns {Promise<string>}
+ */
+async function run_blocks_wall_allocation(input_data, dependencies)
+{
+    const start_time = performance.now()
+    const tracer = get_tracer()
+    const tx_id = tracer?.start_transaction(TRACE_CONTEXT.MAIN_FLOW)
+    try
+    {
+        const output = await allocate_request(input_data, dependencies)
+        return finish_success(start_time, tracer, tx_id, output)
+    }
+    catch (error)
+    {
+        return finish_failure(start_time, tracer, tx_id, error)
+    }
+}
+
+/**
+ * @param {object} input_data
+ * @param {{ object_store?: { get_object: Function } }} dependencies
+ * @returns {Promise<string>}
+ */
+async function allocate_request(input_data, dependencies)
+{
+    logger.log('request received.')
+    const safe_input = parse_allocation_request(input_data)
+    const items_to_allocate = safe_input.items.reduce((accumulator, item) => accumulator + item.qtd, 0)
+    logger.debug(`starting Blocks Wall Allocation request with ${items_to_allocate} items.`)
+    run_validations(safe_input)
+    const input_state = await build_input_state(safe_input, dependencies)
+    const flow = new Allocation_Flow(input_state)
+    const output_data = await flow.allocate()
+    const total_allocated = count_allocated_items_in_transport(output_data)
+    const preloaded_count = count_preloaded_items_in_input(safe_input)
+    logger.debug(`allocated a total of ${total_allocated - preloaded_count} items.`)
+    return build_output_answer(SUCCESS, output_data)
+}
+
+/**
+ * @param {number} start_time
+ * @param {object|null} tracer
+ * @param {string|undefined} tx_id
+ * @param {string} output
+ * @returns {string}
+ */
+function finish_success(start_time, tracer, tx_id, output)
+{
+    print_elapsed_time(start_time)
+    Config.reset()
+    logger.log('request finished successfully.')
+    tracer?.end_transaction_succesfully(tx_id)
+    return output
+}
+
+/**
+ * @param {number} start_time
+ * @param {object|null} tracer
+ * @param {string|undefined} tx_id
+ * @param {Error} error
+ * @returns {string}
+ */
+function finish_failure(start_time, tracer, tx_id, error)
+{
+    logger.error(error.message)
+    logger.error(error.stack)
+    print_elapsed_time(start_time)
+    Config.reset()
+    tracer?.end_transaction_with_failure(tx_id)
+    return build_output_answer(ERROR, create_error_response(error))
+}
+
+function print_elapsed_time(start_time)
+{
+    const end_time = performance.now()
+    const elapsed_time = ((end_time - start_time) / 1000).toFixed(5)
+    logger.debug(`finished request in ${elapsed_time} seconds`)
+}
+
+module.exports = run_core_allocation

package/src/space_and_block_chooser/Space_And_Blocks_Chooser.js

@@ -0,0 +1,115 @@
+const run_filters = require('./blocks_filters/Filter_Runner')
+const run_space_and_block_selection_attempt = require('./run_space_and_block_selection_attempt')
+const {NoSpaceLeftException} = require('@jetta/empty-spaces-manager')
+const Invalid_Space_To_Allocate_Exception = require('./exceptions/Invalid_Space_To_Allocate_Exception')
+const {Logger} = require('@jetta/logger')
+const logger = new Logger('Space and Blocks Creator')
+const { traced_step } = require('../tracing/traced_step')
+const { TRACE_CONTEXT } = require('../tracing/Trace_Context')
+
+function get_unattempted_space_list(empty_space_list, spaces_to_avoid)
+{
+    const pending_spaces = []
+    for (const space of empty_space_list)
+    {
+        if (!spaces_to_avoid.has(space))
+        {
+            pending_spaces.push(space)
+        }
+    }
+    return pending_spaces
+}
+
+function handle_invalid_space_exception(error, chosen_empty_space)
+{
+    if (!(error instanceof Invalid_Space_To_Allocate_Exception))
+    {
+        throw error
+    }
+    if (chosen_empty_space === undefined)
+    {
+        throw new NoSpaceLeftException()
+    }
+}
+
+function remove_empty_space_from_pending_list(pending_list, chosen_empty_space)
+{
+    const index = pending_list.indexOf(chosen_empty_space)
+    if (index > -1)
+    {
+        pending_list.splice(index, 1)
+    }
+}
+
+async function process_space_and_blocks(filter_data, empty_space_list)
+{
+    let chosen_empty_space
+    try
+    {
+        const outcome = await run_space_and_block_selection_attempt(run_filters, filter_data, empty_space_list)
+        chosen_empty_space = outcome.chosen_empty_space
+        if (outcome.pos_selection_block_list !== null)
+        {
+            return {
+                empty_space: chosen_empty_space,
+                block_list: outcome.pos_selection_block_list,
+                no_fillable_space_set: filter_data.no_fillable_space_set
+            }
+        }
+    }
+    catch (error)
+    {
+        handle_invalid_space_exception(error, chosen_empty_space)
+    }
+
+    remove_empty_space_from_pending_list(empty_space_list, chosen_empty_space)
+    return null
+}
+
+/**
+ * Chooses an empty space and matching blocks for allocation.
+ * @param {object} container - Current transport container.
+ * @param {object[]} block_list - Candidate blocks.
+ * @param {object[]} item_list - Items to allocate in this iteration.
+ * @param {Set<object>} spaces_to_avoid - Spaces skipped for the current iteration view.
+ * @param {object} [chooser_session] - Optional persistent session from the allocation flow.
+ * @returns {Promise<{ empty_space: object, block_list: object[], no_fillable_space_set: Set<object> }>}
+ */
+module.exports = async function choose_space_and_blocks(
+    container,
+    block_list,
+    item_list,
+    spaces_to_avoid,
+    chooser_session
+)
+{
+    return traced_step(TRACE_CONTEXT.SPACE_AND_BLOCK_CHOICE, async () =>
+    {
+        logger.debug('choosing space and blocks')
+        const empty_space_list = get_unattempted_space_list(container.empty_spaces(), spaces_to_avoid)
+        const obligate_compound_session = chooser_session?.obligate_compound_session
+            ?? { skip_compound_probe: false }
+        const filter_data = {
+            container,
+            block_list,
+            item_list,
+            spaces_to_avoid,
+            no_fillable_space_set: new Set(),
+            obligate_compound_session,
+            tie_ratio_intercalation_state: chooser_session?.tie_ratio_intercalation_state ?? null,
+            empty_space: undefined
+        }
+
+        while (empty_space_list.length > 0)
+        {
+            filter_data.empty_space = undefined
+            const result = await process_space_and_blocks(filter_data, empty_space_list)
+            if (result)
+            {
+                return result
+            }
+        }
+
+        throw new NoSpaceLeftException()
+    })
+}

package/src/space_and_block_chooser/blocks_filters/Block_Filter_Interface.js

@@ -0,0 +1,19 @@
+class Block_Filter_Interface
+{
+    /**
+    * @description a virtual method to be implemented by all block filters"
+    * @param {Object} filter_data
+    *   {
+    *       container: Container,
+    *       empty_space: Empty_Space,
+    *       block_list: Array<Block>,
+    *       item_list: Array<Item>
+    *   }
+    * @return {Array<Block>} filtered block list
+    **/
+    static run(filter_data)
+    {
+        throw new Error('do not overrided pure virtual method, please implement on your extended class')
+    }
+}
+module.exports = Block_Filter_Interface

package/src/space_and_block_chooser/blocks_filters/Filter_Runner.js

@@ -0,0 +1,46 @@
+const Invalid_Space_To_Allocate_Exception = require('../exceptions/Invalid_Space_To_Allocate_Exception')
+const {Logger} = require('@jetta/logger')
+const logger = new Logger('Filter Runner')
+
+/**
+ * Runs a series of filters on a list of blocks, progressively reducing the list.
+ *
+ * This function iterates through a list of provided filters, passing a data object to each.
+ * Each filter returns a new, potentially smaller, list of blocks. If the final list of blocks
+ * is empty, it means no block could pass the filters for the given empty space. In this case,
+ * the space is marked as invalid and an exception is thrown to signal that this allocation path failed.
+ *
+ * @param {Array<{ run: function(Object): Array<Object> }>} filter_list Filters with a sync `run()` method.
+ * @param {Object} filter_data The data object required by the filters.
+ * @property {Array<Object>} filter_data.block_list The initial list of blocks to filter.
+ * @property {Object} [filter_data.empty_space] The candidate empty space being evaluated.
+ * @property {Set<Object>} filter_data.spaces_to_avoid A set to record spaces that become invalid.
+ * @property {Set<Object>} filter_data.no_fillable_space_set A set to record spaces that could not be filled.
+ *
+ * @returns {Array<Object>} The final, filtered list of blocks.
+ * @throws {Invalid_Space_To_Allocate_Exception} Thrown if no blocks remain after applying all filters.
+ */
+module.exports = function run_filters(filter_list, filter_data)
+{
+    let block_list = filter_data.block_list
+
+    for (const filter of filter_list)
+    {
+        filter_data.block_list = block_list
+        block_list = filter.run(filter_data)
+    }
+
+    if (block_list.length === 0)
+    {
+        if (filter_data.empty_space)
+        {
+            filter_data.spaces_to_avoid.add(filter_data.empty_space)
+            filter_data.no_fillable_space_set.add(filter_data.empty_space)
+        }
+
+        logger.warn('no blocks left after filtering for the chosen space.')
+        throw new Invalid_Space_To_Allocate_Exception()
+    }
+
+    return block_list
+}

package/src/space_and_block_chooser/blocks_filters/initial_blocks_filter/Block_With_Overlapped_Slots_Filter.js

@@ -0,0 +1,14 @@
+const { slot_list_has_overlapped_slots } = require('../../../input_preparation/block_formatter/overlapped_slots')
+
+module.exports = class Block_With_Overlapped_Slots_Filter
+{
+    static run(filter_data)
+    {
+        return filter_data.block_list.filter(block => !this.#does_block_have_overlapped_slots(block))
+    }
+
+    static #does_block_have_overlapped_slots(block)
+    {
+        return slot_list_has_overlapped_slots(block.get_slot_list())
+    }
+}

package/src/space_and_block_chooser/blocks_filters/initial_blocks_filter/Initial_Blocks_Filter_List.js

@@ -0,0 +1,19 @@
+const Insuficient_Items_Filter = require('../pre_selection_filter/Insuficient_Items_Filter')
+const Block_With_Overlapped_Slots_Filter = require('./Block_With_Overlapped_Slots_Filter')
+const Cargo_Profile = require('../../../models/Cargo_Profile')
+
+/**
+ * Initial block filters. Overlapped-slot rejection is opt-in (prod default off).
+ * @returns {Array<{ run: Function }>}
+ */
+function build_initial_blocks_filter_list()
+{
+    const filter_list = [Insuficient_Items_Filter]
+    if (Cargo_Profile.reject_blocks_with_overlapped_slots())
+    {
+        filter_list.push(Block_With_Overlapped_Slots_Filter)
+    }
+    return filter_list
+}
+
+module.exports = build_initial_blocks_filter_list

package/src/space_and_block_chooser/blocks_filters/pos_selection_filters/Blocks_Bigger_Than_Space_Filter.js

@@ -0,0 +1,17 @@
+const math = require('@jetta/number-compare')
+
+module.exports = class Blocks_Bigger_Than_Space_Filter extends require('../Block_Filter_Interface')
+{
+    static run(filter_data)
+    {
+        return filter_data.block_list.filter(block => this.#is_block_smaller_than_empty_space(block, filter_data.empty_space))
+    }
+
+    static #is_block_smaller_than_empty_space(block, empty_space)
+    {
+        const height_fit = math.le(block.get_height(), empty_space.get_height())
+        const length_fit = math.le(block.get_length(), empty_space.get_length())
+        const width_fit  = math.le(block.get_width(),  empty_space.get_width())
+        return height_fit && length_fit && width_fit
+    }
+}

package/src/space_and_block_chooser/blocks_filters/pos_selection_filters/Post_Selection_Filter_List.js

@@ -0,0 +1,9 @@
+const Blocks_Bigger_Than_Space_Filter = require('./Blocks_Bigger_Than_Space_Filter')
+const Tie_Ratio_Orientation_Filter = require('../../../Allocation_Optimization/tie_ratio/Tie_Ratio_Orientation_Filter')
+const Tie_Ratio_Vertical_Stack_Filter = require('../../../Allocation_Optimization/tie_ratio/Tie_Ratio_Vertical_Stack_Filter')
+
+module.exports = [
+    Blocks_Bigger_Than_Space_Filter,
+    Tie_Ratio_Orientation_Filter,
+    Tie_Ratio_Vertical_Stack_Filter
+]

package/src/space_and_block_chooser/blocks_filters/pre_selection_filter/Insuficient_Items_Filter.js

@@ -0,0 +1,81 @@
+const { cube_map_function } = require('../../../Blocks_Preparation/Cube_Map_Function')
+
+module.exports = class Insuficient_Items_Filter
+{
+    static #scratch_available_shapes = new Map()
+
+    static run(filter_data)
+    {
+        const available_shapes_map = this.#get_available_shapes_map(filter_data.item_list)
+        return filter_data.block_list.filter(
+            block => this.#has_sufficient_items(block, available_shapes_map)
+        )
+    }
+
+    static #has_sufficient_items(block, available_shapes_map)
+    {
+        const required_shapes_map = this.#get_required_shapes_map(block)
+        if (required_shapes_map.size === 0)
+        {
+            return false
+        }
+
+        const scratch_map = this.#scratch_available_shapes
+        this.#copy_map_into_scratch(available_shapes_map, scratch_map)
+
+        for (const [shape_hash, required_amount] of required_shapes_map.entries())
+        {
+            const available_amount = scratch_map.get(shape_hash) || 0
+            if (available_amount < required_amount)
+            {
+                return false
+            }
+            scratch_map.set(shape_hash, available_amount - required_amount)
+        }
+
+        return true
+    }
+
+    static #copy_map_into_scratch(source_map, target_map)
+    {
+        target_map.clear()
+        for (const [shape_hash, amount] of source_map.entries())
+        {
+            target_map.set(shape_hash, amount)
+        }
+    }
+
+    static #get_required_shapes_map(block)
+    {
+        const required_shapes = new Map()
+        const slot_list = block.get_slot_list()
+
+        for (const slot of slot_list)
+        {
+            const shape_hash = cube_map_function(slot)
+            required_shapes.set(shape_hash, (required_shapes.get(shape_hash) || 0) + 1)
+        }
+
+        return required_shapes
+    }
+
+    static #get_available_shapes_map(item_list)
+    {
+        const available_shapes = new Map()
+
+        for (const item of item_list)
+        {
+            const unique_shape_hashes = new Set()
+            for (const rotated_item of item.get_all_rotated_options())
+            {
+                unique_shape_hashes.add(cube_map_function(rotated_item))
+            }
+            const item_amount = item.get_amount()
+            for (const shape_hash of unique_shape_hashes)
+            {
+                available_shapes.set(shape_hash, (available_shapes.get(shape_hash) || 0) + item_amount)
+            }
+        }
+        return available_shapes
+    }
+}

package/src/space_and_block_chooser/blocks_filters/pre_selection_filter/Pre_Selection_Filter_List.js

@@ -0,0 +1,8 @@
+const Insuficient_Items_Filter = require('./Insuficient_Items_Filter')
+const Blocks_Lower_Than_Max_Tower_Height = require('./max_tower_height/Blocks_Lower_Than_Max_Tower_Height')
+
+
+module.exports = [
+    Insuficient_Items_Filter,
+    Blocks_Lower_Than_Max_Tower_Height
+]

package/src/space_and_block_chooser/blocks_filters/pre_selection_filter/max_tower_height/Blocks_Lower_Than_Max_Tower_Height.js

@@ -0,0 +1,23 @@
+const calculate_max_tower_height = require('./Max_Tower_Height')
+const Config = require('../../../../models/Cargo_Profile')
+const number_compare = require('@jetta/number-compare')
+const Block_Filter_Interface = require('../../Block_Filter_Interface')
+
+module.exports = class Blocks_Lower_Than_Max_Tower_Height extends Block_Filter_Interface
+{
+    static run(filter_data)
+    {
+        if (!Config.enable_max_tower_cut())
+        {
+            return filter_data.block_list
+        }
+
+        const max_height = calculate_max_tower_height(filter_data.container, filter_data.item_list)
+        return filter_data.block_list.filter(block => this.#is_block_smaller_than_max_height(block, max_height))
+    }
+
+    static #is_block_smaller_than_max_height(block, max_height)
+    {
+        return number_compare.le(block.get_height(), max_height)
+    }
+}