Faza 2 — KlinesProvider

Status: deploy gotov, validacija prošla

KlinesProvider je sad default put za kline reads u svim generatorima preko _build_context.get_klines. Cache-first sa Binance fallback-om za rupe.

Šta je deploy-ovano

1. src/klines_provider.py (novi modul, ~250 lines)

API:

provider = KlinesProvider(analyzer, db_path='database/klines_cache.db')
df = provider.get(symbol, interval, start_dt, end_dt)

Karakteristike:

• WAL mode (multi-reader bez lock contention-a)
• Thread-safe (interni threading.Lock za writes)
• enable_fallback=False → testing mod (samo cache, bez Binance-a)
• enable_writes=False → read-only mod
• cache_available property — gracefully False ako cache db ne postoji
• Defenzivni filter u _read_cache: ignoriše rows gde close_time/1000 > strftime('%s', fetched_at) (open-at-fetch candles)
• INSERT OR REPLACE (umesto OR IGNORE) — stale partial rows mogu biti overwritovane

2. src/generator_manager.py izmene

# __init__:
self.klines_provider: KlinesProvider | None = None
if os.environ.get('CRYPTO_KLINES_PROVIDER_DISABLE') != '1':
    self.klines_provider = KlinesProvider(self.analyzer)

# _build_context.get_klines:
def get_klines(symbol, tf, start_dt, end_dt):
    provider = self.klines_provider
    if provider is not None:
        df = provider.get(symbol, tf, start_dt, end_dt)
        if df is not None and not df.empty:
            return df
    return self._get_klines_range(symbol, tf, start_dt, end_dt)

Sigurnosni mehanizmi:

• ENV flag CRYPTO_KLINES_PROVIDER_DISABLE=1 → potpun bypass na originalni put
• Ako provider vrati None/empty → fallback na originalni _get_klines_range
• Generator kod NIJE menjan — DataFrame schema identična

3. tools/history_cache/build_klines_cache.py fix

• Sad skipuje open candles pri insert-u (close_time_ms > now_ms)
• INSERT OR REPLACE umesto OR IGNORE
• Sprečava regresiju problema otkrivenog u validaciji (videti dole)

4. tools/history_cache/clean_stale_open_candles.py (one-shot cleanup)

Posle bulk fetch-a, otkriveno je 150 stale rows (svi koji su bili open-at-fetch):

• 15m: 10
• 1h: 1
• 4h: 70
• 1d: 69

Sve obrisano. Provider će ih ponovo povući iz Binance-a kad budu zatraženi.

Validacija

Test 1: Klines equivalence (tools/analysis/faza2_klines_equivalence.py)

Poredi KlinesProvider.get() vs _get_klines_range() (originalni Binance put) za 5 slučajeva:

5/5 PASS. Numerička greška < 1e-6 na svim OHLCV+volume kolonama.

Important: test koristi boundary - 1s da isključi tekući (još otvoren) candle. Otkrio je da open-at-fetch candles bili problematični → fix iznad.

Test 2: End-to-end performance benchmark (tools/analysis/faza2_benchmark.py)

Sve match-ovi rows (OK marker). Performance:

• Short-range queries (najčešći use case u live scenariju): 148x speedup
• Large historical ranges (365d): provider marginalno sporiji zbog DataFrame konstrukcije (1603 vs 1333ms — i dalje OK, no rate-limit pressure)

Operativni značaj

Za backtest scenarije (5y backfill)

• Pre: svaki generator backfill povlačio kline-ove direktno sa Binance-a — bottleneck na rate-limit-u
• Sad: 5y kline data je u lokalnom cache-u; generator backfill čita iz cache-a; jedini Binance pozivi su tekuci dani (sve iznad cache_max) → katalitično ubrzanje
• Bilo koji eksperiment sa parametrima generatora je sad deterministički nad istim klines snapshot-om

Za live scenarije

• Cache prozor obnovljen daily (kad se implementira Faza 3 catchup cron)
• Provider transparentno koristi cache za 99.99% prozora, Binance samo za zadnje 1-2 candle-ova
• Defensive open-candle filter u _read_cache znači da live mod uvek dobija fresh vrednost za otvoreni candle (provider re-fetches)

Robustnost

• Cache db missing → fallback na Binance put bez prekida
• Provider init failure → fallback na Binance put
• ENV CRYPTO_KLINES_PROVIDER_DISABLE=1 → eksplicitni bypass
• INSERT OR REPLACE → samo-popravljiv cache (stale rows se overwritu)

Šta NIJE deploy-ovano (Faza 3, 4)

• Daily catchup cron (Faza 3) — održava cache u trendu sa Binance-om
• Symbol churn detection — novi USDT pairs auto-backfill
• klines_features tabela sa precomputed indikatorima (Faza 4) — najveci speedup za RSI/ADX/EMA/BB/Supertrend heavy generatore

Pre-flight checks (sva tri ✅)

• [x] Determinizam: provider == direct Binance za 5 test slučajeva
• [x] Bind mount: cache db persistira između container restart-ova (~/crypto_scanner/database/klines_cache.db)
• [x] Fallback safety: provider failure ne ruši generator backfill, samo prelazi na Binance put

Provenance

• Skripte: src/klines_provider.py, tools/analysis/faza2_klines_equivalence.py, tools/analysis/faza2_benchmark.py, tools/history_cache/clean_stale_open_candles.py
• Izmene: src/generator_manager.py (KlinesProvider hook), tools/history_cache/build_klines_cache.py (skip open candles + REPLACE)
• Source: database/klines_cache.db na .88 (bind-mountovan, 2.2GB, 13.6M redova, 5y × 68 simbola × 4 intervala)
• Linked: crypto-scanner-plan-klines-cache, crypto-scanner-session-2026-05-20-deploy-and-korak-e