evalvault 1.62.1__py3-none-any.whl → 1.63.0__py3-none-any.whl

evalvault/adapters/inbound/cli/commands/run.py

@@ -20,7 +20,8 @@ from evalvault.adapters.outbound.documents.versioned_loader import (
     load_versioned_chunks_from_pdf_dir,
 )
 from evalvault.adapters.outbound.domain_memory.sqlite_adapter import SQLiteDomainMemoryAdapter
-from evalvault.adapters.outbound.llm import get_llm_adapter
+from evalvault.adapters.outbound.llm import SettingsLLMFactory, get_llm_adapter
+from evalvault.adapters.outbound.nlp.korean.toolkit_factory import try_create_korean_toolkit
 from evalvault.adapters.outbound.phoenix.sync_service import (
     PhoenixDatasetInfo,
     PhoenixSyncError,
@@ -39,6 +40,7 @@ from evalvault.domain.services.memory_based_analysis import MemoryBasedAnalysis
 from evalvault.domain.services.prompt_registry import (
     PromptInput,
     build_prompt_bundle,
+    build_prompt_inputs_from_snapshots,
     build_prompt_summary,
 )
 from evalvault.domain.services.ragas_prompt_overrides import (
@@ -808,6 +810,9 @@ def register_run_commands(
         if profile_name:
             settings = apply_profile(settings, profile_name)
 
+        if db_path is None:
+            db_path = Path(settings.evalvault_db_path)
+
         # Override model if specified
         if model:
             if _is_oss_open_model(model) and settings.llm_provider != "vllm":
@@ -1436,7 +1441,9 @@ def register_run_commands(
         if should_enable_phoenix:
             ensure_phoenix_instrumentation(settings, console=console, force=True)
 
-        evaluator = RagasEvaluator()
+        llm_factory = SettingsLLMFactory(settings)
+        korean_toolkit = try_create_korean_toolkit()
+        evaluator = RagasEvaluator(korean_toolkit=korean_toolkit, llm_factory=llm_factory)
         llm_adapter = None
         try:
             llm_adapter = get_llm_adapter(settings)
@@ -1707,6 +1714,40 @@ def register_run_commands(
             result.retrieval_metadata = merged_retriever_metadata
 
         result.tracker_metadata.setdefault("run_mode", preset.name)
+        tracker_meta = result.tracker_metadata or {}
+        result.tracker_metadata = tracker_meta
+        ragas_snapshots = tracker_meta.get("ragas_prompt_snapshots")
+        ragas_snapshot_inputs = build_prompt_inputs_from_snapshots(
+            ragas_snapshots if isinstance(ragas_snapshots, dict) else None,
+        )
+        override_status: dict[str, str] = {}
+        raw_override = tracker_meta.get("ragas_prompt_overrides")
+        if isinstance(raw_override, dict):
+            override_status = cast(dict[str, str], raw_override)
+        if override_status:
+            prompt_inputs = [
+                entry
+                for entry in prompt_inputs
+                if not (
+                    entry.kind == "ragas"
+                    and override_status.get(entry.role) is not None
+                    and override_status.get(entry.role) != "applied"
+                )
+            ]
+
+        if ragas_snapshot_inputs:
+            existing_roles = {entry.role for entry in prompt_inputs if entry.kind == "ragas"}
+            for entry in ragas_snapshot_inputs:
+                if entry.role in existing_roles and override_status.get(entry.role) == "applied":
+                    continue
+                prompt_inputs.append(entry)
+        if prompt_inputs and not db_path:
+            print_cli_warning(
+                console,
+                "Prompt snapshot은 --db 저장 시에만 DB에 기록됩니다.",
+                tips=["--db data/db/evalvault.db 옵션을 추가하세요."],
+            )
+
         if prompt_inputs:
             prompt_bundle = build_prompt_bundle(
                 run_id=result.run_id,

evalvault/adapters/inbound/cli/commands/run_helpers.py

@@ -443,6 +443,16 @@ def _save_to_db(
                     result.run_id,
                     prompt_bundle.prompt_set.prompt_set_id,
                 )
+            excel_path = db_path.parent / f"evalvault_run_{result.run_id}.xlsx"
+            try:
+                storage.export_run_to_excel(result.run_id, excel_path)
+                console.print(f"[green]Excel export saved: {excel_path}[/green]")
+            except Exception as exc:
+                print_cli_warning(
+                    console,
+                    "엑셀 내보내기에 실패했습니다.",
+                    tips=[str(exc)],
+                )
             console.print(f"[green]Results saved to database: {db_path}[/green]")
             console.print(f"[dim]Run ID: {result.run_id}[/dim]")
             if prompt_bundle:

evalvault/adapters/inbound/mcp/tools.py

@@ -18,7 +18,8 @@ from evalvault.adapters.inbound.cli.utils.analysis_io import (
 )
 from evalvault.adapters.outbound.analysis.pipeline_factory import build_analysis_pipeline_service
 from evalvault.adapters.outbound.analysis.statistical_adapter import StatisticalAnalysisAdapter
-from evalvault.adapters.outbound.llm import get_llm_adapter
+from evalvault.adapters.outbound.llm import SettingsLLMFactory, get_llm_adapter
+from evalvault.adapters.outbound.nlp.korean.toolkit_factory import try_create_korean_toolkit
 from evalvault.adapters.outbound.storage.sqlite_adapter import SQLiteStorageAdapter
 from evalvault.config.settings import Settings, apply_profile
 from evalvault.domain.entities.analysis_pipeline import AnalysisIntent
@@ -175,7 +176,9 @@ def run_evaluation(payload: dict[str, Any] | RunEvaluationRequest) -> RunEvaluat
         )
 
     storage = SQLiteStorageAdapter(db_path=db_path)
-    evaluator = RagasEvaluator()
+    llm_factory = SettingsLLMFactory(settings)
+    korean_toolkit = try_create_korean_toolkit()
+    evaluator = RagasEvaluator(korean_toolkit=korean_toolkit, llm_factory=llm_factory)
     adapter = WebUIAdapter(
         storage=storage,
         evaluator=evaluator,

evalvault/adapters/outbound/analysis/ragas_evaluator_module.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, cast
 
 from evalvault.adapters.outbound.analysis.base_module import BaseAnalysisModule
 from evalvault.adapters.outbound.analysis.pipeline_helpers import (
@@ -12,6 +12,9 @@ from evalvault.adapters.outbound.analysis.pipeline_helpers import (
     safe_mean,
     truncate_text,
 )
+from evalvault.adapters.outbound.llm import SettingsLLMFactory
+from evalvault.adapters.outbound.nlp.korean.toolkit_factory import try_create_korean_toolkit
+from evalvault.config.settings import Settings
 from evalvault.domain.entities import Dataset, EvaluationRun, TestCase
 from evalvault.domain.services.evaluator import RagasEvaluator
 from evalvault.ports.outbound.llm_port import LLMPort
@@ -30,7 +33,10 @@ class RagasEvaluatorModule(BaseAnalysisModule):
 
     def __init__(self, llm_adapter: LLMPort | None = None) -> None:
         self._llm_adapter = llm_adapter
-        self._evaluator = RagasEvaluator()
+        settings = Settings()
+        llm_factory = SettingsLLMFactory(settings)
+        korean_toolkit = try_create_korean_toolkit()
+        self._evaluator = RagasEvaluator(korean_toolkit=korean_toolkit, llm_factory=llm_factory)
 
     def execute(
         self,
@@ -143,14 +149,12 @@ class RagasEvaluatorModule(BaseAnalysisModule):
         *,
         recomputed: bool,
     ) -> dict[str, Any]:
-        if metrics and isinstance(next(iter(metrics.values())), list):
-            avg_scores = average_scores(metrics)  # type: ignore[arg-type]
-            sample_count = max(
-                (len(values) for values in metrics.values()),
-                default=0,
-            )  # type: ignore[arg-type]
+        if metrics and all(isinstance(value, list) for value in metrics.values()):
+            metrics_lists = cast(dict[str, list[float]], metrics)
+            avg_scores = average_scores(metrics_lists)
+            sample_count = max((len(values) for values in metrics_lists.values()), default=0)
         else:
-            avg_scores = metrics  # type: ignore[assignment]
+            avg_scores = cast(dict[str, float], metrics)
             sample_count = len(per_case)
 
         overall = safe_mean(avg_scores.values()) if avg_scores else 0.0

evalvault/adapters/outbound/llm/__init__.py

@@ -8,6 +8,10 @@ from evalvault.adapters.outbound.llm.base import (
     LLMConfigurationError,
     create_openai_embeddings_with_legacy,
 )
+from evalvault.adapters.outbound.llm.factory import (
+    SettingsLLMFactory,
+    create_llm_adapter_for_model,
+)
 from evalvault.adapters.outbound.llm.llm_relation_augmenter import LLMRelationAugmenter
 from evalvault.config.settings import Settings
 from evalvault.ports.outbound.llm_port import LLMPort
@@ -70,49 +74,6 @@ def get_llm_adapter(settings: Settings) -> LLMPort:
     )
 
 
-def create_llm_adapter_for_model(
-    provider: str,
-    model_name: str,
-    base_settings: Settings,
-) -> LLMPort:
-    provider = provider.lower()
-
-    if provider == "openai":
-        base_settings.llm_provider = "openai"
-        base_settings.openai_model = model_name
-        from evalvault.adapters.outbound.llm.openai_adapter import OpenAIAdapter
-
-        return OpenAIAdapter(base_settings)
-    if provider == "ollama":
-        base_settings.llm_provider = "ollama"
-        base_settings.ollama_model = model_name
-        from evalvault.adapters.outbound.llm.ollama_adapter import OllamaAdapter
-
-        return OllamaAdapter(base_settings)
-    if provider == "vllm":
-        base_settings.llm_provider = "vllm"
-        base_settings.vllm_model = model_name
-        from evalvault.adapters.outbound.llm.vllm_adapter import VLLMAdapter
-
-        return VLLMAdapter(base_settings)
-    if provider == "azure":
-        base_settings.llm_provider = "azure"
-        base_settings.azure_deployment = model_name
-        from evalvault.adapters.outbound.llm.azure_adapter import AzureOpenAIAdapter
-
-        return AzureOpenAIAdapter(base_settings)
-    if provider == "anthropic":
-        base_settings.llm_provider = "anthropic"
-        base_settings.anthropic_model = model_name
-        from evalvault.adapters.outbound.llm.anthropic_adapter import AnthropicAdapter
-
-        return AnthropicAdapter(base_settings)
-
-    raise ValueError(
-        f"Unsupported LLM provider: '{provider}'. Supported: openai, ollama, vllm, azure, anthropic"
-    )
-
-
 __all__ = [
     "BaseLLMAdapter",
     "LLMConfigurationError",
@@ -123,6 +84,7 @@ __all__ = [
     "LLMRelationAugmenter",
     "OllamaAdapter",
     "VLLMAdapter",
+    "SettingsLLMFactory",
     "get_llm_adapter",
     "create_llm_adapter_for_model",
 ]

evalvault/adapters/outbound/llm/anthropic_adapter.py

@@ -14,7 +14,7 @@ from evalvault.adapters.outbound.llm.base import (
 from evalvault.adapters.outbound.llm.instructor_factory import create_instructor_llm
 from evalvault.config.phoenix_support import instrumentation_span, set_span_attributes
 from evalvault.config.settings import Settings
-from evalvault.ports.outbound.llm_port import ThinkingConfig
+from evalvault.ports.outbound.llm_port import GenerationOptions, ThinkingConfig
 
 try:  # Optional dependency
     from anthropic import AsyncAnthropic
@@ -147,7 +147,12 @@ class AnthropicAdapter(BaseLLMAdapter):
         """Get the extended thinking token budget."""
         return self._thinking_budget
 
-    async def agenerate_text(self, prompt: str) -> str:
+    async def agenerate_text(
+        self,
+        prompt: str,
+        *,
+        options: GenerationOptions | None = None,
+    ) -> str:
         """Generate text from a prompt (async).
 
         Uses the Anthropic messages API for simple text generation.
@@ -158,10 +163,17 @@ class AnthropicAdapter(BaseLLMAdapter):
         Returns:
             Generated text string
         """
+        max_tokens = options.max_tokens if options and options.max_tokens is not None else 8192
+        api_kwargs: dict[str, Any] = {}
+        if options and options.temperature is not None:
+            api_kwargs["temperature"] = options.temperature
+        if options and options.top_p is not None:
+            api_kwargs["top_p"] = options.top_p
         response = await self._anthropic_client.messages.create(
             model=self._model_name,
-            max_tokens=8192,
+            max_tokens=max_tokens,
             messages=[{"role": "user", "content": prompt}],
+            **api_kwargs,
         )
         # Extract text from response content blocks
         text_parts = []
@@ -170,7 +182,13 @@ class AnthropicAdapter(BaseLLMAdapter):
                 text_parts.append(block.text)
         return "".join(text_parts)
 
-    def generate_text(self, prompt: str, *, json_mode: bool = False) -> str:
+    def generate_text(
+        self,
+        prompt: str,
+        *,
+        json_mode: bool = False,
+        options: GenerationOptions | None = None,
+    ) -> str:
         """Generate text from a prompt (sync).
 
         Args:
@@ -192,12 +210,14 @@ class AnthropicAdapter(BaseLLMAdapter):
                 import nest_asyncio
 
                 nest_asyncio.apply()
-                return loop.run_until_complete(self.agenerate_text(prompt))
+                return loop.run_until_complete(self.agenerate_text(prompt, options=options))
             except ImportError:
                 import concurrent.futures
 
                 with concurrent.futures.ThreadPoolExecutor() as executor:
-                    future = executor.submit(asyncio.run, self.agenerate_text(prompt))
+                    future = executor.submit(
+                        asyncio.run, self.agenerate_text(prompt, options=options)
+                    )
                     return future.result()
         else:
-            return asyncio.run(self.agenerate_text(prompt))
+            return asyncio.run(self.agenerate_text(prompt, options=options))

evalvault/adapters/outbound/llm/factory.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from evalvault.config.settings import Settings
+from evalvault.ports.outbound.llm_factory_port import LLMFactoryPort
+from evalvault.ports.outbound.llm_port import LLMPort
+
+
+class SettingsLLMFactory(LLMFactoryPort):
+    def __init__(self, settings: Settings) -> None:
+        self._settings = settings
+
+    def create_faithfulness_fallback(
+        self,
+        active_provider: str | None,
+        active_model: str | None,
+    ) -> LLMPort | None:
+        provider, model = _resolve_faithfulness_fallback_config(
+            settings=self._settings,
+            active_provider=active_provider,
+            active_model=active_model,
+        )
+        if not provider or not model:
+            return None
+        return create_llm_adapter_for_model(provider, model, self._settings)
+
+
+def create_llm_adapter_for_model(
+    provider: str,
+    model_name: str,
+    base_settings: Settings,
+) -> LLMPort:
+    provider = provider.lower()
+
+    if provider == "openai":
+        base_settings.llm_provider = "openai"
+        base_settings.openai_model = model_name
+        from evalvault.adapters.outbound.llm.openai_adapter import OpenAIAdapter
+
+        return OpenAIAdapter(base_settings)
+    if provider == "ollama":
+        base_settings.llm_provider = "ollama"
+        base_settings.ollama_model = model_name
+        from evalvault.adapters.outbound.llm.ollama_adapter import OllamaAdapter
+
+        return OllamaAdapter(base_settings)
+    if provider == "vllm":
+        base_settings.llm_provider = "vllm"
+        base_settings.vllm_model = model_name
+        from evalvault.adapters.outbound.llm.vllm_adapter import VLLMAdapter
+
+        return VLLMAdapter(base_settings)
+    if provider == "azure":
+        base_settings.llm_provider = "azure"
+        base_settings.azure_deployment = model_name
+        from evalvault.adapters.outbound.llm.azure_adapter import AzureOpenAIAdapter
+
+        return AzureOpenAIAdapter(base_settings)
+    if provider == "anthropic":
+        base_settings.llm_provider = "anthropic"
+        base_settings.anthropic_model = model_name
+        from evalvault.adapters.outbound.llm.anthropic_adapter import AnthropicAdapter
+
+        return AnthropicAdapter(base_settings)
+
+    raise ValueError(
+        f"Unsupported LLM provider: '{provider}'. Supported: openai, ollama, vllm, azure, anthropic"
+    )
+
+
+def _resolve_faithfulness_fallback_config(
+    *,
+    settings: Settings,
+    active_provider: str | None,
+    active_model: str | None,
+) -> tuple[str | None, str | None]:
+    provider = (
+        settings.faithfulness_fallback_provider.strip().lower()
+        if settings.faithfulness_fallback_provider
+        else None
+    )
+    model = settings.faithfulness_fallback_model
+    normalized_active = active_provider.strip().lower() if active_provider else None
+    default_provider = normalized_active or settings.llm_provider.lower()
+
+    if not provider and model:
+        provider = default_provider
+    if provider and not model:
+        model = _default_faithfulness_fallback_model(provider)
+    if not provider and not model:
+        provider = default_provider
+        model = _default_faithfulness_fallback_model(default_provider)
+
+    if not provider or not model:
+        return None, None
+    return provider, model
+
+
+def _default_faithfulness_fallback_model(provider: str) -> str | None:
+    if provider == "ollama":
+        return "gpt-oss-safeguard:20b"
+    if provider == "vllm":
+        return "gpt-oss-120b"
+    return None

evalvault/adapters/outbound/llm/llm_relation_augmenter.py

@@ -9,6 +9,29 @@ from evalvault.domain.services.entity_extractor import Entity, Relation
 from evalvault.ports.outbound.llm_port import LLMPort
 from evalvault.ports.outbound.relation_augmenter_port import RelationAugmenterPort
 
+_RELATION_SYSTEM_PROMPT_KO = (
+    "당신은 한국어 보험 문서의 지식 그래프 감사자입니다. "
+    "제공된 문서 스니펫을 보고 관계를 확인하거나 수정하세요."
+)
+_RELATION_SYSTEM_PROMPT_EN = (
+    "You are a knowledge graph auditor for Korean insurance documents. "
+    "Review the provided document snippet and confirm or fix the relations."
+)
+_RELATION_PROMPT_TEMPLATE_KO = (
+    "{system_prompt}\n"
+    "source, target, relation_type, confidence, justification 키를 포함한 JSON 배열만 반환하세요.\n\n"
+    "문서:\n{document_text}\n\n"
+    "엔티티:\n{entity_lines}\n\n"
+    "낮은 신뢰도 관계:\n{relation_lines}"
+)
+_RELATION_PROMPT_TEMPLATE_EN = (
+    "{system_prompt}\n"
+    "Return a JSON array of objects with keys source, target, relation_type, confidence, justification.\n\n"
+    "Document:\n{document_text}\n\n"
+    "Entities:\n{entity_lines}\n\n"
+    "Low-confidence relations:\n{relation_lines}"
+)
+
 
 class LLMRelationAugmenter(RelationAugmenterPort):
     """LLM을 사용해 저신뢰 관계를 검증/보강."""
@@ -18,13 +41,17 @@ class LLMRelationAugmenter(RelationAugmenterPort):
         llm_port: LLMPort,
         max_relations: int = 5,
         system_prompt: str | None = None,
+        language: str = "ko",
     ):
         self._llm_port = llm_port
         self._max_relations = max_relations
-        self._system_prompt = system_prompt or (
-            "You are a knowledge graph auditor for Korean insurance documents. "
-            "Review the provided document snippet and confirm or fix the relations."
-        )
+        self._language = language
+        if system_prompt:
+            self._system_prompt = system_prompt
+        else:
+            self._system_prompt = (
+                _RELATION_SYSTEM_PROMPT_EN if language == "en" else _RELATION_SYSTEM_PROMPT_KO
+            )
 
     def augment_relations(
         self,
@@ -75,16 +102,14 @@ class LLMRelationAugmenter(RelationAugmenterPort):
             f"- {rel.source} -> {rel.target} [{rel.relation_type}] conf={rel.confidence:.2f}"
             for rel in relations
         ]
-        return (
-            f"{self._system_prompt}\n"
-            "Return a JSON array of objects with keys "
-            "source, target, relation_type, confidence, justification.\n\n"
-            "Document:\n"
-            f"{document_text}\n\n"
-            "Entities:\n"
-            f"{chr(10).join(entity_lines)}\n\n"
-            "Low-confidence relations:\n"
-            f"{chr(10).join(relation_lines)}"
+        template = (
+            _RELATION_PROMPT_TEMPLATE_EN if self._language == "en" else _RELATION_PROMPT_TEMPLATE_KO
+        )
+        return template.format(
+            system_prompt=self._system_prompt,
+            document_text=document_text,
+            entity_lines=chr(10).join(entity_lines),
+            relation_lines=chr(10).join(relation_lines),
         )
 
     @staticmethod

evalvault/adapters/outbound/llm/ollama_adapter.py

@@ -19,7 +19,7 @@ from evalvault.adapters.outbound.llm.base import BaseLLMAdapter
 from evalvault.adapters.outbound.llm.instructor_factory import create_instructor_llm
 from evalvault.adapters.outbound.llm.token_aware_chat import ThinkingTokenTrackingAsyncOpenAI
 from evalvault.config.settings import Settings
-from evalvault.ports.outbound.llm_port import ThinkingConfig
+from evalvault.ports.outbound.llm_port import GenerationOptions, ThinkingConfig
 
 
 class OllamaAdapter(BaseLLMAdapter):
@@ -240,7 +240,12 @@ class OllamaAdapter(BaseLLMAdapter):
         else:
             return asyncio.run(self.embed(texts, model, dimension))
 
-    async def agenerate_text(self, prompt: str) -> str:
+    async def agenerate_text(
+        self,
+        prompt: str,
+        *,
+        options: GenerationOptions | None = None,
+    ) -> str:
         """Generate text from a prompt (async).
 
         Uses the Ollama OpenAI-compatible API for simple text generation.
@@ -251,13 +256,30 @@ class OllamaAdapter(BaseLLMAdapter):
         Returns:
             Generated text string
         """
-        response = await self._embedding_client.chat.completions.create(
-            model=self._ollama_model,
-            messages=[{"role": "user", "content": prompt}],
-        )
+        api_kwargs: dict[str, Any] = {
+            "model": self._ollama_model,
+            "messages": [{"role": "user", "content": prompt}],
+        }
+        if options and options.max_tokens is not None:
+            api_kwargs["max_completion_tokens"] = options.max_tokens
+        if options and options.temperature is not None:
+            api_kwargs["temperature"] = options.temperature
+        if options and options.top_p is not None:
+            api_kwargs["top_p"] = options.top_p
+        if options and options.n is not None:
+            api_kwargs["n"] = options.n
+        if options and options.seed is not None:
+            api_kwargs["seed"] = options.seed
+        response = await self._embedding_client.chat.completions.create(**api_kwargs)
         return response.choices[0].message.content or ""
 
-    def generate_text(self, prompt: str, *, json_mode: bool = False) -> str:
+    def generate_text(
+        self,
+        prompt: str,
+        *,
+        json_mode: bool = False,
+        options: GenerationOptions | None = None,
+    ) -> str:
         """Generate text from a prompt (sync).
 
         Args:
@@ -279,12 +301,14 @@ class OllamaAdapter(BaseLLMAdapter):
                 import nest_asyncio
 
                 nest_asyncio.apply()
-                return loop.run_until_complete(self.agenerate_text(prompt))
+                return loop.run_until_complete(self.agenerate_text(prompt, options=options))
             except ImportError:
                 import concurrent.futures
 
                 with concurrent.futures.ThreadPoolExecutor() as executor:
-                    future = executor.submit(asyncio.run, self.agenerate_text(prompt))
+                    future = executor.submit(
+                        asyncio.run, self.agenerate_text(prompt, options=options)
+                    )
                     return future.result()
         else:
-            return asyncio.run(self.agenerate_text(prompt))
+            return asyncio.run(self.agenerate_text(prompt, options=options))

evalvault/adapters/outbound/llm/openai_adapter.py

@@ -10,6 +10,7 @@ from evalvault.adapters.outbound.llm.instructor_factory import create_instructor
 from evalvault.adapters.outbound.llm.token_aware_chat import TokenTrackingAsyncOpenAI
 from evalvault.config.phoenix_support import instrumentation_span, set_span_attributes
 from evalvault.config.settings import Settings
+from evalvault.ports.outbound.llm_port import GenerationOptions
 
 _DEFAULT_MAX_COMPLETION_TOKENS = 8192
 _GPT5_MAX_COMPLETION_TOKENS = 16384
@@ -73,7 +74,12 @@ class OpenAIAdapter(BaseLLMAdapter):
         """
         return self._embedding_model_name
 
-    async def agenerate_text(self, prompt: str) -> str:
+    async def agenerate_text(
+        self,
+        prompt: str,
+        *,
+        options: GenerationOptions | None = None,
+    ) -> str:
         """Generate text from a prompt (async).
 
         Uses the OpenAI chat completions API directly for simple text generation.
@@ -89,18 +95,35 @@ class OpenAIAdapter(BaseLLMAdapter):
             "llm.model": self._model_name,
             "llm.mode": "async",
         }
+        max_tokens = options.max_tokens if options and options.max_tokens is not None else None
+        api_kwargs = {
+            "model": self._model_name,
+            "messages": [{"role": "user", "content": prompt}],
+            "max_completion_tokens": max_tokens
+            or _max_completion_tokens_for_model(self._model_name),
+        }
+        if options and options.temperature is not None:
+            api_kwargs["temperature"] = options.temperature
+        if options and options.top_p is not None:
+            api_kwargs["top_p"] = options.top_p
+        if options and options.n is not None:
+            api_kwargs["n"] = options.n
+        if options and options.seed is not None:
+            api_kwargs["seed"] = options.seed
         with instrumentation_span("llm.generate_text", attrs) as span:
-            response = await self._client.chat.completions.create(
-                model=self._model_name,
-                messages=[{"role": "user", "content": prompt}],
-                max_completion_tokens=_max_completion_tokens_for_model(self._model_name),
-            )
+            response = await self._client.chat.completions.create(**api_kwargs)
             content = response.choices[0].message.content or ""
             if span:
                 set_span_attributes(span, {"llm.response.length": len(content)})
         return content
 
-    def generate_text(self, prompt: str, *, json_mode: bool = False) -> str:
+    def generate_text(
+        self,
+        prompt: str,
+        *,
+        json_mode: bool = False,
+        options: GenerationOptions | None = None,
+    ) -> str:
         """Generate text from a prompt (sync).
 
         Uses sync OpenAI client directly.
@@ -124,11 +147,21 @@ class OpenAIAdapter(BaseLLMAdapter):
         sync_client = OpenAI(**client_kwargs)
 
         # API 호출 파라미터
+        max_tokens = options.max_tokens if options and options.max_tokens is not None else None
         api_kwargs: dict = {
             "model": self._model_name,
             "messages": [{"role": "user", "content": prompt}],
-            "max_completion_tokens": _max_completion_tokens_for_model(self._model_name),
+            "max_completion_tokens": max_tokens
+            or _max_completion_tokens_for_model(self._model_name),
         }
+        if options and options.temperature is not None:
+            api_kwargs["temperature"] = options.temperature
+        if options and options.top_p is not None:
+            api_kwargs["top_p"] = options.top_p
+        if options and options.n is not None:
+            api_kwargs["n"] = options.n
+        if options and options.seed is not None:
+            api_kwargs["seed"] = options.seed
 
         # JSON 모드 설정
         if json_mode: