smart-docgen 0.2.2__tar.gz → 0.2.4__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 (140) hide show
  1. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/.gitignore +1 -0
  2. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/CHANGELOG.md +12 -0
  3. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/PKG-INFO +38 -6
  4. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/README.md +37 -5
  5. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/__init__.py +44 -15
  6. smart_docgen-0.2.4/docpilot/exceptions.py +63 -0
  7. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/mapping/claude.py +10 -1
  8. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/mapping/gemini.py +11 -3
  9. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/mapping/openai.py +10 -1
  10. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/mapping/openai_compat.py +69 -5
  11. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/mapping/rag.py +21 -2
  12. smart_docgen-0.2.4/docpilot/tokens.py +11 -0
  13. smart_docgen-0.2.4/llm_benchmark_report.md +91 -0
  14. smart_docgen-0.2.4/scripts/llm_benchmark.py +97 -0
  15. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/smart_docgen.egg-info/PKG-INFO +38 -6
  16. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/smart_docgen.egg-info/SOURCES.txt +3 -0
  17. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/smart_docgen.egg-info/scm_file_list.json +104 -101
  18. smart_docgen-0.2.4/smart_docgen.egg-info/scm_version.json +8 -0
  19. smart_docgen-0.2.2/docpilot/exceptions.py +0 -34
  20. smart_docgen-0.2.2/smart_docgen.egg-info/scm_version.json +0 -8
  21. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/.claude/skills/docpilot-tools/SKILL.md +0 -0
  22. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/.claude/skills/docpilot-tools/docpilot_cli.py +0 -0
  23. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/.env.example +0 -0
  24. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/.github/workflows/publish.yml +0 -0
  25. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/LICENSE +0 -0
  26. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/__init__.py +0 -0
  27. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/base.py +0 -0
  28. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/docx_analyzer.py +0 -0
  29. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/docx_builder.py +0 -0
  30. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/html_blocks.py +0 -0
  31. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/html_table.py +0 -0
  32. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/hwp_convert.py +0 -0
  33. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/hwpx_analyzer.py +0 -0
  34. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/hwpx_auto_builder.py +0 -0
  35. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/hwpx_builder.py +0 -0
  36. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/hwpx_bullets.py +0 -0
  37. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/hwpx_dynamic_builder.py +0 -0
  38. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/hwpx_section_generator.py +0 -0
  39. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/hwpx_style_extractor.py +0 -0
  40. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/builder/pdf_builder.py +0 -0
  41. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/db/__init__.py +0 -0
  42. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/db/client.py +0 -0
  43. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/db/indexer.py +0 -0
  44. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/db/schema.py +0 -0
  45. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/db/template_store.py +0 -0
  46. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/ingestion/__init__.py +0 -0
  47. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/ingestion/docx.py +0 -0
  48. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/ingestion/hwp.py +0 -0
  49. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/ingestion/hwpx.py +0 -0
  50. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/ingestion/models.py +0 -0
  51. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/ingestion/pdf.py +0 -0
  52. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/ingestion/text.py +0 -0
  53. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/mapping/__init__.py +0 -0
  54. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/mapping/base.py +0 -0
  55. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/mapping/benchmark.py +0 -0
  56. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/mapping/sidecar.py +0 -0
  57. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/mcp_server.py +0 -0
  58. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/search/__init__.py +0 -0
  59. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/search/_filter.py +0 -0
  60. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/search/alias.py +0 -0
  61. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/search/embedding.py +0 -0
  62. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/search/eval.py +0 -0
  63. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/search/exact.py +0 -0
  64. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/search/highlight.py +0 -0
  65. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/search/hybrid.py +0 -0
  66. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/search/models.py +0 -0
  67. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/search/morpheme.py +0 -0
  68. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/search/reranker.py +0 -0
  69. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/template_generator/__init__.py +0 -0
  70. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/template_generator/analyzer.py +0 -0
  71. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/template_generator/docx_extractor.py +0 -0
  72. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/template_generator/extractor.py +0 -0
  73. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/template_generator/generator.py +0 -0
  74. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/base/Contents/content.hpf +0 -0
  75. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/base/Contents/header.xml +0 -0
  76. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/base/Contents/section0.xml +0 -0
  77. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/base/META-INF/container.rdf +0 -0
  78. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/base/META-INF/container.xml +0 -0
  79. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/base/META-INF/manifest.xml +0 -0
  80. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/base/Preview/PrvImage.png +0 -0
  81. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/base/Preview/PrvText.txt +0 -0
  82. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/base/mimetype +0 -0
  83. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/base/settings.xml +0 -0
  84. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/base/version.xml +0 -0
  85. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/gonmun/header.xml +0 -0
  86. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/gonmun/section0.xml +0 -0
  87. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/gonmun/sidecar.json +0 -0
  88. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/minutes/header.xml +0 -0
  89. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/minutes/section0.xml +0 -0
  90. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/minutes/sidecar.json +0 -0
  91. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/proposal/header.xml +0 -0
  92. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/proposal/section0.xml +0 -0
  93. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/proposal/sidecar.json +0 -0
  94. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/report/header.xml +0 -0
  95. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/report/section0.xml +0 -0
  96. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/docpilot/templates/report/sidecar.json +0 -0
  97. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/example/run.py +0 -0
  98. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/pyproject.toml +0 -0
  99. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/scripts/chunk_size_compare.py +0 -0
  100. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/scripts/gen_/355/225/231/355/232/214/353/263/264/352/263/240/354/204/234.py" +0 -0
  101. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/scripts/gen_/355/225/231/355/232/214/353/263/264/352/263/240/354/204/234_hwpx_from_docx.py" +0 -0
  102. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/scripts/inspect_index.py +0 -0
  103. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/scripts/make_ebs_template.py +0 -0
  104. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/scripts/test_docgen.py +0 -0
  105. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/scripts/test_folder_search.py +0 -0
  106. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/scripts/test_hwpx_to_docx.py +0 -0
  107. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/scripts/test_mapping.py +0 -0
  108. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/scripts/test_ollama_truncation.py +0 -0
  109. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/scripts/test_quality.py +0 -0
  110. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/scripts/test_real.py +0 -0
  111. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/scripts/verify_html_render.py +0 -0
  112. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/setup.cfg +0 -0
  113. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/smart_docgen.egg-info/dependency_links.txt +0 -0
  114. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/smart_docgen.egg-info/entry_points.txt +0 -0
  115. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/smart_docgen.egg-info/requires.txt +0 -0
  116. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/smart_docgen.egg-info/top_level.txt +0 -0
  117. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/__init__.py +0 -0
  118. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/conftest.py +0 -0
  119. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/mocks/__init__.py +0 -0
  120. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/mocks/db_mock.py +0 -0
  121. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/mocks/llm_mock.py +0 -0
  122. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_alias.py +0 -0
  123. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_analyzers.py +0 -0
  124. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_builder.py +0 -0
  125. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_collection.py +0 -0
  126. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_embed_batch_bench.py +0 -0
  127. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_embed_model_bench.py +0 -0
  128. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_embed_quality_bench.py +0 -0
  129. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_embedding.py +0 -0
  130. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_generate_from_content.py +0 -0
  131. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_hwp_ingestion.py +0 -0
  132. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_index_perf.py +0 -0
  133. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_indexer.py +0 -0
  134. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_ingestion.py +0 -0
  135. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_mapping.py +0 -0
  136. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_mcp_server.py +0 -0
  137. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_search.py +0 -0
  138. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_search_quality.py +0 -0
  139. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/tests/test_template_generator.py +0 -0
  140. {smart_docgen-0.2.2 → smart_docgen-0.2.4}/uv.lock +0 -0
