"""
FibPi SHA Anchor Tools - Advanced encoding and analysis

Levels:
    - fibpi_sha_anchor: Base encoder/decoder with SHA256 anchors at Fibonacci positions
    - fibpi_index (Level 4): Persistent index for O(1) random access open
    - fibpi_parallel (Level 5): Multi-threaded parallel chunk decoding
    - fibpi_encoded_ops (Level 6): Encoded-domain operations (grep, entropy, diff)
    - fibpi_zlib_wrapper: Random-access compression with per-chunk zlib streams
    - fibpi_gzip_compat: Gzip-compatible mode with sidecar index
    - fibpi_zlib_cli: Command-line interface

CDNA Analysis Tools:
    - cdna_code_stats: Histogram/stats utilities for CDNA indices
    - cdna_regen_experiment: Test whether CDNA codes can be regenerated from seeds

Usage:
    from helix_cdc.echo_core.tools import (
        FibPiShaEncoder, FibPiShaDecoder, FibPiRandomAccess,
        FibPiIndexManager, FibPiRandomAccessIndexed,
        ParallelChunkDecoder,
        EncodedDomainOperations,
        FibPiZlibWrapper, FibPiZlibIndex,
        GzipCompatibleFibPi,
        # CDNA tools
        build_histogram, histogram_entropy, regen_from_histogram,
        compute_match_metrics, compute_residual, CDNARegenExperiment,
    )

Note: zlib/gzip modules use lazy imports to avoid `python -m` RuntimeWarning
and keep CLI startup fast.
"""

from typing import TYPE_CHECKING

# Eager imports for established modules (lightweight, no CLI conflict)
from .fibpi_sha_anchor import (
    FibPiShaEncoder,
    FibPiShaDecoder,
    FibPiRandomAccess,
    encode_with_compression,
    decode_with_compression,
    sha256_hex
)

from .fibpi_index import (
    FibPiIndexManager,
    FibPiRandomAccessIndexed,
    ChunkInfo,
    benchmark_indexed_vs_unindexed
)

from .fibpi_parallel import (
    ParallelChunkDecoder,
    BufferedChunkReader,
    decode_file_parallel
)

from .fibpi_encoded_ops import (
    EncodedDomainOperations,
    Match,
    EntropyResult,
    StringMatch
)

# CDNA analysis tools
from .cdna_code_stats import (
    build_histogram,
    histogram_entropy,
    shake256_rng,
    regen_from_histogram,
    compute_match_metrics,
    compute_residual,
    decode_residual,
    summarize_codebook,
)

from .cdna_regen_experiment import (
    CDNARegenExperiment,
    load_cdna_shard,
    run_batch_experiment,
)

# TYPE_CHECKING block for IDE/type checker support of lazy modules
if TYPE_CHECKING:
    from .fibpi_zlib_wrapper import (
        FibPiZlibWrapper,
        FibPiZlibIndex,
        ChunkIndex,
        create_sidecar_index
    )
    from .fibpi_gzip_compat import (
        GzipCompatibleFibPi,
        SidecarIndex,
        SidecarEntry,
        ConcatenatedGzipReader,
        create_sidecar_from_concatenated_gzip
    )

# Lazy import names for zlib/gzip modules
_ZLIB_WRAPPER_NAMES = {
    "FibPiZlibWrapper",
    "FibPiZlibIndex",
    "ChunkIndex",
    "create_sidecar_index",
    "MAGIC",
    "INDEX_MAGIC",
}

_GZIP_COMPAT_NAMES = {
    "GzipCompatibleFibPi",
    "SidecarIndex",
    "SidecarEntry",
    "ConcatenatedGzipReader",
    "create_sidecar_from_concatenated_gzip",
    "SIDECAR_MAGIC",
}

# Cache for lazy-loaded modules
_lazy_cache = {}


def __getattr__(name: str):
    """
    Lazy import handler for zlib/gzip modules.

    This prevents `python -m helix_cdc.echo_core.tools.fibpi_zlib_wrapper` from
    triggering RuntimeWarning due to pre-import side effects.
    """
    if name in _ZLIB_WRAPPER_NAMES:
        if "fibpi_zlib_wrapper" not in _lazy_cache:
            from . import fibpi_zlib_wrapper
            _lazy_cache["fibpi_zlib_wrapper"] = fibpi_zlib_wrapper
        return getattr(_lazy_cache["fibpi_zlib_wrapper"], name)

    if name in _GZIP_COMPAT_NAMES:
        if "fibpi_gzip_compat" not in _lazy_cache:
            from . import fibpi_gzip_compat
            _lazy_cache["fibpi_gzip_compat"] = fibpi_gzip_compat
        return getattr(_lazy_cache["fibpi_gzip_compat"], name)

    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")


__all__ = [
    # Base encoder/decoder
    'FibPiShaEncoder',
    'FibPiShaDecoder',
    'FibPiRandomAccess',
    'encode_with_compression',
    'decode_with_compression',
    'sha256_hex',
    # Level 4: Index
    'FibPiIndexManager',
    'FibPiRandomAccessIndexed',
    'ChunkInfo',
    'benchmark_indexed_vs_unindexed',
    # Level 5: Parallel
    'ParallelChunkDecoder',
    'BufferedChunkReader',
    'decode_file_parallel',
    # Level 6: Encoded Ops
    'EncodedDomainOperations',
    'Match',
    'EntropyResult',
    'StringMatch',
    # Zlib wrapper (random-access compression) - lazy loaded
    'FibPiZlibWrapper',
    'FibPiZlibIndex',
    'ChunkIndex',
    'create_sidecar_index',
    # Gzip-compatible mode - lazy loaded
    'GzipCompatibleFibPi',
    'SidecarIndex',
    'SidecarEntry',
    'ConcatenatedGzipReader',
    'create_sidecar_from_concatenated_gzip',
    # CDNA analysis tools
    'build_histogram',
    'histogram_entropy',
    'shake256_rng',
    'regen_from_histogram',
    'compute_match_metrics',
    'compute_residual',
    'decode_residual',
    'summarize_codebook',
    'CDNARegenExperiment',
    'load_cdna_shard',
    'run_batch_experiment',
]
