smart-docgen 0.2.2__tar.gz → 0.2.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (138) hide show
  1. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/CHANGELOG.md +7 -0
  2. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/PKG-INFO +24 -6
  3. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/README.md +23 -5
  4. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/__init__.py +27 -11
  5. smart_docgen-0.2.3/docpilot/exceptions.py +63 -0
  6. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/mapping/claude.py +3 -1
  7. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/mapping/gemini.py +3 -1
  8. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/mapping/openai.py +3 -1
  9. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/mapping/openai_compat.py +56 -4
  10. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/mapping/rag.py +21 -2
  11. smart_docgen-0.2.3/docpilot/tokens.py +11 -0
  12. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/smart_docgen.egg-info/PKG-INFO +24 -6
  13. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/smart_docgen.egg-info/SOURCES.txt +1 -0
  14. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/smart_docgen.egg-info/scm_file_list.json +102 -101
  15. smart_docgen-0.2.3/smart_docgen.egg-info/scm_version.json +8 -0
  16. smart_docgen-0.2.2/docpilot/exceptions.py +0 -34
  17. smart_docgen-0.2.2/smart_docgen.egg-info/scm_version.json +0 -8
  18. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/.claude/skills/docpilot-tools/SKILL.md +0 -0
  19. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/.claude/skills/docpilot-tools/docpilot_cli.py +0 -0
  20. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/.env.example +0 -0
  21. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/.github/workflows/publish.yml +0 -0
  22. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/.gitignore +0 -0
  23. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/LICENSE +0 -0
  24. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/__init__.py +0 -0
  25. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/base.py +0 -0
  26. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/docx_analyzer.py +0 -0
  27. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/docx_builder.py +0 -0
  28. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/html_blocks.py +0 -0
  29. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/html_table.py +0 -0
  30. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/hwp_convert.py +0 -0
  31. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/hwpx_analyzer.py +0 -0
  32. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/hwpx_auto_builder.py +0 -0
  33. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/hwpx_builder.py +0 -0
  34. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/hwpx_bullets.py +0 -0
  35. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/hwpx_dynamic_builder.py +0 -0
  36. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/hwpx_section_generator.py +0 -0
  37. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/hwpx_style_extractor.py +0 -0
  38. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/builder/pdf_builder.py +0 -0
  39. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/db/__init__.py +0 -0
  40. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/db/client.py +0 -0
  41. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/db/indexer.py +0 -0
  42. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/db/schema.py +0 -0
  43. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/db/template_store.py +0 -0
  44. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/ingestion/__init__.py +0 -0
  45. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/ingestion/docx.py +0 -0
  46. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/ingestion/hwp.py +0 -0
  47. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/ingestion/hwpx.py +0 -0
  48. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/ingestion/models.py +0 -0
  49. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/ingestion/pdf.py +0 -0
  50. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/ingestion/text.py +0 -0
  51. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/mapping/__init__.py +0 -0
  52. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/mapping/base.py +0 -0
  53. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/mapping/benchmark.py +0 -0
  54. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/mapping/sidecar.py +0 -0
  55. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/mcp_server.py +0 -0
  56. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/search/__init__.py +0 -0
  57. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/search/_filter.py +0 -0
  58. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/search/alias.py +0 -0
  59. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/search/embedding.py +0 -0
  60. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/search/eval.py +0 -0
  61. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/search/exact.py +0 -0
  62. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/search/highlight.py +0 -0
  63. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/search/hybrid.py +0 -0
  64. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/search/models.py +0 -0
  65. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/search/morpheme.py +0 -0
  66. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/search/reranker.py +0 -0
  67. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/template_generator/__init__.py +0 -0
  68. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/template_generator/analyzer.py +0 -0
  69. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/template_generator/docx_extractor.py +0 -0
  70. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/template_generator/extractor.py +0 -0
  71. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/template_generator/generator.py +0 -0
  72. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/base/Contents/content.hpf +0 -0
  73. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/base/Contents/header.xml +0 -0
  74. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/base/Contents/section0.xml +0 -0
  75. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/base/META-INF/container.rdf +0 -0
  76. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/base/META-INF/container.xml +0 -0
  77. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/base/META-INF/manifest.xml +0 -0
  78. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/base/Preview/PrvImage.png +0 -0
  79. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/base/Preview/PrvText.txt +0 -0
  80. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/base/mimetype +0 -0
  81. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/base/settings.xml +0 -0
  82. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/base/version.xml +0 -0
  83. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/gonmun/header.xml +0 -0
  84. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/gonmun/section0.xml +0 -0
  85. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/gonmun/sidecar.json +0 -0
  86. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/minutes/header.xml +0 -0
  87. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/minutes/section0.xml +0 -0
  88. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/minutes/sidecar.json +0 -0
  89. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/proposal/header.xml +0 -0
  90. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/proposal/section0.xml +0 -0
  91. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/proposal/sidecar.json +0 -0
  92. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/report/header.xml +0 -0
  93. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/report/section0.xml +0 -0
  94. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/docpilot/templates/report/sidecar.json +0 -0
  95. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/example/run.py +0 -0
  96. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/pyproject.toml +0 -0
  97. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/scripts/chunk_size_compare.py +0 -0
  98. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/scripts/gen_/355/225/231/355/232/214/353/263/264/352/263/240/354/204/234.py" +0 -0
  99. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/scripts/gen_/355/225/231/355/232/214/353/263/264/352/263/240/354/204/234_hwpx_from_docx.py" +0 -0
  100. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/scripts/inspect_index.py +0 -0
  101. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/scripts/make_ebs_template.py +0 -0
  102. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/scripts/test_docgen.py +0 -0
  103. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/scripts/test_folder_search.py +0 -0
  104. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/scripts/test_hwpx_to_docx.py +0 -0
  105. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/scripts/test_mapping.py +0 -0
  106. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/scripts/test_ollama_truncation.py +0 -0
  107. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/scripts/test_quality.py +0 -0
  108. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/scripts/test_real.py +0 -0
  109. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/scripts/verify_html_render.py +0 -0
  110. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/setup.cfg +0 -0
  111. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/smart_docgen.egg-info/dependency_links.txt +0 -0
  112. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/smart_docgen.egg-info/entry_points.txt +0 -0
  113. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/smart_docgen.egg-info/requires.txt +0 -0
  114. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/smart_docgen.egg-info/top_level.txt +0 -0
  115. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/__init__.py +0 -0
  116. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/conftest.py +0 -0
  117. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/mocks/__init__.py +0 -0
  118. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/mocks/db_mock.py +0 -0
  119. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/mocks/llm_mock.py +0 -0
  120. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_alias.py +0 -0
  121. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_analyzers.py +0 -0
  122. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_builder.py +0 -0
  123. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_collection.py +0 -0
  124. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_embed_batch_bench.py +0 -0
  125. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_embed_model_bench.py +0 -0
  126. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_embed_quality_bench.py +0 -0
  127. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_embedding.py +0 -0
  128. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_generate_from_content.py +0 -0
  129. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_hwp_ingestion.py +0 -0
  130. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_index_perf.py +0 -0
  131. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_indexer.py +0 -0
  132. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_ingestion.py +0 -0
  133. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_mapping.py +0 -0
  134. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_mcp_server.py +0 -0
  135. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_search.py +0 -0
  136. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_search_quality.py +0 -0
  137. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/tests/test_template_generator.py +0 -0
  138. {smart_docgen-0.2.2 → smart_docgen-0.2.3}/uv.lock +0 -0