@@ -34,6 +34,7 @@ htmlcov/
34
34
  *.md
35
35
  !README.md
36
36
  !CHANGELOG.md
37
+ !llm_benchmark_report.md
37
38
  !.claude/skills/**/*.md
38
39
 
39
40
  # Test artifacts
@@ -5,6 +5,18 @@
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [0.2.4] - 2026-07-27
9
+
10
+ ### Added
11
+ - `DocPilot(temperature=...)` — 5개 LLM 제공자(Claude/OpenAI/Gemini/Grok/Ollama) 공통으로 샘플링 temperature 지정 가능. 미지정 시 제공자/모델 기본값 유지
12
+
13
+ ## [0.2.3] - 2026-07-27
14
+
15
+ ### Added
16
+ - `DocPilot(llm="ollama", num_ctx=...)` — Ollama 요청에 `num_ctx`를 실어 보내고, RAG/content로 조립된 프롬프트가 예상 토큰 기준으로 `num_ctx`를 초과하면 API 호출 전에 `ContextExceededError`로 즉시 차단 (기존엔 조용히 잘리거나 응답이 중간에 끊길 수 있었음)
17
+ - `RagMapper.map()`: `ContextExceededError` 발생 시 `top_k`를 절반씩 줄여 최대 2회 자동 재시도 (Ollama 사전 차단 + Claude/OpenAI/Gemini/Grok의 실제 API 거부 에러 양쪽 모두에 적용)
18
+ - Ollama 매퍼 기본 요청 타임아웃 180초 (`OllamaMapper(timeout=...)`로 조정 가능) — VRAM 부족 시 에러 없이 CPU로 전환되며 20~50배 느려지는 상황에 대한 안전장치
19
+
8
20
  ## [0.2.2] - 2026-07-24
