agent-common 0.4.76__tar.gz → 0.4.78__tar.gz

{agent_common-0.4.76 → agent_common-0.4.78}/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 > [ 🇺🇸 English Version (영문 체인지로그) ](https://github.com/kampores/agent_common/blob/main/CHANGELOG_EN.md)
 
+### v0.4.78 (2026-09-21)
+
+- **AI 개발 요청 가이드 및 통합 LLM 사용 설명서 추가**:
+  - README에 만들려는 기능, PyPI·GitHub 링크, 참고 기능 번호를 전달하는 요청 예시와 최소 기능부터 단계적으로 확장하는 방법을 추가했습니다.
+  - `manual/kr/llm/01_unified_llm_client.md`와 영문 매뉴얼을 추가했습니다. 모델 프로필, 외부 API·Fabrix·로컬 GGUF 설정, 환경변수, 반환값·예외 처리 범위를 설명합니다.
+  - Antigravity Stop 훅과 Groq 감독관 AI의 `AGENTS.md` 검사 사례, 검사 범위·생략 조건, `LlmClient` 적용 시 차이를 문서화했습니다.
+  - README의 7번 항목과 매뉴얼 표에 문서를 연결하고, 개발 중인 6번 에러 핸들러 소개를 제외했습니다.
+  - `auto` 모드는 외부 호출이 `None`을 반환할 때만 로컬로 전환한다는 실제 동작에 맞춰 설명을 수정했습니다.
+  - 배포 버전 및 README 명령 예시를 `0.4.78`로 갱신했습니다. 런타임 동작 변경은 없습니다.
+
+### v0.4.77 (2026-09-18)
+- **동적 도구 로더 및 템플릿 평가기(`tool_parser.py`) & 내장 도구(`tool/date/date_time_utils.py`), 공용 유틸리티(`utils.py`) 상세 기술 매뉴얼(한국어/영어 14종) 신설 및 README.md 전면 갱신 (규칙 2.1, 4.2 준수)**:
+  - `manual/kr/tool_parser/` 및 `manual/en/tool_parser/` 신설:
+    - `01_dual_tool_hierarchy_discovery.md`: 4.1. 이원화된 Tool 디렉터리 계층 탐색(1순위: 내장 `agent_common/tool/` vs 2순위: 프로젝트 로컬 `config.transfer.tool_dir_str`), 3단계 함수 탐색 알고리즘, `_tool_cache` 인메모리 캐싱, 기동 초기 `scan_rules_for_tool_functions` 사전 Fail-Fast 검증.
+    - `02_declarative_template_eval.md`: 4.2. 선언적 템플릿 치환 및 표현식 평가(`ToolParser.eval`), 단일 함수 직통 호출, 점(`.`) 네임스페이스 바인딩, 파이프(`|`) 다중 폴백 우선순위, `inspect.signature` 기반 파라미터 매핑 및 `ctx` 컨텍스트 자동 주입.
+    - `03_safe_namespace_navigation.md`: 4.3. 안전한 네임스페이스 탐색(`_SafeNamespace`), 점(`.`) 및 인덱스(`[]`) 접근 통합, 대소문자 무관(Case-insensitive) 탐색, 결측 키에 대한 빈 문자열(`""`) 안전 반환, 중첩 컬렉션 재귀 래핑.
+    - `04_builtin_datetime_utils.md`: 4.4. 내장 공통 일시 도구(`DateTimeUtils`), 비즈니스 테이블 룰(`table_rules.yml`) 및 템플릿 치환식 지원, `TimeUtils` 코어 인프라 위임 및 역할 분담, `YYYYMMDD`, ISO 타임스탬프, 압축 일시(`YYYYMMDDHHMMSS`), 표시용 일시 생성.
+  - `manual/kr/utils/` 및 `manual/en/utils/` 신설:
+    - `01_time_utils_and_timezone_resolution.md`: 5.1. 호스트 시스템 타임존 감지 및 전 세계 표준시 해석(`TimeUtils`), 호스트 OS/컨테이너 타임존 동적 감지(`get_system_timezone`, `get_system_timezone_offset_str`), 30여 개 주요 글로벌 타임존 약어(`WORLD_TIMEZONE_OFFSETS_DICT`) 및 오프셋 해석(`resolve_timezone`), timezone-aware datetime 정규화(`parse_datetime`).
+    - `02_progress_tracker_and_milestones.md`: 5.2. 멀티스레드 실시간 진행률 추적 및 마일스톤 경고(`ProgressTracker`), 배치 대용량 파일/데이터 처리 실시간 추적, 처리 속도(건/s, MB/s) 및 남은 시간(ETA) 동적 계산, 일반 진행 `INFO` vs 10% 배수 마일스톤 및 완료 시 `WARNING` 승격 로깅.
+    - `03_unicode_table_formatter.md`: 5.3. 유니코드 전각 문자 폭 계산 및 마크다운/콘솔 테이블 칼맞춤 포매터(`TableFormatter`), `unicodedata.east_asian_width` 기반 동아시아 전각(2칸) vs 반각(1칸) 정밀 계산, 마크다운 표 헤더/구분선/데이터 행 세로줄 오차 없는 정렬.
+  - `README.md`:
+    - 국문/영문 주요 기능 섹션 4번 및 5번에 4.1 ~ 4.4, 5.1 ~ 5.3 매뉴얼 링크 및 세부 기능 상세 설명 추가.
+    - 국문/영문 상세 기능 매뉴얼 표(User Manuals Table)에 4.1 ~ 4.4, 5.1 ~ 5.3 행 신규 추가.
+    - 패키지 빌드 및 배포 버전 `0.4.77` 최신화.
+  - `agent_common/__init__.py` 및 `pyproject.toml` 버전 `0.4.77` 갱신.
+
 ### v0.4.76 (2026-09-16)
 - **클라우드 스토리지 및 데이터베이스 클라이언트(`clients.py`) 상세 기술 매뉴얼(한국어/영어 10종) 신설 및 README.md 전면 갱신 (규칙 2.1, 4.2 준수)**:
   - `manual/kr/clients/` 및 `manual/en/clients/` 신설:

{agent_common-0.4.76 → agent_common-0.4.78}/CHANGELOG_EN.md

@@ -2,6 +2,33 @@
 
 > [ 🇰🇷 Korean Version (한국어 체인지로그) ](https://github.com/kampores/agent_common/blob/main/CHANGELOG.md)
 
+### v0.4.78 (2026-09-21)
+
+- **AI development request guide and unified LLM manuals**:
+  - Added README prompts combining requirements, PyPI/GitHub links, and feature numbers, with guidance to start small and extend incrementally.
+  - Added Korean and English LLM manuals covering profiles, external APIs, Fabrix, local GGUF, environment overrides, results, and exception behavior.
+  - Documented the Antigravity Stop hook and Groq supervisor example, including review scope, skipped reviews, and differences when using `LlmClient`.
+  - Linked the manuals from README section 7 and the manual tables; omitted the unfinished section 6 error-handler introduction.
+  - Corrected the fallback description: `auto` attempts local inference only after an external `None` result.
+  - Updated release versions and README commands to `0.4.78`. No runtime behavior changes.
+
+### v0.4.77 (2026-09-18)
+- **Comprehensive Technical Manuals for Dynamic Tool Loader (`tool_parser.py`), Built-in Tools (`tool/date/date_time_utils.py`), and Core Utilities (`utils.py`) (14 Documents across Korean and English) and Full README.md Modernization (Rules 2.1, 4.2)**:
+  - Added user manuals under `manual/kr/tool_parser/` and `manual/en/tool_parser/`:
+    - `01_dual_tool_hierarchy_discovery.md`: 4.1. Dual tool hierarchy discovery (Priority 1: built-in `agent_common/tool/` vs Priority 2: project-local `config.transfer.tool_dir_str`), 3-step function introspection, `_tool_cache` in-memory caching, and pre-flight `scan_rules_for_tool_functions` fail-fast validation.
+    - `02_declarative_template_eval.md`: 4.2. Declarative template evaluation (`ToolParser.eval`), direct tool invocations, dot-notation namespace lookups, pipe (`|`) fallback chains, `inspect.signature` argument mapping, and automatic `ctx` context injection.
+    - `03_safe_namespace_navigation.md`: 4.3. Safe namespace traversal (`_SafeNamespace`), unified dot-notation and bracket indexing, case-insensitive key resolution, silent empty-string (`""`) fallback on missing keys, and recursive nested collection wrapping.
+    - `04_builtin_datetime_utils.md`: 4.4. Built-in datetime utility (`DateTimeUtils`), business rule (`table_rules.yml`) and template support, core infrastructure delegation to `TimeUtils`, `YYYYMMDD`, BigQuery ISO timestamps, and compact datetime strings.
+  - Added user manuals under `manual/kr/utils/` and `manual/en/utils/`:
+    - `01_time_utils_and_timezone_resolution.md`: 5.1. Dynamic host OS/container timezone detection (`get_system_timezone`, `get_system_timezone_offset_str`), 30+ global timezone abbreviation parser (`WORLD_TIMEZONE_OFFSETS_DICT`, `resolve_timezone`), and timezone-aware datetime normalization (`parse_datetime`).
+    - `02_progress_tracker_and_milestones.md`: 5.2. Multithreaded progress tracking (`ProgressTracker`), high-volume batch processing telemetry, real-time throughput and ETA calculation, tiered logging (standard `INFO` vs 10% milestone `WARNING` level elevation).
+    - `03_unicode_table_formatter.md`: 5.3. Unicode East Asian width alignment and Markdown table formatter (`TableFormatter`), calculating display widths via `unicodedata.east_asian_width` (Wide 2 columns vs Narrow 1 column) for perfectly aligned Markdown and console tables.
+  - `README.md`:
+    - Integrated manual links and comprehensive descriptions in Korean & English Sections 4 and 5.
+    - Updated user manual index tables with entries 4.1 through 4.4, and 5.1 through 5.3.
+    - Updated release versions and package commands to `0.4.77`.
+  - Bumped version in `agent_common/__init__.py` and `pyproject.toml` to `0.4.77`.
+
 ### v0.4.76 (2026-09-16)
 - **Comprehensive Technical Manuals for Storage & Database Clients (`clients.py`) and Full README.md Modernization (Rules 2.1, 4.2)**:
   - Added 10 user manual documents under `manual/kr/clients/` and `manual/en/clients/`:

{agent_common-0.4.76/src/agent_common.egg-info → agent_common-0.4.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent_common
-Version: 0.4.76
+Version: 0.4.78
 Summary: 자율 에이전트 및 데이터 파이프라인을 위한 경량 설정·로깅·도구 프레임워크 (Lightweight configuration, logging, and tooling framework for autonomous agents and data pipelines)
 Project-URL: Homepage, https://pypi.org/project/agent-common
 Project-URL: Repository, https://github.com/kampores/agent_common
@@ -47,7 +47,7 @@ Dynamic: license-file
 - **1.3. [타입 접미사 자동 형 변환 및 타입 보증 (Type Guarantee & Coercion - v0.4.14 / 범용화 v0.4.32)](https://github.com/kampores/agent_common/blob/main/manual/kr/config_loader/03_type_coercion_and_guarantee.md)**:
   - `_int`: `int` 정수형 자동 형 변환 및 보증
   - `_float`: `float` 실수형 자동 형 변환 및 보증
-  - `_bool`: `bool` 불리언형 자동 변환 (`"true"`, `"false"`, `1`, `0` 등 완벽 대응)
+  - `_bool`: `bool` 불리언형 자동 변환 및 타입 보증 (파이썬 `bool` 또는 대소문자 무관 `"true"`, `"false"` 지원, `0`, `1` 등 비지원 값 유입 시 Fail-Fast 차단)
   - `_str`: `str` 문자열 변환 및 `.strip()` 공백 자동 정제
   - `_list` / `_dict`: 리스트 / 불변 딕셔너리(`ReadOnlyConfig`) 래핑 보증
   - 범용 함수 `coerce_type_by_key_suffix` 및 중첩 딕셔너리 일괄 변환 `coerce_dict_by_key_suffix` 제공으로 임의의 외부 설정 파일(`rule.yml`, `mapping.yml` 등) 및 데이터 파이프라인 완벽 지원
@@ -72,17 +72,20 @@ Dynamic: license-file
 - **3.5. [BigQuery 타임존 오프셋 변환 및 테이블 타임존 모드 검증·동기화 (`convert_to_bigquery_timestamp`)](https://github.com/kampores/agent_common/blob/main/manual/kr/clients/05_bigquery_timestamp_and_tz_sync.md)**: ISO 8601, 공백 구분, 14자리/8자리 숫자 등 다양한 원천 날짜 문자열의 BigQuery 표준 타임스탬프 정규화, 타임존 오프셋 우선순위(`timezone_offset_str` - v0.4.71), 한국 시각 숫자 보존 모드(`kst_as_utc_timestamp_bool`), 테이블 메타데이터(라벨 `timestamp_mode`, 테이블 및 컬럼 Description) 자동 동기화 및 기존 데이터 존재 시 불일치 차단(Fail-Fast)
 
 #### 4. 동적 도구 로더 및 템플릿 평가기 (`agent_common.tool_parser`) & 내장 도구 (`agent_common.tool`)
-- **이원화된 Tool 디렉터리 계층 탐색**:
+- **4.1. [이원화된 Tool 디렉터리 계층 탐색 및 동적 로딩 (`ToolParser.load_tool_function`)](https://github.com/kampores/agent_common/blob/main/manual/kr/tool_parser/01_dual_tool_hierarchy_discovery.md)**:
   - **1순위 (내장 도구)**: `agent_common/tool/` 하위 모듈 (전사 표준 내장 도구)
   - **2순위 (프로젝트 도구)**: `config.yml`의 `transfer.tool_dir_str`에 지정된 로컬 경로 (예: `medallion/tool/`)
-- **선언적 템플릿 치환 및 표현식 평가 (`ToolParser.eval`)**:
+  - 모듈 함수, `클래스.메서드`, 클래스 내부 메서드 3단계 탐색, `_tool_cache` 인메모리 캐싱 및 `scan_rules_for_tool_functions` 사전 검증 지원
+- **4.2. [선언적 템플릿 치환 및 표현식 평가 (`ToolParser.eval`)](https://github.com/kampores/agent_common/blob/main/manual/kr/tool_parser/02_declarative_template_eval.md)**:
   - 변수 네임스페이스 바인딩: `{ecs.key}`, `{sys.today}`, `{json.title}`
   - 동적 도구 함수 호출: `"{code.date_check_to_code(contentInfo.enddate)}"`, `"{path.get_json_name(ecs.key)}"`
-  - 문자열 슬라이싱/메서드: `"{raw_key.lstrip('/')}"`, `"{raw_size|0}"`
-- **안전한 네임스페이스 탐색 (`_SafeNamespace`)**:
-  - 대소문자 무관 탐색 및 누락된 필드에 대해 KeyError 없이 안전하게 빈 문자열(`""`) 반환
-- **내장 공통 도구 (`agent_common.tool.date.DateTimeUtils`)**:
-  - 테이블 규칙 및 템플릿 평가 전용 날짜/시간 도구 (v0.4.69 / v0.4.74)
+  - 파이프(`|`) 우선순위 폴백 및 기본값: `"{meta.title|json.title|'기본제목'}"`
+  - `inspect.signature` 기반 유연한 파라미터 매핑 및 `ctx` 컨텍스트 자동 주입
+- **4.3. [안전한 네임스페이스 탐색 (`_SafeNamespace`)](https://github.com/kampores/agent_common/blob/main/manual/kr/tool_parser/03_safe_namespace_navigation.md)**:
+  - 점(`.`) 및 인덱스(`[]`) 접근 통합, 대소문자 무관(Case-insensitive) 유연한 탐색
+  - 누락된 필드에 대해 KeyError 없이 안전하게 빈 문자열(`""`) 반환 및 중첩 딕셔너리/리스트 재귀적 래핑
+- **4.4. [내장 공통 일시 도구 (`DateTimeUtils`)](https://github.com/kampores/agent_common/blob/main/manual/kr/tool_parser/04_builtin_datetime_utils.md)**:
+  - 테이블 규칙 및 템플릿 평가 전용 날짜/시간 도구, 코어 타임존 해석은 `TimeUtils`에 위임하여 역할 분담 (v0.4.69 / v0.4.74)
   - `parse_datetime(dt_input_any, default_tz_obj)`: 다양한 형식(datetime, ISO 문자열)의 일시를 timezone-aware datetime으로 정규화 변환 (v0.4.74)
   - `get_now_timestamp(tz_obj)`: ISO 8601 표준 타임스탬프(`YYYY-MM-DD HH:MM:SS+09:00` 또는 `+00:00`) 반환 (BigQuery 적재 및 규칙 파일 표준)
   - `get_now_no_tz(tz_obj)`: 타임존 없는 일시 문자열(`YYYY-MM-DD HH:MM:SS`) 반환 (로그 및 요약표 전용)
@@ -90,28 +93,68 @@ Dynamic: license-file
   - `get_today_yyyymmdd(tz_obj)`: `YYYYMMDD` 형식 8자리 일자 반환 (새벽 배치 날짜 역전 방지, 예: `20260824`)
 
 #### 5. 진행률 트래커 및 공용 유틸리티 (`agent_common.utils`)
-- `TimeUtils`: 호스트 시스템(배치 KST vs 파드 UTC) 타임존 동적 자동 감지, 전 세계 주요 표준 타임존(UTC, KST, JST, EST, CET 등) 해석, ISO 8601 오프셋 계산, 일시 객체/문자열을 timezone-aware datetime으로 정규화하는 `parse_datetime` 지원 코어 시간 인프라 유틸리티 (v0.4.69 / v0.4.74)
-- `ProgressTracker`: 멀티스레드 실시간 진행률 추적(`[N/Total] (P%)`), 처리 속도 및 남은 시간 예측, 마일스톤 경고 승격 로깅
-- `TableFormatter`: 유니코드 동아시아 문자 폭(Display Width) 정밀 계산 기반 모노스페이스 콘솔 및 마크다운 테이블 세로줄 자동 맞춤 포매터 (v0.4.63)
-
-#### 6. 공용 에러 및 예외 핸들러 (`agent_common.error_handler`)
-- 네트워크 장애, 설정 오류, 런타임 예외에 대한 일관된 로깅 및 핸들링 제공
+- **5.1. [호스트 시스템 타임존 감지, 전 세계 표준시 해석 및 일시 정규화 (`TimeUtils`)](https://github.com/kampores/agent_common/blob/main/manual/kr/utils/01_time_utils_and_timezone_resolution.md)**: 호스트 시스템(배치 KST vs 파드 UTC) 타임존 동적 자동 감지, 전 세계 30여 개 주요 표준 타임존(UTC, KST, JST, EST, CET 등) 해석, ISO 8601 오프셋 계산, 일시 객체/문자열을 timezone-aware datetime으로 정규화하는 `parse_datetime` 지원 코어 시간 인프라 유틸리티 (v0.4.69 / v0.4.74)
+- **5.2. [멀티스레드 실시간 진행률 추적 및 마일스톤 경고 (`ProgressTracker`)](https://github.com/kampores/agent_common/blob/main/manual/kr/utils/02_progress_tracker_and_milestones.md)**: 멀티스레드 실시간 진행률 추적(`[N/Total] (P%)`), 처리 속도(건/s, MB/s) 및 남은 시간(ETA) 예측, 일반 진행 `INFO` vs 10% 단위 마일스톤 `WARNING` 승격 로깅
+- **5.3. [유니코드 전각 문자 폭 계산 및 마크다운/콘솔 테이블 칼맞춤 포매터 (`TableFormatter`)](https://github.com/kampores/agent_common/blob/main/manual/kr/utils/03_unicode_table_formatter.md)**: 유니코드 동아시아 문자 폭(`unicodedata.east_asian_width`) 정밀 계산 기반 한글/한자(2칸) vs 영문(1칸) 모노스페이스 콘솔 및 마크다운 테이블 세로줄 자동 맞춤 포매터 (v0.4.63)
 
 #### 7. 통합 LLM 클라이언트 및 추론 엔진 (`agent_common.llm`)
+
+상세 사용법과 **Antigravity에서 코딩 AI의 `AGENTS.md` 준수 여부를 검사하는 Groq 감독관 AI 사례**는 [통합 LLM 클라이언트 매뉴얼](https://github.com/kampores/agent_common/blob/main/manual/kr/llm/01_unified_llm_client.md)을 참고하세요.
+
 - **다중 프로바이더 통합 지원 (`LlmClient`)**:
   - **외부 LLM API**: OpenAI 호환 표준 API (`/chat/completions`) 및 Fabrix 전용 API 형식 지원
-  - **로컬 GGUF 모델**: `llama-cpp-python` 기반 로컬 CPU/GPU 가속 추론 및 인메모리 모델 캐싱(`_LOCAL_LLMS`)
+  - **로컬 GGUF 모델**: `llama-cpp-python` 기반 로컬 CPU/GPU 가속 추론 및 모델 경로별 인메모리 캐싱
 - **설정 풀(Pool) 기반 모델 프로필 관리**:
   - `llmpool.yml` 및 `config.yml`을 통해 모델명, 토큰 수(`max_tokens`), 온도(`temperature`), 타임아웃, 컨텍스트 크기(`n_ctx`), 스레드 수(`n_threads`), GPU 레이어(`n_gpu_layers`) 등 동적 구성
-- **자동 장애 복구 (Auto Failover)**:
-  - `provider: auto` 설정 시 외부 LLM API 호출 실패 시 로컬 GGUF 모델로 무중단 자동 전환
-- **추론 예외 통일 관리 (`LlmInferenceError`)**:
-  - API 키 누락, 타임아웃, 모델 로드 실패 등에 대한 통합 예외 처리
+- **조건부 로컬 전환**:
+  - `provider_str: auto` 설정 시 외부 호출이 `None`을 반환하면 같은 프로필의 로컬 설정으로 전환. HTTP·네트워크 예외는 호출자에게 전달
+- **결과 및 예외 처리 (`LlmInferenceError`)**:
+  - 생성 문자열·`None` 반환과 예외를 구분하여 처리. 일부 오류는 원래 예외 형식으로 전달되므로 상세 매뉴얼의 처리 범위 참고
 
 ---
 
 ### 🛠️ 사용 예시 (Usage Examples)
 
+#### AI에게 프로그램 개발을 요청하는 방법
+
+AI에게 **만들려는 기능**, 아래 **PyPI 및 GitHub 링크**, 이 README의 **「주요 제공 기능」에서 참고할 기능 번호**를 함께 전달하면 됩니다. “README의 몇 번, 몇 번 기능과 연결된 상세 매뉴얼을 참고해서 `agent_common`을 활용한 프로그램을 만들어줘”라고 요청하세요.
+
+- PyPI: [agent-common 패키지](https://pypi.org/project/agent-common/)
+- GitHub: [agent_common 저장소 및 README](https://github.com/kampores/agent_common)
+
+예를 들어, **Dell ECS S3 스토리지에서 GCS로 파일을 복사하는 프로그램**을 만들려면 **3.1 (`S3Client`)**, **3.2 (`GcsClient`)** 기능을 지정해 다음과 같이 요청하면 됩니다.
+
+```text
+Dell ECS S3 스토리지에서 Google Cloud Storage(GCS)로 파일을 복사하는 Python 프로그램을 만들어줘.
+
+아래 agent-common 패키지와 GitHub 문서를 참고해줘.
+- https://pypi.org/project/agent-common/
+- https://github.com/kampores/agent_common
+
+주로 README의 「주요 제공 기능」 중 3.1(AWS S3 및 Dell ECS 오브젝트 스토리지 클라이언트)과
+3.2(Google Cloud Storage 스트리밍 클라이언트 및 멀티 계층 인증),
+그리고 각 항목에 연결된 상세 매뉴얼을 참고해서 agent_common을 활용해 구현해줘.
+
+구현 전에 해당 기능의 상세 매뉴얼과 실제 API 사용법을 확인하고,
+요구사항에서 빠진 정보는 임의로 가정하지 말고 질문해줘.
+처음부터 agent_common의 모든 기능을 적용하려고 하지 말고,
+먼저 파일 복사에 필요한 최소 기능을 구현하고 동작을 확인해줘.
+그다음 필요한 부가기능을 변수형 보증(1.3), config 점 표기법(1.2) 등으로
+나누어 하나씩 추가하고, 추가할 때마다 기존 파일 복사가 정상 동작하는지 확인해줘.
+```
+
+다른 프로그램도 같은 방식으로 만들려는 기능에 해당하는 번호를 골라 요청하면 됩니다. 복사 대상 버킷, 대상 파일 범위, 저장 경로 규칙 등 구체적인 요구사항을 함께 설명하면 원하는 동작을 더 명확하게 전달할 수 있습니다.
+
+##### 최소 기능부터 단계적으로 확장하기
+
+처음부터 `agent_common`의 모든 기능을 한꺼번에 적용하도록 요청하지 말고, **핵심 기능 구현 → 동작 확인 → 필요한 부가기능 추가** 순서로 진행하세요. 패키지가 이미 제공하는 기능은 재사용하고, 현재 목적에 필요한 기능부터 적용하면 됩니다.
+
+1. **최소 기능 구현**: ECS S3 → GCS 복사 프로그램이라면 접속·인증과 지정한 파일의 복사에 필요한 기능부터 구현합니다.
+2. **핵심 동작 확인**: 지정한 파일이 원하는 GCS 경로에 정상적으로 복사되는지 확인합니다.
+3. **부가기능 단계적 추가**: 필요에 따라 변수형 보증(1.3), `config` 점 표기법(1.2), 진행률 추적(5.2), 결과 요약(2.5) 등을 하나씩 적용하고 기존 동작을 확인합니다.
+
+후속 요청도 “현재 파일 복사 동작을 유지하면서 README 1.3의 변수형 보증을 적용해줘”처럼 범위를 좁혀 전달하면 됩니다.
+
 #### 1. 전역 `config` 점 표기법 및 타입 보증 활용
 ```python
 from agent_common.config_loader import config
@@ -175,7 +218,7 @@ from agent_common.llm import LlmClient
 # 1) 설정 풀에 정의된 모델명 또는 용도로 클라이언트 초기화
 llm_client = LlmClient(purpose_str="sql_generator")
 
-# 2) 프롬프트 기반 텍스트 생성 (외부 API -> 로컬 GGUF 자동 폴백)
+# 2) 선택한 프로필의 provider_str에 따라 텍스트 생성
 prompt_str = "사용자 요청: 2026년 8월 일일 가입자 수 통계 쿼리를 작성해줘."
 response_str = llm_client.generate(
     prompt_str=prompt_str,
@@ -284,7 +327,7 @@ pip install -e agent_common
 pip install -e "agent_common[clients]"
 
 # 배포 환경 (Wheel 패키지 설치)
-pip install dist/agent_common-0.4.76-py3-none-any.whl
+pip install dist/agent_common-0.4.78-py3-none-any.whl
 ```
 
 #### 🌐 PyPI 공식 배포 (관리자 전용)
@@ -300,7 +343,7 @@ python -m build
 python -m twine check dist/*
 
 # 4. PyPI 업로드
-python -m twine upload dist/agent_common-0.4.76*
+python -m twine upload dist/agent_common-0.4.78*
 ```
 
 ---
@@ -327,11 +370,27 @@ python -m twine upload dist/agent_common-0.4.76*
 | **3.3** | **BigQuery 배치 적재 & 스트리밍 인서트** | [03_bigquery_batch_and_streaming_load.md](https://github.com/kampores/agent_common/blob/main/manual/kr/clients/03_bigquery_batch_and_streaming_load.md) | JSON 배치 로드 Job vs 스트리밍 API, 중첩 에러 상세 분해, 중복 방지 키 집합 조회 |
 | **3.4** | **BigQuery 인라인 MERGE (Upsert) 엔진** | [04_bigquery_inline_merge_upsert.md](https://github.com/kampores/agent_common/blob/main/manual/kr/clients/04_bigquery_inline_merge_upsert.md) | 임시 테이블 없는 인라인 MERGE, UNNEST 파라미터 바인딩, 동적 타입 캐스팅, 100건 청크 분할 |
 | **3.5** | **BigQuery 타임존 변환 & 모드 검증·동기화** | [05_bigquery_timestamp_and_tz_sync.md](https://github.com/kampores/agent_common/blob/main/manual/kr/clients/05_bigquery_timestamp_and_tz_sync.md) | ISO/압축 일시 정규화, Standard-UTC vs KST-as-UTC 모드, 테이블 메타데이터 동기화 및 Fail-Fast |
+| **4.1** | **이원화된 Tool 디렉터리 계층 탐색 & 동적 로딩** | [01_dual_tool_hierarchy_discovery.md](https://github.com/kampores/agent_common/blob/main/manual/kr/tool_parser/01_dual_tool_hierarchy_discovery.md) | 내장(1순위) vs 로컬(2순위) 탐색 계층, 3단계 함수 탐색, `_tool_cache`, `scan_rules_for_tool_functions` 사전 검증 |
+| **4.2** | **선언적 템플릿 치환 & 표현식 평가** | [02_declarative_template_eval.md](https://github.com/kampores/agent_common/blob/main/manual/kr/tool_parser/02_declarative_template_eval.md) | `ToolParser.eval()`, 도구 함수 직통 호출, 점(.) 네임스페이스 바인딩, 파이프(`\|`) 폴백, 자동 `ctx` 컨텍스트 주입 |
+| **4.3** | **안전한 네임스페이스 탐색 (`_SafeNamespace`)** | [03_safe_namespace_navigation.md](https://github.com/kampores/agent_common/blob/main/manual/kr/tool_parser/03_safe_namespace_navigation.md) | 점(.)/인덱스 통합 접근, 대소문자 무관 탐색, 누락 필드 `""` 반환, 중첩 딕셔너리/리스트 안전 재귀 래핑 |
+| **4.4** | **내장 공통 일시 도구 (`DateTimeUtils`)** | [04_builtin_datetime_utils.md](https://github.com/kampores/agent_common/blob/main/manual/kr/tool_parser/04_builtin_datetime_utils.md) | 테이블 룰/템플릿 전용 날짜 도구, `TimeUtils` 코어 위임 역할 분담, `YYYYMMDD`, ISO 타임스탬프, 압축 일시 생성 |
+| **5.1** | **호스트 타임존 감지 & 세계 표준시 해석** | [01_time_utils_and_timezone_resolution.md](https://github.com/kampores/agent_common/blob/main/manual/kr/utils/01_time_utils_and_timezone_resolution.md) | `TimeUtils`, OS/컨테이너 타임존 감지, 전 세계 30여 개 표준시 해석, timezone-aware 일시 정규화 |
+| **5.2** | **멀티스레드 실시간 진행률 추적 & 마일스톤** | [02_progress_tracker_and_milestones.md](https://github.com/kampores/agent_common/blob/main/manual/kr/utils/02_progress_tracker_and_milestones.md) | `ProgressTracker`, 실시간 진행률(`%`), 처리 속도, ETA 계산, 일반 `INFO` vs 10% 단위 마일스톤 `WARNING` 승격 로깅 |
+| **5.3** | **유니코드 전각 폭 계산 & 마크다운 표 칼맞춤** | [03_unicode_table_formatter.md](https://github.com/kampores/agent_common/blob/main/manual/kr/utils/03_unicode_table_formatter.md) | `TableFormatter`, 동아시아 문자 폭(`east_asian_width`) 정밀 계산, 한글(2칸) vs 영문(1칸) 마크다운 표 세로선 칼정렬 |
+| **7** | **통합 LLM 클라이언트 및 추론 엔진** | [01_unified_llm_client.md](https://github.com/kampores/agent_common/blob/main/manual/kr/llm/01_unified_llm_client.md) | 모델 프로필, 외부 API·로컬 GGUF, 조건부 전환, Groq 감독관 AI와 Stop 훅 활용 사례 |
 
 ---
 
 ### 📋 버전 변경 이력 (Changelog)
 
+#### v0.4.78 (2026-09-21)
+
+- AI에게 요구사항·패키지 링크·기능 번호를 전달하는 방법과 최소 기능부터 단계적으로 확장하는 가이드를 추가했습니다.
+- 통합 LLM 클라이언트의 한국어·영어 매뉴얼을 추가하고, 모델 설정·외부 API·로컬 GGUF·환경변수·예외 처리를 설명했습니다.
+- Groq 감독관 AI와 Antigravity Stop 훅의 `AGENTS.md` 검사 사례 및 실제 검사 범위·생략 조건을 정리했습니다.
+- LLM `auto` 모드의 조건부 전환 설명을 실제 구현에 맞추고, 개발 중인 에러 핸들러 소개는 제외했습니다.
+- 패키지 버전을 `0.4.78`로 올렸습니다. 런타임 동작 변경은 없습니다.
+
 자세한 버전 변경 이력은 [GitHub CHANGELOG.md](https://github.com/kampores/agent_common/blob/main/CHANGELOG.md) 파일을 참고하세요.
 
 ---
@@ -350,7 +409,7 @@ A comprehensive Python common library providing unified logging, hierarchical co
 - **1.3. [Type Guarantee & Automatic Coercion via Type Suffixes (v0.4.14 / Generalized v0.4.32)](https://github.com/kampores/agent_common/blob/main/manual/en/config_loader/03_type_coercion_and_guarantee.md)**:
   - `_int`: Automatic integer conversion and type guarantee.
   - `_float`: Automatic floating-point conversion and type guarantee.
-  - `_bool`: Automatic boolean conversion (`"true"`, `"false"`, `1`, `0`, etc.).
+  - `_bool`: Strict boolean conversion and type guarantee (Python `bool` or case-insensitive `"true"`, `"false"`; unsupported values like `0`, `1` fail fast).
   - `_str`: Automatic string conversion and `.strip()` whitespace trimming.
   - `_list` / `_dict`: Guaranteed list / immutable dictionary (`ReadOnlyConfig`) wrapping.
   - Standalone functions `coerce_type_by_key_suffix` and recursive batch coercion `coerce_dict_by_key_suffix` for arbitrary external configuration files (`rule.yml`, `mapping.yml`) and data mappings.
@@ -374,36 +433,41 @@ A comprehensive Python common library providing unified logging, hierarchical co
 - **3.5. [BigQuery Timestamp Conversion & Timezone Mode Synchronization (`convert_to_bigquery_timestamp`)](https://github.com/kampores/agent_common/blob/main/manual/en/clients/05_bigquery_timestamp_and_tz_sync.md)**: Normalizes ISO 8601, whitespace, and 14-digit/8-digit timestamps to standard BigQuery formats, timezone offset precedence (`timezone_offset_str` - v0.4.71), display convenience mode (`kst_as_utc_timestamp_bool`), automated table metadata synchronization (labels, table/column descriptions) with fail-fast mismatch blocking.
 
 #### 4. Dynamic Tool Loader & Template Evaluator (`agent_common.tool_parser`) & Built-in Tools (`agent_common.tool`)
-- **Dual Tool Hierarchy Discovery**:
+- **4.1. [Dual Tool Hierarchy Discovery & Dynamic Loading (`ToolParser.load_tool_function`)](https://github.com/kampores/agent_common/blob/main/manual/en/tool_parser/01_dual_tool_hierarchy_discovery.md)**:
   - **Priority 1 (Built-in Tools)**: Modules under `agent_common/tool/` (standard enterprise tools).
   - **Priority 2 (Project Tools)**: Local path configured in `config.yml` under `transfer.tool_dir_str` (e.g., `medallion/tool/`).
-- **Declarative Template Replacement & Expression Evaluation (`ToolParser.eval`)**:
-  - Variable namespace binding: `{ecs.key}`, `{sys.today}`, `{json.title}`
-  - Dynamic tool function invocation: `"{code.date_check_to_code(contentInfo.enddate)}"`, `"{path.get_json_name(ecs.key)}"`
-  - String slicing & fallback methods: `"{raw_key.lstrip('/')}"`, `"{raw_size|0}"`
-- **Safe Namespace Lookup (`_SafeNamespace`)**:
-  - Case-insensitive lookups returning empty strings (`""`) without raising `KeyError` on missing keys.
-- **Built-in Common Utilities (`agent_common.tool.date.DateTimeUtils`)**:
+  - 3-step function introspection, `_tool_cache` in-memory caching, and `scan_rules_for_tool_functions` pre-flight validation.
+- **4.2. [Declarative Template Evaluation & Expression Resolution (`ToolParser.eval`)](https://github.com/kampores/agent_common/blob/main/manual/en/tool_parser/02_declarative_template_eval.md)**:
+  - Variable namespace binding: `{ecs.key}`, `{sys.today}`, `{json.title}`.
+  - Dynamic tool function invocation: `"{code.date_check_to_code(contentInfo.enddate)}"`, `"{path.get_json_name(ecs.key)}"`.
+  - Pipe (`|`) fallback chains and default values: `"{meta.title|json.title|'Default Title'}"`.
+  - `inspect.signature`-based parameter mapping and automatic `ctx` context injection.
+- **4.3. [Safe Namespace Lookup & Case-Insensitive Access (`_SafeNamespace`)](https://github.com/kampores/agent_common/blob/main/manual/en/tool_parser/03_safe_namespace_navigation.md)**:
+  - Unified dot-notation and bracket indexing, resilient case-insensitive key resolution.
+  - Returns empty string (`""`) on missing keys without raising `KeyError`; recursive wrapping of nested dictionaries and lists.
+- **4.4. [Built-in DateTime Tool (`DateTimeUtils`)](https://github.com/kampores/agent_common/blob/main/manual/en/tool_parser/04_builtin_datetime_utils.md)**:
+  - Business rule and template formatting tool delegating core timezone calculations to `TimeUtils` (v0.4.69 / v0.4.74).
+  - `parse_datetime(dt_input_any, default_tz_obj)`: Normalizes various datetime formats and ISO strings into timezone-aware datetimes (v0.4.74).
   - `get_now_timestamp(tz_obj)`: Returns standard ISO 8601 timestamp string (`YYYY-MM-DD HH:MM:SS+09:00` or `+00:00`).
-  - `get_now_no_tz(tz_obj)`: Returns datetime string without timezone (`YYYY-MM-DD HH:MM:SS`).
-  - `get_now_compact(tz_obj)`: Returns 14-digit timestamp string (e.g., `20260824110500`).
-  - `get_today_yyyymmdd(tz_obj)`: Returns 8-digit date string (e.g., `20260824`).
+  - `get_now_no_tz(tz_obj)`: Returns clean datetime string without timezone (`YYYY-MM-DD HH:MM:SS`).
+  - `get_now_compact(tz_obj)`: Returns 14-digit compact timestamp string (`YYYYMMDDHHMMSS`).
+  - `get_today_yyyymmdd(tz_obj)`: Returns 8-digit date string (`YYYYMMDD`), preventing overnight batch date rollback.
 
 #### 5. Progress Tracker & Common Utilities (`agent_common.utils`)
-- `TimeUtils`: Dynamic host OS system timezone detection, world timezone parsing, and ISO 8601 offset calculation core utility (v0.4.69).
-- `ProgressTracker`: Real-time multithreaded progress tracking (`[N/Total] (P%)`), throughput/ETA calculation, and milestone log level elevation.
-- `TableFormatter`: Precision terminal and markdown table column width alignment utility (v0.4.63).
-
-#### 6. Common Error & Exception Handler (`agent_common.error_handler`)
-- Consistent exception logging and handling for network failures, configuration errors, and runtime exceptions.
+- **5.1. [System Timezone Detection, Global Timezone Resolution & Datetime Normalization (`TimeUtils`)](https://github.com/kampores/agent_common/blob/main/manual/en/utils/01_time_utils_and_timezone_resolution.md)**: Dynamic host OS system timezone detection, 30+ world timezone parsing, ISO 8601 offset calculation, and `parse_datetime` normalization core utility (v0.4.69 / v0.4.74).
+- **5.2. [Multithreaded Progress Tracking & Milestone Telemetry (`ProgressTracker`)](https://github.com/kampores/agent_common/blob/main/manual/en/utils/02_progress_tracker_and_milestones.md)**: Real-time multithreaded progress tracking (`[N/Total] (P%)`), throughput/ETA calculation, and tiered logging (standard `INFO` vs 10% milestone `WARNING` level elevation).
+- **5.3. [Unicode East Asian Width Alignment & Table Formatter (`TableFormatter`)](https://github.com/kampores/agent_common/blob/main/manual/en/utils/03_unicode_table_formatter.md)**: Precision terminal and Markdown table column width alignment utility calculating Unicode East Asian character display widths (`unicodedata.east_asian_width`) (v0.4.63).
 
 #### 7. Unified LLM Client & Inference Engine (`agent_common.llm`)
+
+See the [Unified LLM Client Manual](https://github.com/kampores/agent_common/blob/main/manual/en/llm/01_unified_llm_client.md) for configuration, API usage, and a **Groq supervisor that reviews an Antigravity coding AI's changes against `AGENTS.md`**.
+
 - **Multi-Provider Support (`LlmClient`)**:
   - **External LLM APIs**: Standard OpenAI-compatible API (`/chat/completions`) and Fabrix API format.
-  - **Local GGUF Models**: Local CPU/GPU accelerated inference via `llama-cpp-python` with in-memory caching (`_LOCAL_LLMS`).
+  - **Local GGUF Models**: Local CPU/GPU accelerated inference via `llama-cpp-python` with model-path-based in-memory caching.
 - **Pool-based Model Profile Management**: Dynamic configuration via `llmpool.yml` and `config.yml`.
-- **Auto Failover**: Seamless automatic fallback to local GGUF models if external API calls fail (`provider: auto`).
-- **Unified Inference Error Handling (`LlmInferenceError`)**: Centralized exception handling for API key errors, timeouts, and model load failures.
+- **Conditional Local Fallback**: With `provider_str: auto`, an external `None` result triggers local inference using the same profile. HTTP/network exceptions propagate to the caller.
+- **Results and Exceptions (`LlmInferenceError`)**: Distinguish text, `None`, and exceptions. Some errors retain their original exception types; see the manual for details.
 
 ---
 
@@ -472,7 +536,7 @@ from agent_common.llm import LlmClient
 # 1) Initialize client with configured purpose or model name
 llm_client = LlmClient(purpose_str="sql_generator")
 
-# 2) Prompt-based generation (External API with auto fallback to local GGUF)
+# 2) Generate text using the selected profile's provider_str
 prompt_str = "User request: Generate daily subscriber statistics SQL for August 2026."
 response_str = llm_client.generate(
     prompt_str=prompt_str,
@@ -578,7 +642,7 @@ pip install -e agent_common
 pip install -e "agent_common[clients]"
 
 # Production (Wheel package)
-pip install dist/agent_common-0.4.76-py3-none-any.whl
+pip install dist/agent_common-0.4.78-py3-none-any.whl
 ```
 
 #### 🌐 Official PyPI Distribution (Maintainers Only)
@@ -594,7 +658,7 @@ python -m build
 python -m twine check dist/*
 
 # 4. Upload to PyPI
-python -m twine upload dist/agent_common-0.4.76*
+python -m twine upload dist/agent_common-0.4.78*
 ```
 
 ---
@@ -621,9 +685,25 @@ For comprehensive architecture details and practical code examples for each modu
 | **3.3** | **BigQuery Batch Loading & Streaming Ingestion** | [03_bigquery_batch_and_streaming_load.md](https://github.com/kampores/agent_common/blob/main/manual/en/clients/03_bigquery_batch_and_streaming_load.md) | JSON batch load jobs vs streaming API, nested error diagnostics unpacking, deduplication key lookup |
 | **3.4** | **BigQuery Inline MERGE (Upsert) Engine** | [04_bigquery_inline_merge_upsert.md](https://github.com/kampores/agent_common/blob/main/manual/en/clients/04_bigquery_inline_merge_upsert.md) | Pure inline MERGE without staging tables, UNNEST parameter binding, dynamic type casting, 100-row chunks |
 | **3.5** | **BigQuery Timestamp Conversion & TZ Sync** | [05_bigquery_timestamp_and_tz_sync.md](https://github.com/kampores/agent_common/blob/main/manual/en/clients/05_bigquery_timestamp_and_tz_sync.md) | ISO/compact timestamp normalization, Standard-UTC vs KST-as-UTC modes, table metadata auto-sync & Fail-Fast |
+| **4.1** | **Dual Tool Hierarchy Discovery & Dynamic Loading** | [01_dual_tool_hierarchy_discovery.md](https://github.com/kampores/agent_common/blob/main/manual/en/tool_parser/01_dual_tool_hierarchy_discovery.md) | Built-in (Priority 1) vs Local (Priority 2) discovery, 3-step function introspection, `_tool_cache`, `scan_rules_for_tool_functions` pre-flight validation |
+| **4.2** | **Declarative Template Evaluation & Expression Resolution** | [02_declarative_template_eval.md](https://github.com/kampores/agent_common/blob/main/manual/en/tool_parser/02_declarative_template_eval.md) | `ToolParser.eval()`, direct tool calls, dot-notation namespaces, pipe (`\|`) fallbacks, signature-aware parameter binding, and automatic context injection |
+| **4.3** | **Safe Namespace Lookup & Case-Insensitive Access** | [03_safe_namespace_navigation.md](https://github.com/kampores/agent_common/blob/main/manual/en/tool_parser/03_safe_namespace_navigation.md) | `_SafeNamespace`, case-insensitive lookups, silent empty-string (`""`) fallback on missing keys, recursive nested collection wrapping |
+| **4.4** | **Built-in DateTime Tool (`DateTimeUtils`)** | [04_builtin_datetime_utils.md](https://github.com/kampores/agent_common/blob/main/manual/en/tool_parser/04_builtin_datetime_utils.md) | Business template formatting tool, `TimeUtils` delegation architecture, `YYYYMMDD`, BigQuery ISO timestamps, and compact datetime strings |
+| **5.1** | **System Timezone Detection & Global Timezone Resolution** | [01_time_utils_and_timezone_resolution.md](https://github.com/kampores/agent_common/blob/main/manual/en/utils/01_time_utils_and_timezone_resolution.md) | `TimeUtils`, dynamic host OS/container timezone detection, 30+ global timezone abbreviation parser, timezone-aware datetime normalization |
+| **5.2** | **Multithreaded Progress Tracking & Milestone Telemetry** | [02_progress_tracker_and_milestones.md](https://github.com/kampores/agent_common/blob/main/manual/en/utils/02_progress_tracker_and_milestones.md) | `ProgressTracker`, real-time percentage (`%`), throughput, ETA, standard `INFO` vs 10% milestone `WARNING` level elevation |
+| **5.3** | **Unicode East Asian Width Alignment & Table Formatter** | [03_unicode_table_formatter.md](https://github.com/kampores/agent_common/blob/main/manual/en/utils/03_unicode_table_formatter.md) | `TableFormatter`, precise East Asian character display width calculation, monospace and Markdown table vertical border alignment |
+| **7** | **Unified LLM Client and Inference Engine** | [01_unified_llm_client.md](https://github.com/kampores/agent_common/blob/main/manual/en/llm/01_unified_llm_client.md) | Model profiles, external APIs, local GGUF, conditional fallback, Groq supervisor and Stop hook example |
 
 ---
 
 ### 📋 Version History (Changelog)
 
+#### v0.4.78 (2026-09-21)
+
+- Added AI request examples using requirements, package links, and feature numbers, with incremental implementation guidance.
+- Added Korean/English LLM manuals covering configuration, external APIs, local GGUF, environment overrides, and failure handling.
+- Documented the Groq supervisor and Antigravity Stop hook example, including review scope and skipped-review conditions.
+- Corrected conditional fallback documentation and omitted the unfinished error-handler introduction.
+- Bumped the package version to `0.4.78` with no runtime behavior changes.
+
 For detailed version history, please refer to [GitHub CHANGELOG_EN.md](https://github.com/kampores/agent_common/blob/main/CHANGELOG_EN.md).