@@ -5,6 +5,13 @@
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [0.2.3] - 2026-07-27
9
+
10
+ ### Added
11
+ - `DocPilot(llm="ollama", num_ctx=...)` — Ollama 요청에 `num_ctx`를 실어 보내고, RAG/content로 조립된 프롬프트가 예상 토큰 기준으로 `num_ctx`를 초과하면 API 호출 전에 `ContextExceededError`로 즉시 차단 (기존엔 조용히 잘리거나 응답이 중간에 끊길 수 있었음)
12
+ - `RagMapper.map()`: `ContextExceededError` 발생 시 `top_k`를 절반씩 줄여 최대 2회 자동 재시도 (Ollama 사전 차단 + Claude/OpenAI/Gemini/Grok의 실제 API 거부 에러 양쪽 모두에 적용)
13
+ - Ollama 매퍼 기본 요청 타임아웃 180초 (`OllamaMapper(timeout=...)`로 조정 가능) — VRAM 부족 시 에러 없이 CPU로 전환되며 20~50배 느려지는 상황에 대한 안전장치
14
+
8
15
  ## [0.2.2] - 2026-07-24
9
16
 
10
17
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: smart-docgen
3
- Version: 0.2.2
3
+ Version: 0.2.3
4
4
  Summary: LLM-powered document generation from data sources and templates
5
5
  License: MIT
6
6
  Project-URL: Homepage, https://github.com/pjkwon/docpilot
@@ -151,11 +151,26 @@ pip install "smart-docgen[pdf,openai,postgres]" # 풀 스택
151
151
 
152
152
  **Ollama 등 로컬 모델의 컨텍스트 한도.** Ollama는 요청에 `num_ctx`를 명시하지 않으면 모델이 지원하는
153
153
  최대 컨텍스트보다 훨씬 작은 기본값(예: 4096 — 모델이 32k를 지원해도)으로 로드합니다. 실제 로드된 값은
154
- `ollama ps`로 확인할 수 있습니다. RAG로 검색된 컨텍스트가 크면 이 기본값에 걸려 LLM 응답이 중간에
155
- 잘릴 수 있으며, smart-docgen은 현재 `num_ctx`를 API 호출에 실어 보내지 않습니다 — 필요하면 Ollama
156
- 서버를 `OLLAMA_CONTEXT_LENGTH` 환경변수나 커스텀 Modelfile로 설정하세요. 응답이 max_tokens/컨텍스트
157
- 한도로 잘리면 `MappingError` 메시지에 "max_tokens 제한으로 잘림"이 명시되어 일반 JSON 파싱 실패와
158
- 구분되므로, 이 메시지가 뜨면 `top_k`를 줄이거나 Ollama의 컨텍스트 한도를 늘려보세요.
154
+ `ollama ps`로 확인할 수 있습니다. `DocPilot(llm="ollama", num_ctx=8192)`처럼 `num_ctx`를 넘기면
155
+ 그 값이 요청마다 Ollama에 전달되고(서버가 그 이상으로 미리 로드돼 있어야 합니다 — `num_ctx`는 요청
156
+ 옵션일 뿐 서버가 로드한 컨텍스트 자체를 늘리지 않습니다. 서버 쪽 최대치는 여전히
157
+ `OLLAMA_CONTEXT_LENGTH` 환경변수나 커스텀 Modelfile로 설정), RAG/content로 조립된 프롬프트가
158
+ 바이트 기반 추정치로 `num_ctx`(+ `max_tokens`)를 넘으면 API 호출 전에 `ContextExceededError`로
159
+ 즉시 막습니다(추정치라 ±30% 오차 가능 — 정확한 카운트는 Ollama가 토큰 카운팅 API를 제공하지 않아
160
+ 불가능합니다). `num_ctx`를 넘기지 않으면 이전과 동일하게 아무 사전 검증 없이 그대로 전송되며, Ollama
161
+ 기본값에 걸려 프롬프트 앞부분이 조용히 잘리거나 응답이 중간에 끊길 수 있습니다.
162
+
163
+ `generate()`(RAG 경로)를 쓰면 `ContextExceededError`가 나든(Ollama 사전 차단), Claude/OpenAI/Gemini/Grok이
164
+ 컨텍스트 초과로 요청을 거부하든 `RagMapper`가 자동으로 `top_k`를 절반씩 줄여 최대 2회 재시도합니다
165
+ (10 → 5 → 2 등, 1까지 줄여도 실패하면 최종적으로 에러를 올립니다). `generate_from_content()`처럼 RAG가
166
+ 없는 경로는 `top_k` 자체가 없어 재시도 대상이 아니며, `max_input_tokens`로 사전에 상한을 걸어야 합니다.
167
+
168
+ Ollama는 컨텍스트 초과와 별개로 VRAM이 부족하면 에러 없이 CPU로 스필오버되며 20~50배 느려질 수 있어
169
+ ("멈춘 것"처럼 보임), `OllamaMapper`/`DocPilot(llm="ollama", ...)`는 기본 180초 요청 타임아웃을 둡니다
170
+ — 정상적인 요청도 하드웨어에 따라 이보다 오래 걸릴 수 있으니 필요시 `OllamaMapper(timeout=...)`로
171
+ 조정하세요. 응답이 max_tokens/컨텍스트 한도로 잘리면 `MappingError` 메시지에 "max_tokens 제한으로 잘림"이
172
+ 명시되어 일반 JSON 파싱 실패와 구분되므로, 이 메시지가 뜨면 `top_k`를 줄이거나 `num_ctx`(및 서버의
173
+ 컨텍스트 한도)를 늘려보세요.
159
174
 