9
21
 
10
22
  ### 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.4
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
 
@@ -220,6 +235,20 @@ pilot = DocPilot(llm="grok", model="grok-3-mini")
220
235
  pilot = DocPilot(llm="ollama", model="deepseek-r1:7b")
221
236
  ```
222
237
 
238
+ ### temperature (샘플링 온도)
239
+
240
+ ```python
241
+ pilot = DocPilot(llm="ollama", model="qwen2.5:7b", temperature=0)
242
+ ```
243
+
244
+ 모든 제공자 공통으로 `temperature`를 넘길 수 있습니다. 미지정 시(기본값 `None`) 제공자/모델 자체의
245
+ 기본값을 그대로 씁니다 — 예를 들어 `ollama show <model>`로 보면 모델마다 Modelfile에 다른 기본값이
246
+ 박혀 있을 수 있습니다(예: 어떤 모델은 1.0). `generate()`는 섹션 내용을 JSON으로 채우는 구조화된
247
+ 출력 작업이라, temperature가 높을수록 같은 입력에도 실행마다 결과가 달라질 수 있고 — 로컬의 작은
248
+ 모델일수록 지시(프롬프트의 `[스타일: ...]` 같은 서식 힌트)를 값에 그대로 베끼는 등 JSON 파싱 실패로
249
+ 이어지는 경우가 관찰됐습니다. 일관된 결과가 중요하면 `temperature=0`(그리디에 가까운 결정적 출력)으로
250
+ 낮추는 걸 권장하되, 완전한 재현성을 보장하지는 않습니다(GPU 병렬 연산 특성상 미세한 차이는 남을 수 있음).
251
+
223
252
  > **`DocPilot(llm=...)`은 `generate()` 파이프라인 전용입니다.**
224
253
  > `build_auto()` · `HwpxDynamicBuilder`는 내부에서 LLM을 독립적으로 호출합니다.
225
254
  > 기본값은 Claude이며, `mapper=` 파라미터로 다른 제공자로 전환할 수 있습니다.
@@ -1348,6 +1377,7 @@ from docpilot.exceptions import (
1348
1377
  DocPilotError,
1349
1378
  IngestionError,
1350
1379
  MappingError,
1380
+ ContextExceededError, # MappingError의 서브클래스 — 컨텍스트 초과로 거부/차단된 경우
1351
1381
  BuilderError,
1352
1382
  ConversionError,
1353
1383
  SearchError,
@@ -1356,6 +1386,8 @@ from docpilot.exceptions import (
1356
1386
 
1357
1387
  try:
1358
1388
  pilot.generate(...)
1389
+ except ContextExceededError as e:
1390
+ print(e.detail) # RagMapper가 top_k를 줄여가며 재시도했지만 끝내 실패한 경우
1359
1391
  except MappingError as e:
1360
1392
  print(e.detail) # 상세 오류 메시지
1361
1393
  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
 
@@ -154,6 +169,20 @@ pilot = DocPilot(llm="grok", model="grok-3-mini")
154
169
  pilot = DocPilot(llm="ollama", model="deepseek-r1:7b")
155
170
  ```
156
171
 
