OjV~UdZddlmZddlZddlmZmZddlmZm Z m Z m Z ddl m Z ddlmZej eZdZd Zd Zd dd d Zded<dZddZdZdZdZGddee Zy)u~C(c) producer — 구간당 **단일 판독** + compact evidence merge. ★아직 안 켠다. ## 무엇을 대신하나 지금은 원문 전문이 **네 번**(`grounding_a0` + `entity_extract_*` 셋), 샷 전부가 **세 번**(`entity_all_*`) 나간다. 이 스텝은 그것을 **구간 수 + 1** 로 줄인다 — 구간마다 한 번 읽고, 마지막에 한 번 합친다. ## ★아직 아무 데도 안 붙어 있다 `step_manifest` 에도 `STEP_CLASSES` 에도 없다. `uses_chunk_producer(mode)` 가 True 일 때만 도는데, 그 모드(`v2_chunk`)를 **아무도 안 쓴다.** 사람이 v3 검토 화면에서 샷 결속 의미·두 축·엔티티 품질을 보고 GO 를 준 뒤에 켠다. ## 이 파일이 **안 하는** 것 - 승인 없이 provider 를 부르지 않는다 — `uses_chunk_producer` 가 False 면 **한 푼도 안 쓰고** 돌아간다 - 구간 나누기·payload 조립·행 해석·합치기·adapter 를 **다시 적지 않는다**. 전부 이미 있는 함수를 부른다. 여기서 다시 적으면 도구가 재는 것과 주행이 굽는 것이 갈린다 - 샷 `description` 을 **자르지 않는다** ) annotationsN)ThreadPoolExecutor as_completed)AnyDictListOptional) StepRunner)_EntityStepMixin g @gr@Fg?)enable_fallback num_retries temperatureDict[str, Any]REQUEST_CONTRACTc|jdrdnd}t|jdxsd}td||zd|zzS)u@한 논리 호출이 여는 **물리 최대**. ★계약이 바뀌면 같이 바뀐다. ★글 호출 경로(`_completion`)에는 이미지 쪽 `reserve_current_call` 같은 **세는 자리가 없다.** 그래서 물리 수를 「막을」 수는 없고, 대신 **구조적으로 상한을 정한다** — 재시도와 fallback 을 끄면 남는 것은 키 슬롯 loop 뿐이고 그것은 `slot_count()` 로 위가 정해진다. ★이것은 **상한이지 실측이 아니다.** 실제로 몇 번 나갔는지는 Opik+provider 로그로 본다. r rr)getintmax)request_contractslotstiersretriess Y/Users/manta/Documents/Projects/TheRoad-I1/backend/app/core/steps/grounding_chunk_step.pyphysical_per_logicalrJsN"%%&78AaE"&&}5:;G q%=5 AK 00grounding_chunk_readzop:grounding-chunkcc_call_identityceZdZdZddZdddZdZdZddZddZ ddZ dd Z dd Z dd Z dd ZddZd ddZd d ddZdd dZedZddZy )!GroundingChunkStepuU구간당 단일 판독 producer. ★`v2_chunk` 모드에서만 산다. ★★★`_EntityStepMixin` 을 **왜 쓰나** — `_load_prev_checkpoint` 때문이다. 이 스텝은 `scene_save`·`shot_validator`·`visual_world_rules` 체크포인트를 읽는데, 그 함수는 `StepRunner` 에 없고 스텝마다 각자 갖고 있다. 이웃인 `GroundingScreenStep` 도 같은 이유로 이 mixin 을 쓴다. ★실측 (2026-09-02 유료 canary ①): 이것이 없어서 첫 실주행이 `AttributeError: 'GroundingChunkStep' object has no attribute '_load_prev_checkpoint'` 로 죽었다. **시험은 CP 를 손으로 넣어 줘서** 이 자리를 한 번도 안 지났다 — producer 가 실제로 돈 적이 없었다. ★이 클래스가 제 `_config_hash` 를 갖고 있으므로 mixin 것에 안 가린다. cddl}ddl}ddlm}ddlm}ddlm}ddlm}ddlm }||ji|jd|d |ji|j|j|j|j |j"d d }|j%|j'|d d j)dj+ddS)uf★팩 **바이트**와 계약을 지문에 접는다. 안 접으면 팩·후처리 계약·adapter 를 고쳐도 resume 이 **옛 체크포인트를 그대로 건너뛴다** — 고친 것이 아무 데도 안 닿는다. 버전 문자열만 접으면 같은 버전 디렉토리의 **내용**을 고쳤을 때 못 잡는다. rN)compute_config_hash)_pack_fingerprintgrounding_chunkgrounding_chunk_adapter)grounding_chunk_plan pack_bytesr()contractadapter chunk_plan bundle_target)base acquisition admission processingTF) sort_keys ensure_asciizutf-8)hashlibjsonapp.core.step_runnerr%app.core.steps.grounding_stepsr&app.modules.pipeliner(r*r+project_config _acquisitionCHUNK_PACK_VERSION _admissionPROCESSING_CONTRACT_VERSIONADAPTER_CONTRACT_VERSIONCHUNK_PLAN_CONTRACT_VERSION BUNDLE_TARGETsha256dumpsencode hexdigest) selfr8_jsonr%r&gcadcppayloads r _config_hashzGroundingChunkStep._config_hashns <D>FC((;(;<##%/0A020E0EG *::66 < I>E 8 $%--l;ArLL(.B33J?E2 0 ;#@cS S,,-=>D"++f%+00:@b--.BCIr*84 05= ! ! ,H5"#!A}-./!%%-2E2E! #;C E;Ca}-23AEE&M/R02;C EF&(!g&DAq)*+AVA3<C+""63/CD1QCM KKsGC11#tU?B2D  'T4&&## E ,s+/G!"AG& G+cddlm}m}||j|z |j t |d}|j rtjd|S)uE구간 장부. ★계약이 바뀌었으면 **이어 쓰지 않고** 새로 시작한다. 신원(`acquisition_identity`)이 팩·모델·요청 계약을 접으므로 사실은 저절로 안 맞지만, 계약 자체를 장부에 적어 두면 **왜 다시 사는지**가 기록에 남는다. r) ChunkJournal JOURNAL_NAME)r2chunks)r-utgrounding_chunk: 획득 계약이 바뀌었다 — 신원이 다른 것만 다시 산다(장부는 그대로 둔다)) ,app.modules.pipeline.grounding_chunk_journalrr_cp_dirr>rcontract_driftedr^r_)rIrhrrrls rrazGroundingChunkStep._journals^ ($,,5373D3D3F.1$i$9:     KKK L rcddlm}ddlm}|j||j|j |j ttdS)u**provider 응답의 뜻을 지배하는 것만**. ★신원은 이것만 접는다. ★★세 가지를 갈라야 한다 (Codex 2026-08-31) — provider 획득 payload · 모델 · **실제 전송 인자** → 바뀌면 **다른 답**이다. 다시 산다 admission 정책 마감 · 슬롯 · 예산 → 「언제·몇 번 보낼까」지 **답의 뜻이 아니다**. 여기 넣으면 정책만 바꿔도 raw 를 재구매한다 해석 후처리 · adapter · 구간 나누기 → 무료 재해석 ★`max_tokens` 는 **실제 전송 인자**라 여기 든다 — 앞 판엔 빠져 있었다. r)_resolve_modelr')aliasphysicalpackrequest) app.modules.llm.llm_clientrr<r(step_idr=r?dictr)rIrrKs rr>zGroundingChunkStep._acquisitionsC >>\\&t||T5H5HI)),-   rc|ddlm}|j}t|t t ||j dS)u**언제·몇 번 보낼까**. ★신원에 안 접는다 — 답의 뜻이 아니다. 지문에는 **따로** 접는다. 정책이 바뀌면 「같은 조건에서 돌았다」가 거짓이 되지만, 이미 산 raw 는 **여전히 그 답**이다. r) openai_keys)r\rrtransmission_cap)app.corer slot_countrerrrd)rIrrs rr@zGroundingChunkStep._admissions@ )&&( 6$89I9>%@ $ 6 6 8   rcZt|jjdxstS)uR물리 전송 상한. ★`grounding_research` 와 **같은 설정 키**를 본다.research_transmission_cap)rr=rDEFAULT_TRANSMISSION_CAP)rIs rrdz$GroundingChunkStep._transmission_cap/s+4&&**+FG/.0 0rcfddlm}|j}|||d|dd|di|dS)u호출 **신원** — 팩·모델·**실제 요청 계약**까지 접는다. ★production 함수 한 곳(`acquisition_identity`)이 만든다 — 감사 도구와 같은 것이라 장부·trace 대조가 성립한다. r)acquisition_identityrrrr) model_aliasmodel_physicalr)$app.modules.pipeline.grounding_chunkrr>)rIrNracqs r _identityzGroundingChunkStep._identity4sI N!# Wc*o$c&kDS^DF Frct|dzS)uN논리 상한 — 구간 수 + merge 1. ★계획에서 **한 번만** 센다.r)r)rIrhs r_capzGroundingChunkStep._capAs4y1}rc |j}|d}|j|t|dz}||kDr0ddlm}|dd|d|d|j|d |dd d |S) u물리 **상한**이 승인 범위 안인가. ★넘으면 provider 앞에서 선다. ★막는 것이 아니라 **정하는 것**이다 — 글 호출 경로에는 세는 자리가 없어서 물리 수를 그 자리에서 거절할 수 없다. 대신 재시도·fallback 을 끄고 슬롯 수로 위를 정한 뒤, 그 수가 **손으로 적은 승인 수**를 넘으면 아무것도 안 사고 선다. rrrrz'grounding_chunk.physical_bound_exceededu물리 상한이 u 인데 승인 전송 상한은 u 이다 (논리 u × 슬롯·재시도 ug) — 사람이 `research_transmission_cap` 을 다시 정해야 한다. 아무것도 안 사고 선다ir)r@rrrr)rIrhadmr[rmrs rrcz)GroundingChunkStep._assert_physical_boundEsoo$% $#c*@&A"BB 3; 0>,UG3STWSXY$$(IIdO#44J 6789::  ! ! rNcddlm}ddlm}ddlm}g}g} g} i} t ttt|5} ||j} |Dcic])}| j| |||j||d+}}t|D]}||} |j| |< d d d |D]j}| j)|d}||j+|j)d xsg|d|d ||j)|d }||d z }| |d z } l| r@ddlm}|ddt| dt|d| Dcgc]\}}| c}}dd|| | fScc}w#t$rT}||rt j#d|t j%d||| j'||fYd }~:d }~wwxYw#1swY%xYwcc}}w)uU구간마다 **한 번** 읽는다 — 병렬. ★행 해석은 production 함수가.rr')bind_current_research_budget)is_abort) max_workersrugrounding_chunk 중단 — %sugrounding_chunk %s 실패: %sNrur)rrrrrvrzgrounding_chunk.incomplete_readu구간 /u 을 못 읽었다 (u) — 등록 횟수는 구간을 걸쳐 세므로 남은 것만으로 내면 **수가 틀린다**. 재개해서 빠진 구간만 다시 읽어야 한다ir)r<r(rbrapp.core.run_controlrrmin MAX_WORKERSr_onesubmitrrresult Exceptionr^warningerrorrr resolve_rowsrr)rIrhrirjrlrKrrrurvfailedgotexsendrfutsfcidexcrespoutrrws rrrzGroundingChunkStep._read_chunks^s>N1%',.   C 03D -;/3xx* /F"HC CK D 3}- -K  06"3v;-qT <,23FDAqaF345QQ  [&((Y1 ! .  }'FLLL!@#sKMM3*-- .< ) zz!R112s!' *(='>?A Arrc  ddlm ddlmddlm ddlm}ddlm j   fd}||S|| |||fd S) u산다 — **장부·예산·정지를 거쳐서**. ★한 곳에서만 보낸다. ## ★신원은 `opik_metadata` 로는 **안 간다** litellm 이 `metadata["opik"]` 에서 읽는 키는 **넷뿐**이다 (`project_name`·`current_span_data`·`tags`·`thread_id`, `llm_client._build_opik_metadata` 주석). 다른 키는 조용히 버려지고, 태그로 실어도 **축 whitelist**(`is_axis_tag`)가 거른다. ★이 결함을 앞서 한 번 겪고 기억에 적었는데 **다시 냈다** (Codex 2026-08-31). 신원은 **부모 trace 의 metadata** 로 간다 — 감사 도구(`cc_runner.live_send`)가 쓰는 바로 그 자리다. r)research_calls_armed)call_structured) open_trace) buy_or_reuse)call_with_deadlinecttgtdjdijdj di55jdddt jdtgitd td td  cdddcdddS#1swYnxYw dddy#1swYyxYw) Nstepschema:identity)nametagsmetadata thread_id input_datasystempartsrrr r)r\r= schema_name opik_metadatarr r) CHUNK_TRACE_NAME CHUNK_TAG ID_META_KEYr project_id episode_idCHUNK_CALL_DEADLINE_SECONDSr=r)rridentrrNrrrIsr_sendz'GroundingChunkStep._call.._sends!1 &15&,dll&. &=*.(94??:K&L(2E': <*+-' gh&79I))D'+':':$/'- {&;$4]$C(89J(K$4]$C E,+<<,++<<z*GroundingChunkStep._call..s"t33( 6t 4 Er)r[rr stop_check) rbrrrapp.modules.llm.opik_tracerrr!app.modules.pipeline.llm_deadlinerr) rIrNrrlr[rrrrrrrrs ``` @@@@@rrzGroundingChunkStep._calls] G>9MHw' E E< :7N 3UEF Frc fddlm}ddlm}|s|jgg|S|j dd|j |}|j ||j||xs#|r|jjddd zndd }|j||jd xsg|S) Nrr')grounding_chunk_merge)rzgrounding_chunk mergeTrrrmerger decisions) r<r(rreduce_episoder build_merge_payloadrMERGE_SCHEMA_NAMEr-r) rIrurirlr[rKcmrrs rrszGroundingChunkStep._merges>D$$Rd$; ; #:4H  " "4 (zz!R112*b"++//(A">"B'(9  txx '<'B*.!0 0rc6|jdxsifd}g}|jdxsdD]Q}||xsijd||xsijd}}|s<|s?|j||fStt|S)uT`part_of` 를 **정본 ID 짝**으로. ★등록된 것만 — 없으면 안 낸다. registeredcxtjt|xsijdxsdS)Nfinal_idr)strr)lidregs r_fidz3GroundingChunkStep._part_of_final_ids.._fids0S*0b55jAHbI Irpart_ofpartwhole)rrsortedset)rxrrxrwrs @r_part_of_final_idsz%GroundingChunkStep._part_of_final_idsskk,'-2 J++i(.B.Ab f-.ag2]]75K0LqAQ Aq6"/c#hrcbddlm}ddlm}ddlm} |j ||j |j } | j|d|jdxsg|jdxsi} | j| d |jt|t|d|t||r|jnt||rd ndz|j||jd |j|z|jd |j |j"|j$d d| dg| d| jdxsg| d||D cgc]V} | jdrC| jd| jd| jd| jddXc} |j'|D cgc] \} }| |d c}} | d | d|jdxsi|jdxsid dScc} wcc}} w)uO★`entity_merge` 모양과 **근거**를 함께 낸다. adapter 가 짓는다.rr'r))grounding_facet_binding)rrrurrbindingsrrT)rr4r.)rSrrU logical_capphysical_upper_boundrcomplete contracts candidates facet_debtrTsalvage_problemslocal_id owner_type surface_form)r2r3r4problems)r!r"debtcountsrefused) removedgrounding_candidatesgrounding_facet_debt_rowsgrounding_skippedgrounding_quarantinedgrounding_salvagedgrounding_part_ofgrounding_facet_bindingsgrounding_facet_debtgrounding_countsgrounding_refused) config_hashrVrWrXrY)r<r(r*r)project_rows_and_candidatesrrbindrassert_owner_pairsrOrboughtrr@rdr?rArBr')rIrgrhrurvrxrlrKrLfb projectedfacetr%r_wids rrtzGroundingChunkStep._wraps=>FF22 DOO3M Y)?)E2 L17R9 eJ/0  ,,."4y #D d)35299;(+D $QA(F#yy)-(9*),.2iio)>$($:$:$< 11"$"@"@!::,(F#),*(1,(?-6]]<-H-NB%.y%9)4"'@"QUU+=%>"#z!2!%% BU%&UU>%:N`Hac!'@'+&=&=g&F&H&F d"D1&F&H-2*,=(-f $+KK$9$?R%,[[%;%ArW,6 6 N'@&Hs -AH&H+)returnr)resume)rSrrMr)rMr)rMr)rMr)rNrrMrrp)Nr)rrr[rrMr) rNrrrr[rrz Optional[str]rMr)r[r)__name__ __module__ __qualname____doc__rOrnrfr`rar>r@rdrrrcrrrrrs staticmethodr'rtr rrr#r#_s %NN;:H0'd2 2 "0 F2<)|A A(,:F$:F0>:Fz0$    F rr#)rrrrrMr)rR __future__rloggingconcurrent.futuresrrtypingrrrr r:r app.core.steps.entity_stepsr getLoggerrOr^rrerr__annotations__rrrrrr#r rrr[s.#?,,+8   8 $ $$. 1*  i ):i r