# OntoCast Vendored Copy — 수정 내역

본 디렉터리는 OntoCast의 vendored copy다.

- **원본 저장소**: https://github.com/growgraph/ontocast
- **원본 라이선스**: Apache License 2.0 (`LICENSE` 파일 참조, 변경 금지)
- **vendored 시점 버전**: 0.3.0
- **vendored 시점**: 2026-05-13

## Apache 2.0 의무사항

본 vendored copy 내의 파일을 수정할 경우 Apache License 2.0 §4(b) 요구사항에 따라:

1. 수정된 파일 상단에 `# MODIFIED YYYY-MM-DD: <한 줄 설명>` 주석을 추가한다
2. 본 문서(`VENDORED_MODIFICATIONS.md`)에 수정 내역을 항목으로 기록한다
3. 원본 `LICENSE` 파일은 절대 삭제하거나 변경하지 않는다

## 수정 내역 (시간순)

### 2026-05-13 — vendored copy 생성
- 원본 https://github.com/growgraph/ontocast (v0.3.0)을 `vendored/ontocast/`로 복사
- 아직 어떠한 파일도 수정하지 않은 상태

### 2026-05-13 — Phase 0.3: convert_document.py 다중 파일 처리 확장
- **파일**: `ontocast/agent/convert_document.py`
- **문제**: 루프는 모든 `state.files`를 순회하지만 `state.set_text(result["text"])`가 매 반복에서 덮어써 마지막 파일의 텍스트만 살아남았다(`"NB: processing only one file"` 주석으로 의도가 명시되어 있던 부분).
- **수정**: 텍스트를 `texts: list[str]`에 누적하고 파일이 2개 이상이면 `=== File: <name> ===` 경계 마커를 사이에 삽입해 단일 corpus로 합친다. 단일 파일 입력은 마커 없이 통과하여 기존 단일 파일 동작과 byte-identical. JSON envelope의 `ontology_user_instruction` / `facts_user_instruction` / `url`은 first-wins (한 corpus는 하나의 instruction이라는 모델). 첫 unsupported 확장자에서 fail-fast하는 기존 동작 유지.
- **회귀 테스트**: `tests/unit/test_convert_document.py` (7 케이스 — 단일 PDF / 단일 JSON / 다중 PDF / 다중 JSON first-wins / 미지원 확장자 / 빈 입력 / 혼합 PDF+JSON)
- **근거**: docs/통합설계서.md §5 Phase 0, OntoCast 분석 §13.1 / §21.1 (#4)

### 2026-05-14 — node_factories.py: BudgetTracker가 LLM 호출을 기록하지 못하던 버그 수정
- **파일**: `ontocast/stategraph/node_factories.py`
- **문제**: `make_render_ontology_node`(line 91)와 `make_render_facts_node`(line 256)에서 병렬 unit 처리 시 `base_state = state.model_copy(deep=True)`로 root state를 deep-copy 한 뒤 `budget_tracker=base_state.budget_tracker`를 child state(`UnitOntologyState`/`UnitFactsState`)에 전달했다. 그 결과 LLM이 add_usage()를 호출해도 *복사본* 인스턴스만 갱신되고 root state.budget_tracker는 영원히 0인 채로 남아 BudgetTracker가 LLM 호출 수, chars sent/received를 전혀 기록하지 못했다. e2e 실행 시 LM Studio 로그에 LLM 호출이 분명히 들어왔는데(token count 검증됨) workflow_state["budget_tracker"].calls_count == 0으로 응답되는 증상으로 확인됨.
- **수정**: 두 곳 모두 `base_state.budget_tracker` → `state.budget_tracker`로 변경. `base_state = state.model_copy(deep=True)` 라인 자체가 budget_tracker 추출에만 쓰였으므로 함께 제거. Python int `+= 1` 연산은 GIL 하에서 원자적이라 병렬 process_unit 간 race condition은 무시 가능한 수준.
- **회귀 테스트**: e2e (`tests/e2e/test_phase0_full_pipeline.py`)에서 `budget.calls_count > 0` 검증.
- **근거**: docs/phases/PHASE0_ACCEPTANCE_GATE.md (Gate #3 통과를 위한 차단 이슈).

### 2026-05-14 — render_ontology.py: Bootstrap KeyError 수정
- **파일**: `ontocast/agent/render_ontology.py`
- **문제**: `vendored/ontocast/ontocast/prompt/render_ontology.py:44`의 `general_ontology_instruction = f"""...{prefix_instruction}..."""`이 f-string이라 모듈 로드 시점에 `prefix_instruction` 변수가 즉시 치환됨. 그 결과 최종 문자열에는 `prefix_instruction` 자체가 가진 `{ontology_prefix}` placeholder만 남는다. `render_ontology_update`는 호출 시 `ontology_prefix=current.prefix`도 함께 넘기지만 `render_ontology_fresh`는 누락 → Bootstrap 단계에서 `KeyError: 'ontology_prefix'`.
- **수정**: `render_ontology_fresh()`의 `.format()` 호출에 `ontology_prefix=""`를 추가. Bootstrap 시점에는 prefix가 아직 LLM에 의해 정의되지 않으므로 빈 문자열이 의미적으로 올바름.
- **회귀 테스트**: e2e (`tests/e2e/test_phase0_full_pipeline.py`)에서 검증.
- **근거**: docs/phases/PHASE0_ACCEPTANCE_GATE.md (Gate #1 통과를 위한 차단 이슈).

### 2026-05-13 — Phase 0.2: select_ontology.py None-index 버그 수정
- **파일**: `ontocast/agent/select_ontology.py`
- **문제**: dynamic Pydantic 모델은 `answer_index ∈ [1, num_ontologies + 1]`을 강제하지만 코드는 `answer_index == 0`을 "None"으로 처리. 0은 Pydantic 검증을 통과할 수 없어 dead code였으며, LLM이 None을 선택할 때마다(`num_ontologies + 1` 반환) defensive branch로 빠져 WARNING 로그가 찍혔다.
- **수정**: `none_index = num_ontologies + 1` 분기 추가, `answer_index == 0` 분기 제거. 파일 상단에 `MODIFIED 2026-05-13` 주석 추가.
- **회귀 테스트**: `tests/unit/test_select_ontology.py` (4 케이스 — 빈 ontology / 정상 선택 / None 선택 / 범위 밖)
- **근거**: docs/통합설계서.md §5 Phase 0, OntoCast 분석 §13.1

## 우리 프로젝트에서의 사용 방식

- `vendored/ontocast/ontocast/` 패키지는 우리 코드(`platform/`)에서 import하여 사용한다
- OntoCast의 코어 모듈(`stategraph/`, `agent/`, `onto/`, `tool/`)은 **수정 최소화**
- API 레이어(`vendored/ontocast/ontocast/cli/serve.py` Robyn)는 사용하지 않고 우리가 FastAPI로 재작성한다
- OntoCast 자체의 `pyproject.toml`은 참고용이며, 의존성은 프로젝트 루트의 `pyproject.toml`이 우선