172
+ ### temperature (샘플링 온도)
173
+
174
+ ```python
175
+ pilot = DocPilot(llm="ollama", model="qwen2.5:7b", temperature=0)
176
+ ```
177
+
178
+ 모든 제공자 공통으로 `temperature`를 넘길 수 있습니다. 미지정 시(기본값 `None`) 제공자/모델 자체의
179
+ 기본값을 그대로 씁니다 — 예를 들어 `ollama show <model>`로 보면 모델마다 Modelfile에 다른 기본값이
180
+ 박혀 있을 수 있습니다(예: 어떤 모델은 1.0). `generate()`는 섹션 내용을 JSON으로 채우는 구조화된
181
+ 출력 작업이라, temperature가 높을수록 같은 입력에도 실행마다 결과가 달라질 수 있고 — 로컬의 작은
182
+ 모델일수록 지시(프롬프트의 `[스타일: ...]` 같은 서식 힌트)를 값에 그대로 베끼는 등 JSON 파싱 실패로
183
+ 이어지는 경우가 관찰됐습니다. 일관된 결과가 중요하면 `temperature=0`(그리디에 가까운 결정적 출력)으로
184
+ 낮추는 걸 권장하되, 완전한 재현성을 보장하지는 않습니다(GPU 병렬 연산 특성상 미세한 차이는 남을 수 있음).
185
+
157
186
  > **`DocPilot(llm=...)`은 `generate()` 파이프라인 전용입니다.**
158
187
  > `build_auto()` · `HwpxDynamicBuilder`는 내부에서 LLM을 독립적으로 호출합니다.
159
188
  > 기본값은 Claude이며, `mapper=` 파라미터로 다른 제공자로 전환할 수 있습니다.
