explodethosebits 0.3.0__cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

include/etb/bit_extraction.hpp

@@ -0,0 +1,79 @@
+#ifndef ETB_BIT_EXTRACTION_HPP
+#define ETB_BIT_EXTRACTION_HPP
+
+#include "path.hpp"
+#include <vector>
+#include <cstdint>
+
+namespace etb {
+
+/**
+ * Bit Extraction Engine - CPU Reference Implementation
+ * 
+ * Provides functions for converting between paths (bit coordinates) and byte sequences.
+ * This is the core functionality for extracting and reconstructing bit combinations.
+ */
+
+/**
+ * Extract a single bit from a byte array at the given coordinate.
+ * @param data The input byte array
+ * @param coord The bit coordinate to extract
+ * @return The bit value (0 or 1)
+ * @throws std::out_of_range if coordinate is out of bounds
+ */
+uint8_t extract_bit(const std::vector<uint8_t>& data, const BitCoordinate& coord);
+
+/**
+ * Extract a single bit from a byte array at the given coordinate.
+ * @param data Pointer to the input byte array
+ * @param data_length Length of the input byte array
+ * @param coord The bit coordinate to extract
+ * @return The bit value (0 or 1)
+ * @throws std::out_of_range if coordinate is out of bounds
+ */
+uint8_t extract_bit(const uint8_t* data, size_t data_length, const BitCoordinate& coord);
+
+/**
+ * Extract bits at specified path coordinates from a byte array.
+ * Returns the extracted bit values in order.
+ * 
+ * @param data The input byte array
+ * @param path The path containing coordinates to extract
+ * @return Vector of bit values (0 or 1) in path order
+ * @throws std::out_of_range if any coordinate is out of bounds
+ */
+std::vector<uint8_t> extract_bits_from_path(const std::vector<uint8_t>& data, const Path& path);
+
+/**
+ * Convert a sequence of bits to a byte array.
+ * Bits are packed into bytes with the first bit going to the MSB of the first byte.
+ * If the number of bits is not a multiple of 8, the last byte is zero-padded on the right.
+ * 
+ * @param bits Vector of bit values (0 or 1)
+ * @return Packed byte array
+ */
+std::vector<uint8_t> bits_to_bytes(const std::vector<uint8_t>& bits);
+
+/**
+ * Convert a path with associated bit values to a byte array.
+ * This extracts bits from the source data at path coordinates and packs them into bytes.
+ * 
+ * @param source_data The source byte array to extract bits from
+ * @param path The path specifying which bit coordinates to extract
+ * @return Packed byte array of extracted bits
+ * @throws std::out_of_range if any coordinate is out of bounds
+ */
+std::vector<uint8_t> path_to_bytes(const std::vector<uint8_t>& source_data, const Path& path);
+
+/**
+ * Convert a byte array to a sequence of bits.
+ * Each byte is unpacked to 8 bits, MSB first.
+ * 
+ * @param bytes The input byte array
+ * @return Vector of bit values (0 or 1)
+ */
+std::vector<uint8_t> bytes_to_bits(const std::vector<uint8_t>& bytes);
+
+} // namespace etb
+
+#endif // ETB_BIT_EXTRACTION_HPP

include/etb/bit_pruning.hpp

