폴더 안의 대상 파일(pdf/docx/pptx/svg/png) 목록과 확장자별 개수를 조회합니다.

문서 내용을 읽지 않고 메타데이터(경로/크기/수정일)만 가볍게 훑어보는 도구입니다. 폴더 안에 어떤 파일이 몇 개 있는지 빠르게 확인하고 싶을 때 사용하세요.

Returns: ScanFolderResponse: files[]에 경로/이름/확장자/크기/수정일이 담깁니다. 파일이 max_files보다 많으면 list_truncated=True이고, by_extension의 개수는 상한과 무관하게 항상 전체 매칭 파일 기준입니다.

Examples: - 사용: "이 폴더에 어떤 문서들이 있어?", "pdf 몇 개야?" - 사용하지 않음: 파일 내용까지 요약하고 싶을 때 → analyze_folder - 사용하지 않음: 하위 폴더 구조/통계까지 보고 싶을 때 → analyze_folder_structure

폴더의 하위 디렉터리 트리와 확장자별 통계, 용량, 최대 파일을 분석합니다.

scan_folder보다 한 단계 더 깊은 "구조" 파악용 도구입니다. 폴더가 어떻게 구성돼 있는지(하위 폴더별 파일 분포, 가장 큰 파일 등)를 먼저 감 잡고 싶을 때 사용하세요.

Returns: FolderStructureResponse: tree는 {"하위폴더명": {...}, "_files": [...]} 형태의 중첩 딕셔너리입니다. 파일이 max_files보다 많으면 tree에는 앞쪽 max_files개만 반영되고 list_truncated=True가 되지만, total_files/ by_extension/total_size_bytes 등 통계는 항상 전체 파일 기준입니다.

Examples: - 사용: "이 폴더 구조 좀 분석해줘", "가장 큰 파일이 뭐야?" - 사용하지 않음: 파일 목록만 빠르게 보고 싶을 때 → scan_folder

문서 파일(pdf/docx/pptx/svg) 하나의 텍스트를 추출합니다. 요약은 하지 않습니다.

scan_folder/analyze_folder에서 찾은 파일 중 하나를 더 자세히 보고 싶을 때, 또는 analyze_folder의 일괄 요약이 잘렸을 때(truncated=True) 이어서 읽을 때 씁니다.

Returns: ReadDocumentResponse: text에 원문(잘렸으면 앞부분)이 담깁니다. truncated=True면 max_chars를 늘려 다시 호출해 나머지를 볼 수 있습니다.

Examples: - 사용: "이 pdf 파일 내용 좀 자세히 보여줘" - 사용하지 않음: png 이미지 → read_image_text - 사용하지 않음: 폴더 전체를 한 번에 훑고 싶을 때 → analyze_folder

PNG 이미지 하나를 OCR로 읽어 텍스트를 추출합니다(Tesseract-OCR 필요).

스크린샷, 스캔한 메모, 다이어그램에 박힌 라벨처럼 이미지 안의 문자를 읽어야 할 때 사용하세요. 순수 그림/사진처럼 텍스트가 없는 이미지는 빈 결과가 나올 수 있습니다(비전 해석이 아니라 OCR이므로 그림 자체의 의미는 파악하지 못합니다).

Returns: ReadImageTextResponse: text에 인식된 문자열이 담깁니다. 결과가 비어 있으면 next_actions에서 그 이유를 안내합니다.

Examples: - 사용: "이 스크린샷에 뭐라고 적혀 있어?" - 사용하지 않음: pdf/docx/pptx/svg 문서 → read_document

폴더 안의 모든 대상 파일(pdf/docx/pptx/svg/png)을 한 번에 추출해 리포트로 반환합니다.

파일마다 read_document/read_image_text를 따로 호출하지 않아도 되는 배치 도구입니다. 한 파일이 실패해도 나머지 파일 처리는 계속되며, 실패 이유는 파일별로 남습니다. 파일 수가 max_files를 넘으면 앞쪽부터 max_files개만 처리하고, 넘겨받지 못한 개수는 skipped_due_to_limit로 투명하게 알려줍니다(조용히 누락되지 않습니다).

Returns: AnalyzeFolderResponse: reports[]의 각 항목은 status(OK/ERROR)와 함께 text 또는 error를 담습니다. status가 PARTIAL이면 일부 실패했거나(failed>0) 상한 때문에 스킵된 파일(skipped_due_to_limit>0)이 있다는 뜻입니다.

Examples: - 사용: "이 폴더 문서들 다 요약해줘", "폴더 구조 분석하고 내용도 정리해줘" - 사용하지 않음: 파일 목록만 필요할 때 → scan_folder - 사용하지 않음: 특정 파일 하나만 자세히 → read_document / read_image_text