@@ -1282,6 +1311,7 @@ from docpilot.exceptions import (
1282
1311
  DocPilotError,
1283
1312
  IngestionError,
1284
1313
  MappingError,
1314
+ ContextExceededError, # MappingError의 서브클래스 — 컨텍스트 초과로 거부/차단된 경우
1285
1315
  BuilderError,
1286
1316
  ConversionError,
1287
1317
  SearchError,
@@ -1290,6 +1320,8 @@ from docpilot.exceptions import (
1290
1320
 
1291
1321
  try:
1292
1322
  pilot.generate(...)
1323
+ except ContextExceededError as e:
1324
+ print(e.detail) # RagMapper가 top_k를 줄여가며 재시도했지만 끝내 실패한 경우
1293
1325
  except MappingError as e:
1294
1326
  print(e.detail) # 상세 오류 메시지
1295
1327
  except DocPilotError as e:
@@ -175,6 +175,14 @@ 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
+
182
+ def _t(temperature: float | None) -> dict:
183
+ return {"temperature": temperature} if temperature is not None else {}
184
+
185
+
178
186
  def _ingest_instructions_doc(path: Path) -> str:
179
187
  """지침 문서를 읽어 텍스트로 반환한다. 지원하지 않는 형식이면 빈 문자열 반환."""
180
188
  from docpilot.ingestion import text as text_ing
@@ -258,12 +266,6 @@ def _estimate_tokens_from_folder(folder: Path, n_sections: int) -> int:
258
266
  _DEFAULT_MAX_INPUT_TOKENS_WARN = 50_000
259
267
 
260
268
 
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
269
  def _resolve_instructions(
268
270
  extra_instructions: str | None,
269
271
  sidecar_instructions: str,
@@ -313,7 +315,8 @@ def _resolve_content(content: str | list[str | Path] | list[IngestedDocument]) -
313
315
  def _check_content_size(content_str: str, max_input_tokens: int | None) -> None:
314
316
  """Warn or raise on a rough byte-based token estimate — *_from_content() methods send
315
317
  content in full with no RAG top_k to bound its size automatically."""
316
- estimated_tokens = _estimate_tokens_raw(content_str)
318
+ from docpilot.tokens import estimate_tokens_raw
319
+ estimated_tokens = estimate_tokens_raw(content_str)
317
320
  if max_input_tokens is not None:
318
321
  if estimated_tokens > max_input_tokens:
319
322
  raise MappingError(
@@ -1022,17 +1025,33 @@ class DocPilot:
1022
1025
  api_key: str | None = None,
1023
1026
  model: str | None = None,
1024
1027
  base_url: str | None = None,
1028
+ num_ctx: int | None = None,
1029
+ temperature: float | None = None,
1025
1030
  database_url: str | None = None,
1026
1031
  embed_fn=None,
1027
1032
  use_reranker: bool = False,
1028
1033
  ) -> None:
1034
+ """
1035
+ num_ctx: Ollama-only — the context window (input+output token budget) the server
1036
+ loaded the model with. Ollama defaults to a small value (often 4096) regardless
1037
+ of what the model actually supports, and silently truncates prompts that exceed
1038
+ it rather than erroring — see README "Ollama 등 로컬 모델의 컨텍스트 한도". Pass the
1039
+ same value your Ollama server was started/configured with (check via `ollama ps`)
1040
+ so docpilot can (a) forward it as a per-request option and (b) reject oversized
1041
+ RAG/content prompts before sending them, instead of silently losing context.
1042
+ temperature: sampling temperature forwarded to whichever provider is active. None
1043
+ (default) leaves the provider/model's own default untouched. Lower it (e.g. 0)
1044
+ for more deterministic, structured output — useful since the JSON-mapping prompt
1045
+ can otherwise produce inconsistent results run to run (observed with local
1046
+ Ollama models especially; see llm_benchmark_report.md).
1047
+ """
1029
1048
  self._llm = llm or os.environ.get("DOCPILOT_LLM", "claude")
1030
1049
  self._api_key = api_key
1031
1050
  if embed_fn is None:
1032
1051
  from docpilot.search.embedding import default_embed_fn
1033
1052
  embed_fn = default_embed_fn() # None when sentence-transformers not installed
1034
1053
  self._embed_fn = embed_fn
1035
- base_mapper = self._build_mapper(self._llm, api_key, model, base_url)
1054
+ base_mapper = self._build_mapper(self._llm, api_key, model, base_url, num_ctx, temperature)
1036
1055
 
1037
1056
  from docpilot.mapping.rag import RagMapper
1038
1057
  self._mapper = base_mapper
@@ -1459,7 +1478,8 @@ class DocPilot:
1459
1478
  est_output = len(sections) * _EST_OUTPUT_TOKENS_PER_SECTION
1460
1479
 
1461
1480
  if quick:
1462
- input_tokens = _estimate_tokens_raw(content_str)
1481
+ from docpilot.tokens import estimate_tokens_raw
1482
+ input_tokens = estimate_tokens_raw(content_str)
1463
1483
  input_cost = input_tokens / 1_000_000 * in_price
1464
1484
  output_cost = est_output / 1_000_000 * out_price
1465
1485
  lines = [
@@ -1605,21 +1625,30 @@ class DocPilot:
1605
1625
  return suggest_extras(folder)
1606
1626
 
1607
1627
  @staticmethod
1608
- def _build_mapper(llm: str, api_key: str | None, model: str | None, base_url: str | None):
1628
+ def _build_mapper(
1629
+ llm: str,
1630
+ api_key: str | None,
1631
+ model: str | None,
1632
+ base_url: str | None,
1633
+ num_ctx: int | None = None,
1634
+ temperature: float | None = None,
1635
+ ):
1609
1636
  from docpilot.mapping import ClaudeMapper, OpenAIMapper, GeminiMapper
1610
1637
  from docpilot.mapping.openai_compat import GrokMapper, OllamaMapper
1611
1638
 
1612
1639
  match llm.lower():
1613
1640
  case "claude":
1614
- return ClaudeMapper(api_key=api_key, **(_m(model)))
1641
+ return ClaudeMapper(api_key=api_key, **(_m(model)), **(_t(temperature)))
1615
1642
  case "openai":
1616
- return OpenAIMapper(api_key=api_key, **(_m(model)))
1643
+ return OpenAIMapper(api_key=api_key, **(_m(model)), **(_t(temperature)))
1617
1644
  case "gemini":
1618
- return GeminiMapper(api_key=api_key, **(_m(model)))
1645
+ return GeminiMapper(api_key=api_key, **(_m(model)), **(_t(temperature)))
1619
1646
  case "grok":
1620
- return GrokMapper(api_key=api_key, **(_m(model)))
1647
+ return GrokMapper(api_key=api_key, **(_m(model)), **(_t(temperature)))
1621
1648
  case "ollama":
1622
- return OllamaMapper(**(_m(model)), **(_b(base_url)))
1649
+ return OllamaMapper(
1650
+ **(_m(model)), **(_b(base_url)), **(_n(num_ctx)), **(_t(temperature)),
1651
+ )
1623
1652
  case _:
1624
1653
  raise MappingError(
1625
1654
  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__)
@@ -18,9 +18,11 @@ class ClaudeMapper(BaseLLMMapper):
18
18
  api_key: str | None = None,
19
19
  model: str = DEFAULT_MODEL,
20
20
  max_tokens: int = 8096,
21
+ temperature: float | None = None,
21
22
  ) -> None:
22
23
  self._model = model
23
24
  self._max_tokens = max_tokens
25
+ self._temperature = temperature
24
26
  self._api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
25
27
  if not self._api_key:
26
28
  raise MappingError(
@@ -28,6 +30,9 @@ class ClaudeMapper(BaseLLMMapper):
28
30
  detail="Pass api_key or set ANTHROPIC_API_KEY env var",
29
31
  )
30
32
 
33
+ def _temp_kwargs(self) -> dict:
34
+ return {"temperature": self._temperature} if self._temperature is not None else {}
35
+
31
36
  def complete(self, prompt: str, max_tokens: int = 2048) -> str:
32
37
  try:
33
38
  import anthropic
@@ -39,6 +44,7 @@ class ClaudeMapper(BaseLLMMapper):
39
44
  model=self._model,
40
45
  max_tokens=max_tokens,
41
46
  messages=[{"role": "user", "content": prompt}],
47
+ **self._temp_kwargs(),
42
48
  )
43
49
  except Exception as e:
44
50
  raise MappingError("Claude API call failed", detail=str(e)) from e
@@ -59,8 +65,11 @@ class ClaudeMapper(BaseLLMMapper):
59
65
  model=self._model,
60
66
  max_tokens=self._max_tokens,
61
67
  messages=[{"role": "user", "content": prompt}],
68
+ **self._temp_kwargs(),
62
69
  )
63
70
  except Exception as e:
71
+ if is_context_overflow_error(str(e)):
72
+ raise ContextExceededError("Claude API가 컨텍스트 초과로 요청을 거부함", detail=str(e)) from e
64
73
  raise MappingError("Claude API call failed", detail=str(e)) from e
65
74
  elapsed = time.perf_counter() - start
66
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__)
@@ -18,9 +18,11 @@ class GeminiMapper(BaseLLMMapper):
18
18
  api_key: str | None = None,