@@ -0,0 +1,122 @@
+#ifndef ETB_BIT_PRUNING_HPP
+#define ETB_BIT_PRUNING_HPP
+
+#include <cstdint>
+#include <string>
+#include <vector>
+#include <optional>
+
+namespace etb {
+
+/**
+ * Bit pruning modes that control which bit positions are explored.
+ * These modes reduce the search space from O(8^d) to smaller complexities.
+ */
+enum class BitPruningMode {
+    EXHAUSTIVE,     // All 8 bit positions (O(8^d)) - bit_mask = 0xFF
+    MSB_ONLY,       // Only bits 4-7 (O(4^d)) - bit_mask = 0xF0
+    SINGLE_BIT,     // Only 2 configured bit positions (O(2^d))
+    CUSTOM          // User-defined bit mask
+};
+
+/**
+ * Configuration for the bit pruning system.
+ * Controls which bit positions are allowed during path generation.
+ */
+struct BitPruningConfig {
+    BitPruningMode mode;
+    uint8_t bit_mask;                   // Bitmask of allowed positions (bit N set = position N allowed)
+    std::vector<uint8_t> single_bits;   // For SINGLE_BIT mode: which 2 positions to use
+    
+    /**
+     * Default constructor - exhaustive mode (all bits allowed).
+     */
+    BitPruningConfig();
+    
+    /**
+     * Construct with a specific mode.
+     */
+    explicit BitPruningConfig(BitPruningMode mode);
+    
+    /**
+     * Construct with a custom bit mask.
+     */
+    explicit BitPruningConfig(uint8_t custom_mask);
+    
+    /**
+     * Construct single-bit mode with specified positions.
+     * @param bit1 First bit position (0-7)
+     * @param bit2 Second bit position (0-7)
+     */
+    BitPruningConfig(uint8_t bit1, uint8_t bit2);
+    
+    /**
+     * Check if a bit position is allowed by this configuration.
+     * @param bit_pos Bit position (0-7)
+     * @return true if the position is allowed
+     */
+    bool is_bit_allowed(uint8_t bit_pos) const;
+    
+    /**
+     * Get the number of allowed bit positions.
+     * @return Count of set bits in the mask
+     */
+    uint8_t allowed_bit_count() const;
+    
+    /**
+     * Get all allowed bit positions.
+     * @return Vector of allowed positions (0-7)
+     */
+    std::vector<uint8_t> get_allowed_positions() const;
+    
+    /**
+     * Get the effective branching factor for complexity analysis.
+     * @return Number of choices per byte level
+     */
+    uint8_t branching_factor() const;
+    
+    /**
+     * Get a human-readable description of the configuration.
+     */
+    std::string description() const;
+    
+    /**
+     * Validate the configuration.
+     * @return true if configuration is valid
+     */
+    bool is_valid() const;
+    
+    /**
+     * Get the bit mask for use with PathGeneratorConfig.
+     */
+    uint8_t get_mask() const { return bit_mask; }
+};
+
+/**
+ * Parse a bit pruning mode from a string.
+ * @param mode_str Mode string: "exhaustive", "msb_only", "single_bit", "custom"
+ * @return Parsed mode, or std::nullopt if invalid
+ */
+std::optional<BitPruningMode> parse_bit_pruning_mode(const std::string& mode_str);
+
+/**
+ * Convert a bit pruning mode to string.
+ */
+std::string bit_pruning_mode_to_string(BitPruningMode mode);
+
+/**
+ * Create a BitPruningConfig from a mode string and optional mask.
+ * @param mode_str Mode string
+ * @param custom_mask Optional custom mask (used when mode is "custom")
+ * @param single_bits Optional single bit positions (used when mode is "single_bit")
+ * @return Configured BitPruningConfig, or std::nullopt if invalid
+ */
+std::optional<BitPruningConfig> create_bit_pruning_config(
+    const std::string& mode_str,
+    std::optional<uint8_t> custom_mask = std::nullopt,
+    std::optional<std::pair<uint8_t, uint8_t>> single_bits = std::nullopt
+);
+
+} // namespace etb
+
+#endif // ETB_BIT_PRUNING_HPP

include/etb/config.hpp