160
175
  ## LLM 제공자
161
176
 
@@ -1348,6 +1363,7 @@ from docpilot.exceptions import (
1348
1363
  DocPilotError,
1349
1364
  IngestionError,
1350
1365
  MappingError,
1366
+ ContextExceededError, # MappingError의 서브클래스 — 컨텍스트 초과로 거부/차단된 경우
1351
1367
  BuilderError,
1352
1368
  ConversionError,
1353
1369
  SearchError,
@@ -1356,6 +1372,8 @@ from docpilot.exceptions import (
1356
1372
 
1357
1373
  try:
1358
1374
  pilot.generate(...)
1375
+ except ContextExceededError as e:
1376
+ print(e.detail) # RagMapper가 top_k를 줄여가며 재시도했지만 끝내 실패한 경우
1359
1377
  except MappingError as e:
1360
1378
  print(e.detail) # 상세 오류 메시지
1361
1379
  except DocPilotError as e:
@@ -85,11 +85,26 @@ pip install "smart-docgen[pdf,openai,postgres]" # 풀 스택
85
85
 
86
86
  **Ollama 등 로컬 모델의 컨텍스트 한도.** Ollama는 요청에 `num_ctx`를 명시하지 않으면 모델이 지원하는
87
87
  최대 컨텍스트보다 훨씬 작은 기본값(예: 4096 — 모델이 32k를 지원해도)으로 로드합니다. 실제 로드된 값은
88
- `ollama ps`로 확인할 수 있습니다. RAG로 검색된 컨텍스트가 크면 이 기본값에 걸려 LLM 응답이 중간에
89
- 잘릴 수 있으며, smart-docgen은 현재 `num_ctx`를 API 호출에 실어 보내지 않습니다 — 필요하면 Ollama
90
- 서버를 `OLLAMA_CONTEXT_LENGTH` 환경변수나 커스텀 Modelfile로 설정하세요. 응답이 max_tokens/컨텍스트
91
- 한도로 잘리면 `MappingError` 메시지에 "max_tokens 제한으로 잘림"이 명시되어 일반 JSON 파싱 실패와
92
- 구분되므로, 이 메시지가 뜨면 `top_k`를 줄이거나 Ollama의 컨텍스트 한도를 늘려보세요.
88
+ `ollama ps`로 확인할 수 있습니다. `DocPilot(llm="ollama", num_ctx=8192)`처럼 `num_ctx`를 넘기면
89
+ 그 값이 요청마다 Ollama에 전달되고(서버가 그 이상으로 미리 로드돼 있어야 합니다 — `num_ctx`는 요청
90
+ 옵션일 뿐 서버가 로드한 컨텍스트 자체를 늘리지 않습니다. 서버 쪽 최대치는 여전히
91
+ `OLLAMA_CONTEXT_LENGTH` 환경변수나 커스텀 Modelfile로 설정), RAG/content로 조립된 프롬프트가
92
+ 바이트 기반 추정치로 `num_ctx`(+ `max_tokens`)를 넘으면 API 호출 전에 `ContextExceededError`로
93
+ 즉시 막습니다(추정치라 ±30% 오차 가능 — 정확한 카운트는 Ollama가 토큰 카운팅 API를 제공하지 않아
94
+ 불가능합니다). `num_ctx`를 넘기지 않으면 이전과 동일하게 아무 사전 검증 없이 그대로 전송되며, Ollama
95
+ 기본값에 걸려 프롬프트 앞부분이 조용히 잘리거나 응답이 중간에 끊길 수 있습니다.
96
+
97
+ `generate()`(RAG 경로)를 쓰면 `ContextExceededError`가 나든(Ollama 사전 차단), Claude/OpenAI/Gemini/Grok이
98
+ 컨텍스트 초과로 요청을 거부하든 `RagMapper`가 자동으로 `top_k`를 절반씩 줄여 최대 2회 재시도합니다
99
+ (10 → 5 → 2 등, 1까지 줄여도 실패하면 최종적으로 에러를 올립니다). `generate_from_content()`처럼 RAG가
100
+ 없는 경로는 `top_k` 자체가 없어 재시도 대상이 아니며, `max_input_tokens`로 사전에 상한을 걸어야 합니다.
101
+
102
+ Ollama는 컨텍스트 초과와 별개로 VRAM이 부족하면 에러 없이 CPU로 스필오버되며 20~50배 느려질 수 있어
103
+ ("멈춘 것"처럼 보임), `OllamaMapper`/`DocPilot(llm="ollama", ...)`는 기본 180초 요청 타임아웃을 둡니다
104
+ — 정상적인 요청도 하드웨어에 따라 이보다 오래 걸릴 수 있으니 필요시 `OllamaMapper(timeout=...)`로
105
+ 조정하세요. 응답이 max_tokens/컨텍스트 한도로 잘리면 `MappingError` 메시지에 "max_tokens 제한으로 잘림"이
106
+ 명시되어 일반 JSON 파싱 실패와 구분되므로, 이 메시지가 뜨면 `top_k`를 줄이거나 `num_ctx`(및 서버의
107
+ 컨텍스트 한도)를 늘려보세요.
93
108
 
94
109
  ## LLM 제공자
95
110
 
@@ -1282,6 +1297,7 @@ from docpilot.exceptions import (
1282
1297
  DocPilotError,
1283
1298
  IngestionError,
1284
1299
  MappingError,
1300
+ ContextExceededError, # MappingError의 서브클래스 — 컨텍스트 초과로 거부/차단된 경우
1285
1301
  BuilderError,
1286
1302
  ConversionError,
1287
1303
  SearchError,
@@ -1290,6 +1306,8 @@ from docpilot.exceptions import (
1290
1306
 
1291
1307
  try:
1292
1308
  pilot.generate(...)
1309
+ except ContextExceededError as e:
1310
+ print(e.detail) # RagMapper가 top_k를 줄여가며 재시도했지만 끝내 실패한 경우
1293
1311
  except MappingError as e:
1294
1312
  print(e.detail) # 상세 오류 메시지
1295
1313
  except DocPilotError as e:
@@ -175,6 +175,10 @@ def _b(base_url: str | None) -> dict:
175
175
  return {"base_url": base_url} if base_url else {}
176
176
 
177
177
 
178
+ def _n(num_ctx: int | None) -> dict:
179
+ return {"num_ctx": num_ctx} if num_ctx else {}
180
+
181
+
178
182
  def _ingest_instructions_doc(path: Path) -> str:
179
183
  """지침 문서를 읽어 텍스트로 반환한다. 지원하지 않는 형식이면 빈 문자열 반환."""
180
184
  from docpilot.ingestion import text as text_ing
@@ -258,12 +262,6 @@ def _estimate_tokens_from_folder(folder: Path, n_sections: int) -> int:
258
262
  _DEFAULT_MAX_INPUT_TOKENS_WARN = 50_000
259
263
 
260
264
 
261
- def _estimate_tokens_raw(text: str) -> int:
262
- """Rough token estimate for text that goes into the prompt in full — no RAG retrieval
263
- subset, so (unlike _estimate_tokens_from_folder) no per-section cap applies."""
264
- return int(len(text.encode("utf-8")) * 0.4)
265
-
266
-
267
265
  def _resolve_instructions(
268
266
  extra_instructions: str | None,
269
267
  sidecar_instructions: str,
@@ -313,7 +311,8 @@ def _resolve_content(content: str | list[str | Path] | list[IngestedDocument]) -
313
311
  def _check_content_size(content_str: str, max_input_tokens: int | None) -> None:
314
312
  """Warn or raise on a rough byte-based token estimate — *_from_content() methods send
315
313
  content in full with no RAG top_k to bound its size automatically."""
316
- estimated_tokens = _estimate_tokens_raw(content_str)
314
+ from docpilot.tokens import estimate_tokens_raw
315
+ estimated_tokens = estimate_tokens_raw(content_str)
317
316
  if max_input_tokens is not None:
318
317
  if estimated_tokens > max_input_tokens:
319
318
  raise MappingError(
@@ -1022,17 +1021,27 @@ class DocPilot:
1022
1021
  api_key: str | None = None,
1023
1022
  model: str | None = None,
1024
1023
  base_url: str | None = None,
1024
+ num_ctx: int | None = None,
1025
1025
  database_url: str | None = None,
1026
1026
  embed_fn=None,
1027
1027
  use_reranker: bool = False,
1028
1028
  ) -> None:
1029
+ """
1030
+ num_ctx: Ollama-only — the context window (input+output token budget) the server
1031
+ loaded the model with. Ollama defaults to a small value (often 4096) regardless
1032
+ of what the model actually supports, and silently truncates prompts that exceed
1033
+ it rather than erroring — see README "Ollama 등 로컬 모델의 컨텍스트 한도". Pass the
1034
+ same value your Ollama server was started/configured with (check via `ollama ps`)
1035
+ so docpilot can (a) forward it as a per-request option and (b) reject oversized
1036
+ RAG/content prompts before sending them, instead of silently losing context.
1037
+ """
1029
1038
  self._llm = llm or os.environ.get("DOCPILOT_LLM", "claude")
1030
1039
  self._api_key = api_key
1031
1040
  if embed_fn is None:
1032
1041
  from docpilot.search.embedding import default_embed_fn
1033
1042
  embed_fn = default_embed_fn() # None when sentence-transformers not installed
1034
1043
  self._embed_fn = embed_fn
1035
- base_mapper = self._build_mapper(self._llm, api_key, model, base_url)
1044
+ base_mapper = self._build_mapper(self._llm, api_key, model, base_url, num_ctx)
1036
1045
 
1037
1046
  from docpilot.mapping.rag import RagMapper
1038
1047
  self._mapper = base_mapper
@@ -1459,7 +1468,8 @@ class DocPilot:
1459
1468
  est_output = len(sections) * _EST_OUTPUT_TOKENS_PER_SECTION
1460
1469
 
1461
1470
  if quick:
1462
- input_tokens = _estimate_tokens_raw(content_str)
1471
+ from docpilot.tokens import estimate_tokens_raw
1472
+ input_tokens = estimate_tokens_raw(content_str)
1463
1473
  input_cost = input_tokens / 1_000_000 * in_price
1464
1474
  output_cost = est_output / 1_000_000 * out_price
1465
1475
  lines = [
@@ -1605,7 +1615,13 @@ class DocPilot:
1605
1615
  return suggest_extras(folder)
1606
1616
 
1607
1617
  @staticmethod
1608
- def _build_mapper(llm: str, api_key: str | None, model: str | None, base_url: str | None):
1618
+ def _build_mapper(
1619
+ llm: str,
1620
+ api_key: str | None,
1621
+ model: str | None,
1622
+ base_url: str | None,
1623
+ num_ctx: int | None = None,
1624
+ ):
1609
1625
  from docpilot.mapping import ClaudeMapper, OpenAIMapper, GeminiMapper
1610
1626
  from docpilot.mapping.openai_compat import GrokMapper, OllamaMapper
1611
1627
 
@@ -1619,7 +1635,7 @@ class DocPilot:
1619
1635
  case "grok":
1620
1636
  return GrokMapper(api_key=api_key, **(_m(model)))
1621
1637
  case "ollama":
1622
- return OllamaMapper(**(_m(model)), **(_b(base_url)))
1638
+ return OllamaMapper(**(_m(model)), **(_b(base_url)), **(_n(num_ctx)))
1623
1639
  case _:
1624
1640
  raise MappingError(
1625
1641
  f"Unknown LLM '{llm}'. "
@@ -0,0 +1,63 @@
1
+ from __future__ import annotations
2
+
3
+
4
+ class DocPilotError(Exception):
5
+ """Base exception for all docpilot errors."""
6
+
7
+ def __init__(self, message: str, detail: str | None = None) -> None:
8
+ self.detail = detail
9
+ full_message = f"{message} — {detail}" if detail else message
10
+ super().__init__(full_message)
11
+
12
+
13
+ class IngestionError(DocPilotError):
14
+ """Raised when a source file cannot be parsed or read."""
15
+
16
+
17
+ class MappingError(DocPilotError):
18
+ """Raised when LLM fails to map content to template sections."""
19
+
20
+
21
+ class ContextExceededError(MappingError):
22
+ """Raised when a request would exceed (Ollama: local pre-flight estimate) or was
23
+ rejected for exceeding (hosted APIs: live error from the provider) the model's
24
+ context window. Kept distinct from MappingError so callers like RagMapper can retry
25
+ with a smaller top_k specifically for this failure, without swallowing unrelated
26
+ errors (auth, rate limit, etc.) that a retry can't fix."""
27
+
28
+
29
+ _CONTEXT_OVERFLOW_MARKERS = (
30
+ "context length",
31
+ "context_length_exceeded",
32
+ "maximum context",
33
+ "context window",
34
+ "too many tokens",
35
+ "exceeds the maximum number of tokens",
36
+ "token limit",
37
+ )
38
+
39
+
40
+ def is_context_overflow_error(message: str) -> bool:
41
+ """Heuristic match against a provider SDK error message to tell a context-window
42
+ rejection apart from other API failures. Providers don't share a common exception
43
+ type for this, so this is a substring match, not a guarantee — false negatives just
44
+ fall through to the generic MappingError path (no retry); false positives cost at
45
+ most a couple of wasted retries before the error surfaces anyway."""
46
+ lowered = message.lower()
47
+ return any(marker in lowered for marker in _CONTEXT_OVERFLOW_MARKERS)
48
+
49
+
50
+ class BuilderError(DocPilotError):
51
+ """Raised when document generation fails."""
52
+
53
+
54
+ class ConversionError(DocPilotError):
55
+ """Raised when a file format conversion fails."""
56
+
57
+
58
+ class SearchError(DocPilotError):
59
+ """Raised when a search or index operation fails."""
60
+
61
+
62
+ class TemplateError(DocPilotError):
63
+ """Raised when template analysis or generation fails."""
@@ -4,7 +4,7 @@ import logging
4
4
  import os
5
5
  import time
6
6
 
7
- from docpilot.exceptions import MappingError
7
+ from docpilot.exceptions import ContextExceededError, MappingError, is_context_overflow_error
8
8
  from docpilot.mapping.base import BaseLLMMapper, MappingResult, TemplateSection
9
9
 
10
10
  logger = logging.getLogger(__name__)
@@ -61,6 +61,8 @@ class ClaudeMapper(BaseLLMMapper):
61
61
  messages=[{"role": "user", "content": prompt}],
62
62
  )
63
63
  except Exception as e:
64
+ if is_context_overflow_error(str(e)):
65
+ raise ContextExceededError("Claude API가 컨텍스트 초과로 요청을 거부함", detail=str(e)) from e
64
66
  raise MappingError("Claude API call failed", detail=str(e)) from e
65
67
  elapsed = time.perf_counter() - start
66
68
 
@@ -4,7 +4,7 @@ import logging
4
4
  import os
5
5
  import time
6
6
 
7
- from docpilot.exceptions import MappingError
7
+ from docpilot.exceptions import ContextExceededError, MappingError, is_context_overflow_error
8
8
  from docpilot.mapping.base import BaseLLMMapper, MappingResult, TemplateSection
9
9
 
10
10
  logger = logging.getLogger(__name__)
@@ -68,6 +68,8 @@ class GeminiMapper(BaseLLMMapper):
68
68
  config=types.GenerateContentConfig(max_output_tokens=self._max_tokens),
69
69
  )
70
70
  except Exception as e:
71
+ if is_context_overflow_error(str(e)):
72
+ raise ContextExceededError("Gemini API가 컨텍스트 초과로 요청을 거부함", detail=str(e)) from e
71
73
  raise MappingError("Gemini API call failed", detail=str(e)) from e
72
74
  elapsed = time.perf_counter() - start
73
75
 
@@ -4,7 +4,7 @@ import logging
4
4
  import os
5
5
  import time
6
6
 
7
- from docpilot.exceptions import MappingError
7
+ from docpilot.exceptions import ContextExceededError, MappingError, is_context_overflow_error
8
8
  from docpilot.mapping.base import BaseLLMMapper, MappingResult, TemplateSection
9
9
 
10
10
  logger = logging.getLogger(__name__)
@@ -66,6 +66,8 @@ class OpenAIMapper(BaseLLMMapper):
66
66
  messages=[{"role": "user", "content": prompt}],
67
67
  )
68
68
  except Exception as e:
69
+ if is_context_overflow_error(str(e)):
70
+ raise ContextExceededError("OpenAI API가 컨텍스트 초과로 요청을 거부함", detail=str(e)) from e
69
71
  raise MappingError("OpenAI API call failed", detail=str(e)) from e
70
72
  elapsed = time.perf_counter() - start
71
73
 
@@ -4,8 +4,9 @@ import logging
4
4
  import os
5
5
  import time
6
6
 
7
- from docpilot.exceptions import MappingError
7
+ from docpilot.exceptions import ContextExceededError, MappingError, is_context_overflow_error
8
8
  from docpilot.mapping.base import BaseLLMMapper, MappingResult, TemplateSection
9
+ from docpilot.tokens import estimate_tokens_raw
9
10
 
10
11
  logger = logging.getLogger(__name__)
11
12
 
@@ -25,25 +26,59 @@ class OpenAICompatMapper(BaseLLMMapper):
25
26
  base_url: str,
26
27
  api_key: str = "not-required",
27
28
  max_tokens: int = 8096,
29
+ num_ctx: int | None = None,
30
+ timeout: float | None = None,
28
31
  ) -> None:
29
32
  self._model = model
30
33
  self._base_url = base_url
31
34
  self._api_key = api_key
32
35
  self._max_tokens = max_tokens
36
+ self._num_ctx = num_ctx
37
+ self._timeout = timeout
38
+
39
+ def _extra_body(self) -> dict:
40
+ # Ollama-specific request option — openai SDK has no native num_ctx param, so it
41
+ # must be passed through extra_body's "options" dict (Ollama's own convention).
42
+ return {"options": {"num_ctx": self._num_ctx}} if self._num_ctx else {}
43
+
44
+ def _check_num_ctx(self, prompt: str, max_tokens: int) -> None:
45
+ """Reject prompts that won't fit num_ctx *before* sending — Ollama itself doesn't
46
+ error on this, it silently truncates the prompt from the front instead, which loses
47
+ RAG context with no signal in the response (see README "Ollama 등 로컬 모델의 컨텍스트
48
+ 한도"). Estimate only — no exact tokenizer available for Ollama models over the API."""
49
+ if self._num_ctx is None:
50
+ return
51
+ estimated = estimate_tokens_raw(prompt)
52
+ if estimated + max_tokens > self._num_ctx:
53
+ raise ContextExceededError(
54
+ f"예상 입력 토큰({estimated:,}) + max_tokens({max_tokens:,})이 "
55
+ f"num_ctx({self._num_ctx:,})를 초과합니다.",
56
+ detail=(
57
+ "이 상태로 보내면 Ollama가 프롬프트 앞부분을 조용히 잘라내거나 "
58
+ "응답이 중간에 끊길 수 있습니다. num_ctx를 늘리거나 top_k/컨텍스트 "
59
+ "크기를 줄이세요. (추정치는 바이트 기반 휴리스틱으로 ±30% 오차 가능)"
60
+ ),
61
+ )
33
62
 
34
63
  def complete(self, prompt: str, max_tokens: int = 2048) -> str:
35
64
  try:
36
65
  from openai import OpenAI
37
66
  except ImportError as e:
38
67
  raise MappingError("openai SDK required: pip install openai") from e
39
- client = OpenAI(api_key=self._api_key, base_url=self._base_url)
68
+ self._check_num_ctx(prompt, max_tokens)
69
+ client = OpenAI(api_key=self._api_key, base_url=self._base_url, timeout=self._timeout)
40
70
  try:
41
71
  response = client.chat.completions.create(
42
72
  model=self._model,
43
73
  max_tokens=max_tokens,
44
74
  messages=[{"role": "user", "content": prompt}],
75
+ extra_body=self._extra_body(),
45
76
  )
46
77
  except Exception as e:
78
+ if is_context_overflow_error(str(e)):
79
+ raise ContextExceededError(
80
+ f"API가 컨텍스트 초과로 요청을 거부함 ({self._base_url})", detail=str(e)
81
+ ) from e
47
82
  raise MappingError(f"API call failed ({self._base_url})", detail=str(e)) from e
48
83
  return response.choices[0].message.content or ""
49
84
 
@@ -58,8 +93,9 @@ class OpenAICompatMapper(BaseLLMMapper):
58
93
  except ImportError as e:
59
94
  raise MappingError("openai SDK required: pip install openai") from e
60
95
 
61
- client = OpenAI(api_key=self._api_key, base_url=self._base_url)
96
+ client = OpenAI(api_key=self._api_key, base_url=self._base_url, timeout=self._timeout)
62
97
  prompt = self._build_prompt(self._resolve_content(content), sections, instructions)
98
+ self._check_num_ctx(prompt, self._max_tokens)
63
99
 
64
100
  start = time.perf_counter()
65
101
  try:
@@ -67,8 +103,13 @@ class OpenAICompatMapper(BaseLLMMapper):
67
103
  model=self._model,
68
104
  max_tokens=self._max_tokens,
69
105
  messages=[{"role": "user", "content": prompt}],
106
+ extra_body=self._extra_body(),
70
107
  )
71
108
  except Exception as e:
109
+ if is_context_overflow_error(str(e)):
110
+ raise ContextExceededError(
111
+ f"API가 컨텍스트 초과로 요청을 거부함 ({self._base_url})", detail=str(e)
112
+ ) from e
72
113
  raise MappingError(
73
114
  f"API call failed ({self._base_url})", detail=str(e)
74
115
  ) from e
@@ -110,10 +151,21 @@ def GrokMapper(
110
151
  return OpenAICompatMapper(model=model, base_url=_GROK_BASE_URL, api_key=key, max_tokens=max_tokens)
111
152
 
112
153
 
154
+ _OLLAMA_DEFAULT_TIMEOUT = 180.0 # seconds — Ollama has no explicit context-overflow error;
155
+ # a VRAM-starved request degrades to CPU offload instead of failing (20-50x slower, can look
156
+ # hung), so this is a starting-point safety net rather than a measured value. Pass timeout=
157
+ # to OllamaMapper()/OpenAICompatMapper() directly to tune for your hardware.
158
+
159
+
113
160
  def OllamaMapper(
114
161
  model: str = "llama3.2",
115
162
  base_url: str | None = None,
116
163
  max_tokens: int = 8096,
164
+ num_ctx: int | None = None,
165
+ timeout: float = _OLLAMA_DEFAULT_TIMEOUT,
117
166
  ) -> OpenAICompatMapper:
118
167
  url = base_url or os.environ.get("OLLAMA_BASE_URL", _OLLAMA_BASE_URL)
119
- return OpenAICompatMapper(model=model, base_url=url, api_key="ollama", max_tokens=max_tokens)
168
+ return OpenAICompatMapper(
169
+ model=model, base_url=url, api_key="ollama", max_tokens=max_tokens,
170
+ num_ctx=num_ctx, timeout=timeout,
171
+ )
@@ -1,16 +1,22 @@
1
1
  from __future__ import annotations
2
2
 
3
+ import logging
3
4
  from collections.abc import Callable
4
5
  from typing import TYPE_CHECKING
5
6
 
7
+ from docpilot.exceptions import ContextExceededError
6
8
  from docpilot.mapping.base import BaseLLMMapper, MappingResult, TemplateSection
7
9
  from docpilot.search.models import SearchFilter, SearchResult
8
10
 
9
11
  if TYPE_CHECKING:
10
12
  from docpilot.ingestion.models import IngestedDocument
11
13
 
14
+ logger = logging.getLogger(__name__)
15
+
12
16
  EmbedFn = Callable[[str], list[float]]
13
17
 
18
+ _MAX_CONTEXT_RETRIES = 2
19
+
14
20
 
15
21
  class RagMapper:
16
22
  """
@@ -48,8 +54,21 @@ class RagMapper:
48
54
  top_k: int | None = None,
49
55
  filters: SearchFilter | None = None,
50
56
  ) -> MappingResult:
51
- content = self.retrieve_content(sections, top_k=top_k, filters=filters)
52
- return self._mapper.map(content, sections, instructions)
57
+ effective_top_k = top_k if top_k is not None else self._top_k
58
+
59
+ for attempt in range(_MAX_CONTEXT_RETRIES + 1):
60
+ content = self.retrieve_content(sections, top_k=effective_top_k, filters=filters)
61
+ try:
62
+ return self._mapper.map(content, sections, instructions)
63
+ except ContextExceededError:
64
+ if attempt >= _MAX_CONTEXT_RETRIES or effective_top_k <= 1:
65
+ raise
66
+ new_top_k = max(1, effective_top_k // 2)
67
+ logger.warning(
68
+ "컨텍스트 초과로 top_k %d → %d로 줄여 재시도 (%d/%d)",
69
+ effective_top_k, new_top_k, attempt + 1, _MAX_CONTEXT_RETRIES,
70
+ )
71
+ effective_top_k = new_top_k
53
72
 
54
73
  def retrieve_content(
55
74
  self,
@@ -0,0 +1,11 @@
1
+ from __future__ import annotations
2
+
3
+ _TOKENS_PER_BYTE = 0.4
4
+
5
+
6
+ def estimate_tokens_raw(text: str) -> int:
7
+ """Rough token estimate for text sent to an LLM in full — ~0.4 tokens/byte, tuned for
8
+ Korean/mixed text. No tokenizer call, so this is a heuristic (±30%), not an exact count;
9
+ exact counts require the model's own tokenizer, which local models (Ollama) don't expose
10
+ over the API."""
11
+ return int(len(text.encode("utf-8")) * _TOKENS_PER_BYTE)
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: smart-docgen
3
- Version: 0.2.2
3
+ Version: 0.2.3
4
4
  Summary: LLM-powered document generation from data sources and templates
5
5
  License: MIT
6
6
  Project-URL: Homepage, https://github.com/pjkwon/docpilot
@@ -151,11 +151,26 @@ pip install "smart-docgen[pdf,openai,postgres]" # 풀 스택
151
151
 
152
152
  **Ollama 등 로컬 모델의 컨텍스트 한도.** Ollama는 요청에 `num_ctx`를 명시하지 않으면 모델이 지원하는
153
153
  최대 컨텍스트보다 훨씬 작은 기본값(예: 4096 — 모델이 32k를 지원해도)으로 로드합니다. 실제 로드된 값은
154
- `ollama ps`로 확인할 수 있습니다. RAG로 검색된 컨텍스트가 크면 이 기본값에 걸려 LLM 응답이 중간에
155
- 잘릴 수 있으며, smart-docgen은 현재 `num_ctx`를 API 호출에 실어 보내지 않습니다 — 필요하면 Ollama
156
- 서버를 `OLLAMA_CONTEXT_LENGTH` 환경변수나 커스텀 Modelfile로 설정하세요. 응답이 max_tokens/컨텍스트
157
- 한도로 잘리면 `MappingError` 메시지에 "max_tokens 제한으로 잘림"이 명시되어 일반 JSON 파싱 실패와
158
- 구분되므로, 이 메시지가 뜨면 `top_k`를 줄이거나 Ollama의 컨텍스트 한도를 늘려보세요.
154
+ `ollama ps`로 확인할 수 있습니다. `DocPilot(llm="ollama", num_ctx=8192)`처럼 `num_ctx`를 넘기면
155
+ 그 값이 요청마다 Ollama에 전달되고(서버가 그 이상으로 미리 로드돼 있어야 합니다 — `num_ctx`는 요청
156
+ 옵션일 뿐 서버가 로드한 컨텍스트 자체를 늘리지 않습니다. 서버 쪽 최대치는 여전히
157
+ `OLLAMA_CONTEXT_LENGTH` 환경변수나 커스텀 Modelfile로 설정), RAG/content로 조립된 프롬프트가
158
+ 바이트 기반 추정치로 `num_ctx`(+ `max_tokens`)를 넘으면 API 호출 전에 `ContextExceededError`로
159
+ 즉시 막습니다(추정치라 ±30% 오차 가능 — 정확한 카운트는 Ollama가 토큰 카운팅 API를 제공하지 않아
160
+ 불가능합니다). `num_ctx`를 넘기지 않으면 이전과 동일하게 아무 사전 검증 없이 그대로 전송되며, Ollama
161
+ 기본값에 걸려 프롬프트 앞부분이 조용히 잘리거나 응답이 중간에 끊길 수 있습니다.
162
+
163
+ `generate()`(RAG 경로)를 쓰면 `ContextExceededError`가 나든(Ollama 사전 차단), Claude/OpenAI/Gemini/Grok이
164
+ 컨텍스트 초과로 요청을 거부하든 `RagMapper`가 자동으로 `top_k`를 절반씩 줄여 최대 2회 재시도합니다
165
+ (10 → 5 → 2 등, 1까지 줄여도 실패하면 최종적으로 에러를 올립니다). `generate_from_content()`처럼 RAG가
166
+ 없는 경로는 `top_k` 자체가 없어 재시도 대상이 아니며, `max_input_tokens`로 사전에 상한을 걸어야 합니다.
167
+
168
+ Ollama는 컨텍스트 초과와 별개로 VRAM이 부족하면 에러 없이 CPU로 스필오버되며 20~50배 느려질 수 있어
169
+ ("멈춘 것"처럼 보임), `OllamaMapper`/`DocPilot(llm="ollama", ...)`는 기본 180초 요청 타임아웃을 둡니다
170
+ — 정상적인 요청도 하드웨어에 따라 이보다 오래 걸릴 수 있으니 필요시 `OllamaMapper(timeout=...)`로
171
+ 조정하세요. 응답이 max_tokens/컨텍스트 한도로 잘리면 `MappingError` 메시지에 "max_tokens 제한으로 잘림"이
172
+ 명시되어 일반 JSON 파싱 실패와 구분되므로, 이 메시지가 뜨면 `top_k`를 줄이거나 `num_ctx`(및 서버의
173
+ 컨텍스트 한도)를 늘려보세요.
159
174
 
160
175
  ## LLM 제공자
161
176
 
@@ -1348,6 +1363,7 @@ from docpilot.exceptions import (
1348
1363
  DocPilotError,
1349
1364
  IngestionError,
1350
1365
  MappingError,
1366
+ ContextExceededError, # MappingError의 서브클래스 — 컨텍스트 초과로 거부/차단된 경우
1351
1367
  BuilderError,
1352
1368
  ConversionError,
1353
1369
  SearchError,
@@ -1356,6 +1372,8 @@ from docpilot.exceptions import (
1356
1372
 
1357
1373
  try:
1358
1374
  pilot.generate(...)
1375
+ except ContextExceededError as e:
1376
+ print(e.detail) # RagMapper가 top_k를 줄여가며 재시도했지만 끝내 실패한 경우
1359
1377
  except MappingError as e:
1360
1378
  print(e.detail) # 상세 오류 메시지
1361
1379
  except DocPilotError as e:
@@ -11,6 +11,7 @@ uv.lock
11
11
  docpilot/__init__.py
12
12
  docpilot/exceptions.py
13
13
  docpilot/mcp_server.py
14
+ docpilot/tokens.py
14
15
  docpilot/builder/__init__.py
15
16
  docpilot/builder/base.py
16
17
  docpilot/builder/docx_analyzer.py