19
19
  model: str = DEFAULT_MODEL,
20
20
  max_tokens: int = 8096,
21
+ temperature: float | None = None,
21
22
  ) -> None:
22
23
  self._model = model
23
24
  self._max_tokens = max_tokens
25
+ self._temperature = temperature
24
26
  self._api_key = api_key or os.environ.get("GEMINI_API_KEY")
25
27
  if not self._api_key:
26
28
  raise MappingError(
@@ -39,7 +41,9 @@ class GeminiMapper(BaseLLMMapper):
39
41
  response = client.models.generate_content(
40
42
  model=self._model,
41
43
  contents=prompt,
42
- config=types.GenerateContentConfig(max_output_tokens=max_tokens),
44
+ config=types.GenerateContentConfig(
45
+ max_output_tokens=max_tokens, temperature=self._temperature,
46
+ ),
43
47
  )
44
48
  except Exception as e:
45
49
  raise MappingError("Gemini API call failed", detail=str(e)) from e
@@ -65,9 +69,13 @@ class GeminiMapper(BaseLLMMapper):
65
69
  response = client.models.generate_content(
66
70
  model=self._model,
67
71
  contents=prompt,
68
- config=types.GenerateContentConfig(max_output_tokens=self._max_tokens),
72
+ config=types.GenerateContentConfig(
73
+ max_output_tokens=self._max_tokens, temperature=self._temperature,
74
+ ),
69
75
  )
70
76
  except Exception as e:
77
+ if is_context_overflow_error(str(e)):
78
+ raise ContextExceededError("Gemini API가 컨텍스트 초과로 요청을 거부함", detail=str(e)) from e
71
79
  raise MappingError("Gemini API call failed", detail=str(e)) from e
72
80
  elapsed = time.perf_counter() - start
73
81
 
@@ -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__)
@@ -18,9 +18,11 @@ class OpenAIMapper(BaseLLMMapper):
18
18
  api_key: str | None = None,
19
19
  model: str = DEFAULT_MODEL,
20
20
  max_tokens: int = 8096,
