---
phase: 04-python-efficiency
plan: 01
subsystem: python-performance
tags: [pydantic, config-caching, vision-ttl, dataframe, kintsugi, backfill]

requires: []
provides:
  - "Cached _kintsugi_cfg() in _repair() — 0 redundant pydantic instantiations per shard"
  - "Dynamic Vision 404 TTL — 15min for recent dates, 1h for older"
  - "Removed redundant DataFrame copy in store_bars_bulk() non-DatetimeIndex path"
affects: []

tech-stack:
  added: []
  patterns:
    - "Cache pydantic config at function scope when accessed multiple times"
    - "Dynamic TTL based on date proximity to today"

key-files:
  created: []
  modified:
    - python/opendeviationbar/kintsugi.py
    - python/opendeviationbar/backfill.py
    - python/opendeviationbar/config/backfill.py
    - python/opendeviationbar/clickhouse/bulk_operations.py

key-decisions:
  - "Dynamic Vision TTL uses 2-day window (dates within 2 days of today get 15min TTL)"
  - "Removed bars.copy() — store_bars_bulk() is terminal consumer, no caller reads DataFrame after"

patterns-established:
  - "Config caching: bind pydantic model to local var when accessed 2+ times in a function"

requirements-completed: [PYEF-01, PYEF-02, PYEF-03]

duration: 2min
completed: 2026-03-20
---

# Phase 4 Plan 1: Python Efficiency Summary

**Cached kintsugi config per repair (3 instantiations eliminated), dynamic Vision 404 TTL (15min for T-2 dates), and removed redundant DataFrame copy in bulk operations**

## Performance

- **Duration:** 2 min
- **Started:** 2026-03-20T08:57:27Z
- **Completed:** 2026-03-20T08:59:44Z
- **Tasks:** 2
- **Files modified:** 4

## Accomplishments

- Eliminated 3 redundant `_kintsugi_cfg()` pydantic instantiations per shard repair (PYEF-01)
- Added `vision_probe_ttl_recent_s = 900` to BackfillConfig; recent Vision 404s now cached 15min instead of 1h (PYEF-02)
- Removed unnecessary `bars.copy()` in `store_bars_bulk()` non-DatetimeIndex path (PYEF-03)

## Task Commits

Each task was committed atomically:

1. **Task 1: Cache \_kintsugi_cfg() in \_repair() + add dynamic Vision TTL** - `9bcecfc` (feat)
2. **Task 2: Remove redundant DataFrame copy in store_bars_bulk()** - `8ab09b2` (perf)

## Files Created/Modified

- `python/opendeviationbar/kintsugi.py` - Bound `cfg = _kintsugi_cfg()` once in `_repair()`, replaced 3 bare calls with `cfg.batch_days` / `cfg.batch_workers`
- `python/opendeviationbar/backfill.py` - Dynamic TTL in `_mark_vision_unavailable()`: 15min for dates within 2 days, 1h otherwise; updated log message
- `python/opendeviationbar/config/backfill.py` - Added `vision_probe_ttl_recent_s: int = 900` field
- `python/opendeviationbar/clickhouse/bulk_operations.py` - Changed `df = bars.copy()` to `df = bars`

## Decisions Made

- Dynamic Vision TTL uses 2-day window: dates within 2 days of today get 15min TTL, older get 1h. This matches Vision archive publication lag.
- Removed `bars.copy()` after confirming all callers of `store_bars_bulk()` are terminal (no post-call DataFrame reads).

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- All three PYEF requirements complete
- No blockers for future phases

---

_Phase: 04-python-efficiency_
_Completed: 2026-03-20_

## Self-Check: PASSED