@@ -0,0 +1,284 @@
+#ifndef ETB_CONFIG_HPP
+#define ETB_CONFIG_HPP
+
+#include <cstdint>
+#include <cstddef>
+#include <string>
+#include <vector>
+#include <optional>
+#include <mutex>
+#include <functional>
+#include <atomic>
+#include "heuristics.hpp"
+#include "early_stopping.hpp"
+#include "bit_pruning.hpp"
+#include "scoring.hpp"
+#include "memoization.hpp"
+
+namespace etb {
+
+/**
+ * Error codes for configuration operations.
+ */
+enum class ConfigError {
+    NONE = 0,
+    FILE_NOT_FOUND,
+    PARSE_ERROR,
+    INVALID_VALUE,
+    MISSING_REQUIRED_FIELD,
+    TYPE_MISMATCH,
+    OUT_OF_RANGE
+};
+
+/**
+ * Result of a configuration operation.
+ */
+struct ConfigResult {
+    bool success;
+    ConfigError error;
+    std::string message;
+
+    ConfigResult() : success(true), error(ConfigError::NONE) {}
+    ConfigResult(ConfigError err, const std::string& msg)
+        : success(false), error(err), message(msg) {}
+
+    static ConfigResult ok() { return ConfigResult(); }
+    static ConfigResult fail(ConfigError err, const std::string& msg) {
+        return ConfigResult(err, msg);
+    }
+};
+
+/**
+ * Output configuration options.
+ */
+struct OutputConfig {
+    uint32_t top_n_results;         // Number of top results to return (default: 10)
+    bool save_partials;             // Save partial matches (default: false)
+    bool include_paths;             // Include reconstruction paths in output (default: true)
+    std::string metrics_verbosity;  // "minimal", "standard", "full" (default: "full")
+
+    OutputConfig()
+        : top_n_results(10)
+        , save_partials(false)
+        , include_paths(true)
+        , metrics_verbosity("full") {}
+
+    bool is_valid() const;
+};
+
+/**
+ * Performance configuration options.
+ */
+struct PerformanceConfig {
+    uint32_t max_parallel_workers;  // CPU threads for host coordination (default: 8)
+    uint32_t cuda_streams;          // Concurrent CUDA streams (default: 4)
+    uint32_t batch_size;            // Paths per kernel launch (default: 65536)
+
+    PerformanceConfig()
+        : max_parallel_workers(8)
+        , cuda_streams(4)
+        , batch_size(65536) {}
+
+    bool is_valid() const;
+};
+
+
+/**
+ * Complete configuration for the etb library.
+ * Aggregates all component configurations.
+ */
+struct EtbConfig {
+    // Paths
+    std::string signature_dictionary_path;
+
+    // Component configurations
+    EarlyStoppingConfig early_stopping;
+    HeuristicWeights heuristic_weights;
+    ScoringWeights scoring_weights;
+    BitPruningConfig bit_pruning;
+    MemoizationConfig memoization;
+    OutputConfig output;
+    PerformanceConfig performance;
+
+    // Entropy thresholds (separate from early stopping for clarity)
+    float entropy_min;              // Below this = repeated pattern garbage (default: 0.1)
+    float entropy_max;              // Above this = random/encrypted (default: 7.9)
+
+    // Text detection thresholds
+    float min_printable_ratio;      // For text detection (default: 0.95)
+    uint32_t max_null_run;          // Max consecutive nulls before penalty (default: 16)
+
+    EtbConfig();
+
+    /**
+     * Validate the entire configuration.
+     * @return ConfigResult with success/failure and error details
+     */
+    ConfigResult validate() const;
+};
+
+/**
+ * Callback type for configuration change notifications.
+ */
+using ConfigChangeCallback = std::function<void(const EtbConfig&)>;
+
+/**
+ * Configuration loader and manager.
+ * Supports JSON and YAML formats, runtime updates, and hot-reload.
+ * 
+ * Requirements: 11.1, 11.2, 11.3, 11.4, 2.7
+ */
+class ConfigManager {
+public:
+    /**
+     * Get the singleton instance.
+     */
+    static ConfigManager& instance();
+
+    /**
+     * Load configuration from a JSON file.
+     * @param filepath Path to the JSON configuration file
+     * @return ConfigResult with success/failure and error details
+     */
+    ConfigResult load_json(const std::string& filepath);
+
+    /**
+     * Load configuration from a JSON string.
+     * @param json_content JSON content as string
+     * @return ConfigResult with success/failure and error details
+     */
+    ConfigResult load_json_string(const std::string& json_content);
+
+    /**
+     * Load configuration from a YAML file.
+     * @param filepath Path to the YAML configuration file
+     * @return ConfigResult with success/failure and error details
+     */
+    ConfigResult load_yaml(const std::string& filepath);
+
+    /**
+     * Load configuration from a YAML string.
+     * @param yaml_content YAML content as string
+     * @return ConfigResult with success/failure and error details
+     */
+    ConfigResult load_yaml_string(const std::string& yaml_content);
+
+    /**
+     * Get the current configuration (thread-safe read).
+     * @return Copy of the current configuration
+     */
+    EtbConfig get_config() const;
+
+    /**
+     * Set the configuration (thread-safe write).
+     * @param config New configuration to set
+     * @return ConfigResult with validation result
+     */
+    ConfigResult set_config(const EtbConfig& config);
+
+    /**
+     * Update a specific configuration value at runtime.
+     * Only certain parameters support hot-reload.
+     * @param key Configuration key (e.g., "early_stopping.level1_threshold")
+     * @param value New value as string
+     * @return ConfigResult with success/failure
+     */
+    ConfigResult update_value(const std::string& key, const std::string& value);
+
+    /**
+     * Register a callback for configuration changes.
+     * @param callback Function to call when configuration changes
+     * @return ID for unregistering the callback
+     */
+    size_t register_change_callback(ConfigChangeCallback callback);
+
+    /**
+     * Unregister a configuration change callback.
+     * @param id Callback ID returned by register_change_callback
+     */
+    void unregister_change_callback(size_t id);
+
+    /**
+     * Reload configuration from the last loaded file.
+     * @return ConfigResult with success/failure
+     */
+    ConfigResult reload();
+
+    /**
+     * Check if a configuration file has been loaded.
+     */
+    bool is_loaded() const { return loaded_.load(); }
+
+    /**
+     * Get the path of the last loaded configuration file.
+     */
+    std::string get_loaded_path() const;
+
+    /**
+     * Reset to default configuration.
+     */
+    void reset_to_defaults();
+
+    /**
+     * Save current configuration to a JSON file.
+     * @param filepath Path to save to
+     * @return ConfigResult with success/failure
+     */
+    ConfigResult save_json(const std::string& filepath) const;
+
+    /**
+     * Save current configuration to a YAML file.
+     * @param filepath Path to save to
+     * @return ConfigResult with success/failure
+     */
+    ConfigResult save_yaml(const std::string& filepath) const;
+
+    /**
+     * Get configuration as JSON string.
+     */
+    std::string to_json_string() const;
+
+    /**
+     * Get configuration as YAML string.
+     */
+    std::string to_yaml_string() const;
+
+private:
+    ConfigManager();
+    ~ConfigManager() = default;
+    ConfigManager(const ConfigManager&) = delete;
+    ConfigManager& operator=(const ConfigManager&) = delete;
+
+    mutable std::mutex mutex_;
+    EtbConfig config_;
+    std::string loaded_path_;
+    std::atomic<bool> loaded_;
+    std::vector<std::pair<size_t, ConfigChangeCallback>> callbacks_;
+    size_t next_callback_id_;
+
+    void notify_callbacks();
+    ConfigResult parse_json_object(const std::string& json_content);
+    ConfigResult parse_yaml_content(const std::string& yaml_content);
+    
+    // Helper functions for parsing
+    static bool parse_bool(const std::string& value, bool& out);
+    static bool parse_float(const std::string& value, float& out);
+    static bool parse_uint32(const std::string& value, uint32_t& out);
+    static bool parse_size_t(const std::string& value, size_t& out);
+};
+
+/**
+ * Helper function to load configuration from file (auto-detects format).
+ * @param filepath Path to configuration file (.json or .yaml/.yml)
+ * @return ConfigResult with success/failure
+ */
+ConfigResult load_config(const std::string& filepath);
+
+/**
+ * Get the default configuration.
+ */
+EtbConfig get_default_config();
+
+} // namespace etb
+
+#endif // ETB_CONFIG_HPP