21
+ temperature: float | None = None,
21
22
  ) -> None:
22
23
  self._model = model
23
24
  self._max_tokens = max_tokens
25
+ self._temperature = temperature
24
26
  self._api_key = api_key or os.environ.get("OPENAI_API_KEY")
25
27
  if not self._api_key:
26
28
  raise MappingError(
@@ -28,6 +30,9 @@ class OpenAIMapper(BaseLLMMapper):
28
30
  detail="Pass api_key or set OPENAI_API_KEY env var",
29
31
  )
30
32
 
33
+ def _temp_kwargs(self) -> dict:
34
+ return {"temperature": self._temperature} if self._temperature is not None else {}
35
+
31
36
  def complete(self, prompt: str, max_tokens: int = 2048) -> str:
32
37
  try:
33
38
  from openai import OpenAI
@@ -39,6 +44,7 @@ class OpenAIMapper(BaseLLMMapper):
39
44
  model=self._model,
40
45
  max_tokens=max_tokens,
41
46
  messages=[{"role": "user", "content": prompt}],
47
+ **self._temp_kwargs(),
42
48
  )
43
49
  except Exception as e:
44
50
  raise MappingError("OpenAI API call failed", detail=str(e)) from e
@@ -64,8 +70,11 @@ class OpenAIMapper(BaseLLMMapper):
64
70
  model=self._model,
65
71
  max_tokens=self._max_tokens,
66
72
  messages=[{"role": "user", "content": prompt}],
73
+ **self._temp_kwargs(),
67
74
  )
68
75
  except Exception as e:
76
+ if is_context_overflow_error(str(e)):
77
+ raise ContextExceededError("OpenAI API가 컨텍스트 초과로 요청을 거부함", detail=str(e)) from e
69
78
  raise MappingError("OpenAI API call failed", detail=str(e)) from e
70
79
  elapsed = time.perf_counter() - start
71
80
 
@@ -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,65 @@ 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,
31
+ temperature: float | None = None,
28
32
  ) -> None:
29
33
  self._model = model
30
34
  self._base_url = base_url
31
35
  self._api_key = api_key
32
36
  self._max_tokens = max_tokens
37
+ self._num_ctx = num_ctx
38
+ self._timeout = timeout
39
+ self._temperature = temperature
40
+
41
+ def _temp_kwargs(self) -> dict:
42
+ return {"temperature": self._temperature} if self._temperature is not None else {}
43
+
44
+ def _extra_body(self) -> dict:
45
+ # Ollama-specific request option — openai SDK has no native num_ctx param, so it
46
+ # must be passed through extra_body's "options" dict (Ollama's own convention).
47
+ return {"options": {"num_ctx": self._num_ctx}} if self._num_ctx else {}
48
+
49
+ def _check_num_ctx(self, prompt: str, max_tokens: int) -> None:
50
+ """Reject prompts that won't fit num_ctx *before* sending — Ollama itself doesn't
51
+ error on this, it silently truncates the prompt from the front instead, which loses
52
+ RAG context with no signal in the response (see README "Ollama 등 로컬 모델의 컨텍스트
53
+ 한도"). Estimate only — no exact tokenizer available for Ollama models over the API."""
54
+ if self._num_ctx is None:
55
+ return
56
+ estimated = estimate_tokens_raw(prompt)
57
+ if estimated + max_tokens > self._num_ctx:
58
+ raise ContextExceededError(
59
+ f"예상 입력 토큰({estimated:,}) + max_tokens({max_tokens:,})이 "
60
+ f"num_ctx({self._num_ctx:,})를 초과합니다.",
61
+ detail=(
62
+ "이 상태로 보내면 Ollama가 프롬프트 앞부분을 조용히 잘라내거나 "
63
+ "응답이 중간에 끊길 수 있습니다. num_ctx를 늘리거나 top_k/컨텍스트 "
64
+ "크기를 줄이세요. (추정치는 바이트 기반 휴리스틱으로 ±30% 오차 가능)"
65
+ ),
66
+ )
33
67
 
34
68
  def complete(self, prompt: str, max_tokens: int = 2048) -> str:
35
69
  try:
36
70
  from openai import OpenAI
37
71
  except ImportError as e:
38
72
  raise MappingError("openai SDK required: pip install openai") from e
39
- client = OpenAI(api_key=self._api_key, base_url=self._base_url)
73
+ self._check_num_ctx(prompt, max_tokens)
74
+ client = OpenAI(api_key=self._api_key, base_url=self._base_url, timeout=self._timeout)
40
75
  try:
41
76
  response = client.chat.completions.create(
42
77
  model=self._model,
43
78
  max_tokens=max_tokens,
44
79
  messages=[{"role": "user", "content": prompt}],
80
+ extra_body=self._extra_body(),
81
+ **self._temp_kwargs(),
45
82
  )
46
83
  except Exception as e:
84
+ if is_context_overflow_error(str(e)):
85
+ raise ContextExceededError(
86
+ f"API가 컨텍스트 초과로 요청을 거부함 ({self._base_url})", detail=str(e)
87
+ ) from e
47
88
  raise MappingError(f"API call failed ({self._base_url})", detail=str(e)) from e
48
89
  return response.choices[0].message.content or ""
49
90
 
@@ -58,8 +99,9 @@ class OpenAICompatMapper(BaseLLMMapper):
58
99
  except ImportError as e:
59
100
  raise MappingError("openai SDK required: pip install openai") from e
60
101
 
61
- client = OpenAI(api_key=self._api_key, base_url=self._base_url)
102
+ client = OpenAI(api_key=self._api_key, base_url=self._base_url, timeout=self._timeout)
62
103
  prompt = self._build_prompt(self._resolve_content(content), sections, instructions)
104
+ self._check_num_ctx(prompt, self._max_tokens)
63
105
 
64
106
  start = time.perf_counter()
65
107
  try:
@@ -67,8 +109,14 @@ class OpenAICompatMapper(BaseLLMMapper):
67
109
  model=self._model,
68
110
  max_tokens=self._max_tokens,
69
111
  messages=[{"role": "user", "content": prompt}],
112
+ extra_body=self._extra_body(),
113
+ **self._temp_kwargs(),
70
114
  )
71
115
  except Exception as e:
116
+ if is_context_overflow_error(str(e)):
117
+ raise ContextExceededError(
118
+ f"API가 컨텍스트 초과로 요청을 거부함 ({self._base_url})", detail=str(e)
119
+ ) from e
72
120
  raise MappingError(
73
121
  f"API call failed ({self._base_url})", detail=str(e)
74
122
  ) from e
@@ -100,6 +148,7 @@ def GrokMapper(
100
148
  api_key: str | None = None,
101
149
  model: str = "grok-3",
102
150
  max_tokens: int = 8096,
151
+ temperature: float | None = None,
103
152
  ) -> OpenAICompatMapper:
104
153
  key = api_key or os.environ.get("XAI_API_KEY")
105
154
  if not key:
@@ -107,13 +156,28 @@ def GrokMapper(
107
156
  "Grok API key not provided",
108
157
  detail="Pass api_key or set XAI_API_KEY env var",
109
158
  )
110
- return OpenAICompatMapper(model=model, base_url=_GROK_BASE_URL, api_key=key, max_tokens=max_tokens)
159
+ return OpenAICompatMapper(
160
+ model=model, base_url=_GROK_BASE_URL, api_key=key, max_tokens=max_tokens,
161
+ temperature=temperature,
162
+ )
163
+
164
+
165
+ _OLLAMA_DEFAULT_TIMEOUT = 180.0 # seconds — Ollama has no explicit context-overflow error;
166
+ # a VRAM-starved request degrades to CPU offload instead of failing (20-50x slower, can look
167
+ # hung), so this is a starting-point safety net rather than a measured value. Pass timeout=
168
+ # to OllamaMapper()/OpenAICompatMapper() directly to tune for your hardware.
111
169
 
112
170
 
113
171
  def OllamaMapper(
114
172
  model: str = "llama3.2",
115
173
  base_url: str | None = None,
116
174
  max_tokens: int = 8096,
175
+ num_ctx: int | None = None,
176
+ timeout: float = _OLLAMA_DEFAULT_TIMEOUT,
177
+ temperature: float | None = None,
117
178
  ) -> OpenAICompatMapper:
118
179
  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)
180
+ return OpenAICompatMapper(
181
+ model=model, base_url=url, api_key="ollama", max_tokens=max_tokens,
182
+ num_ctx=num_ctx, timeout=timeout, temperature=temperature,
183
+ )