codeboarding 0.9.0__py3-none-any.whl

agents/dependency_discovery.py

@@ -0,0 +1,159 @@
+import logging
+from collections.abc import Set as AbstractSet
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+from repo_utils.ignore import RepoIgnoreManager
+
+logger = logging.getLogger(__name__)
+
+
+class Ecosystem(StrEnum):
+    PYTHON = "python"
+    NODE = "node"
+    GO = "go"
+    JAVA = "java"
+    PHP = "php"
+
+
+class FileRole(StrEnum):
+    MANIFEST = "manifest"
+    LOCK = "lock"
+    CONFIG = "config"
+
+
+@dataclass(frozen=True, slots=True)
+class DependencyFileSpec:
+    filename: str
+    ecosystem: Ecosystem
+    role: FileRole
+
+
+DEPENDENCY_REGISTRY: tuple[DependencyFileSpec, ...] = (
+    # ── Python ──
+    DependencyFileSpec("requirements.txt", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("requirements-dev.txt", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("requirements-test.txt", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("dev-requirements.txt", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("test-requirements.txt", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("setup.py", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("setup.cfg", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("Pipfile", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("Pipfile.lock", Ecosystem.PYTHON, FileRole.LOCK),
+    DependencyFileSpec("pyproject.toml", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("poetry.lock", Ecosystem.PYTHON, FileRole.LOCK),
+    DependencyFileSpec("pdm.lock", Ecosystem.PYTHON, FileRole.LOCK),
+    DependencyFileSpec("uv.lock", Ecosystem.PYTHON, FileRole.LOCK),
+    DependencyFileSpec("environment.yml", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("environment.yaml", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("conda.yml", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("conda.yaml", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("pixi.toml", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("requirements.in", Ecosystem.PYTHON, FileRole.MANIFEST),
+    DependencyFileSpec("pixi.lock", Ecosystem.PYTHON, FileRole.LOCK),
+    # ── Node / TypeScript / JavaScript ──
+    DependencyFileSpec("package.json", Ecosystem.NODE, FileRole.MANIFEST),
+    DependencyFileSpec("package-lock.json", Ecosystem.NODE, FileRole.LOCK),
+    DependencyFileSpec("yarn.lock", Ecosystem.NODE, FileRole.LOCK),
+    DependencyFileSpec("pnpm-lock.yaml", Ecosystem.NODE, FileRole.LOCK),
+    DependencyFileSpec("bun.lockb", Ecosystem.NODE, FileRole.LOCK),
+    DependencyFileSpec("tsconfig.json", Ecosystem.NODE, FileRole.CONFIG),
+    DependencyFileSpec("jsconfig.json", Ecosystem.NODE, FileRole.CONFIG),
+    DependencyFileSpec("bun.lock", Ecosystem.NODE, FileRole.LOCK),
+    DependencyFileSpec("deno.json", Ecosystem.NODE, FileRole.MANIFEST),
+    DependencyFileSpec("deno.jsonc", Ecosystem.NODE, FileRole.MANIFEST),
+    DependencyFileSpec("deno.lock", Ecosystem.NODE, FileRole.LOCK),
+    DependencyFileSpec("lerna.json", Ecosystem.NODE, FileRole.CONFIG),
+    # ── Go ──
+    DependencyFileSpec("go.mod", Ecosystem.GO, FileRole.MANIFEST),
+    DependencyFileSpec("go.sum", Ecosystem.GO, FileRole.LOCK),
+    DependencyFileSpec("go.work", Ecosystem.GO, FileRole.CONFIG),
+    DependencyFileSpec("go.work.sum", Ecosystem.GO, FileRole.LOCK),
+    # ── Java / JVM ──
+    DependencyFileSpec("pom.xml", Ecosystem.JAVA, FileRole.MANIFEST),
+    DependencyFileSpec("pom.properties", Ecosystem.JAVA, FileRole.CONFIG),
+    DependencyFileSpec("build.gradle", Ecosystem.JAVA, FileRole.MANIFEST),
+    DependencyFileSpec("build.gradle.kts", Ecosystem.JAVA, FileRole.MANIFEST),
+    DependencyFileSpec("settings.gradle", Ecosystem.JAVA, FileRole.CONFIG),
+    DependencyFileSpec("settings.gradle.kts", Ecosystem.JAVA, FileRole.CONFIG),
+    DependencyFileSpec("gradle.properties", Ecosystem.JAVA, FileRole.CONFIG),
+    DependencyFileSpec("build.sbt", Ecosystem.JAVA, FileRole.MANIFEST),
+    DependencyFileSpec("gradle.lockfile", Ecosystem.JAVA, FileRole.LOCK),
+    DependencyFileSpec("verification-metadata.xml", Ecosystem.JAVA, FileRole.LOCK),
+    # ── PHP ──
+    DependencyFileSpec("composer.json", Ecosystem.PHP, FileRole.MANIFEST),
+    DependencyFileSpec("composer.lock", Ecosystem.PHP, FileRole.LOCK),
+    DependencyFileSpec("symfony.lock", Ecosystem.PHP, FileRole.LOCK),
+    DependencyFileSpec("phive.xml", Ecosystem.PHP, FileRole.MANIFEST),
+    DependencyFileSpec("package.xml", Ecosystem.PHP, FileRole.MANIFEST),
+)
+
+DEPENDENCY_FILES: tuple[str, ...] = tuple(spec.filename for spec in DEPENDENCY_REGISTRY)
+
+_FILENAME_TO_SPEC: dict[str, DependencyFileSpec] = {spec.filename: spec for spec in DEPENDENCY_REGISTRY}
+
+
+@dataclass
+class DiscoveredDependencyFile:
+    path: Path
+    spec: DependencyFileSpec
+
+
+def discover_dependency_files(
+    repo_dir: Path,
+    ignore_manager: RepoIgnoreManager,
+    *,
+    max_depth: int = 3,
+    roles: AbstractSet[FileRole] | None = None,
+    ecosystems: AbstractSet[Ecosystem] | None = None,
+) -> list[DiscoveredDependencyFile]:
+    """Discover dependency files with full ecosystem / role metadata.
+
+    Walks the repository tree up to *max_depth* directories deep,
+    matching filenames against the known dependency registry in O(1)
+    per file.  The *ignore_manager* prunes entire subtrees early.
+
+    Args:
+        repo_dir: Repository root.
+        ignore_manager: Ignore-rule evaluator (gitignore, codeboardingignore).
+        max_depth: Maximum directory depth to descend (0 = root only).
+        roles: If given, only return files whose role is in this set.
+        ecosystems: If given, only return files whose ecosystem is in this set.
+    """
+    found: list[DiscoveredDependencyFile] = []
+    seen: set[Path] = set()
+
+    def _walk(directory: Path, depth: int) -> None:
+        if depth > max_depth:
+            return
+        if directory != repo_dir and ignore_manager.should_ignore(directory):
+            return
+        try:
+            entries = sorted(directory.iterdir())
+        except PermissionError:
+            return
+
+        for entry in entries:
+            if entry.is_file():
+                spec = _FILENAME_TO_SPEC.get(entry.name)
+                if spec is None:
+                    continue
+                if roles and spec.role not in roles:
+                    continue
+                if ecosystems and spec.ecosystem not in ecosystems:
+                    continue
+                if not ignore_manager.should_ignore(entry) and entry not in seen:
+                    found.append(DiscoveredDependencyFile(path=entry, spec=spec))
+                    seen.add(entry)
+            elif entry.is_dir() and depth < max_depth:
+                _walk(entry, depth + 1)
+
+    _walk(repo_dir, 0)
+
+    logger.debug(
+        "[Dependency Discovery] Found %d dependency files: %s",
+        len(found),
+        ", ".join(d.path.relative_to(repo_dir).as_posix() for d in found),
+    )
+    return found

agents/details_agent.py

@@ -0,0 +1,174 @@
+import logging
+from pathlib import Path
+
+from langchain_core.prompts import PromptTemplate
+from langchain_core.language_models import BaseChatModel
+
+from agents.agent import CodeBoardingAgent
+from agents.agent_responses import (
+    AnalysisInsights,
+    ClusterAnalysis,
+    Component,
+    MetaAnalysisInsights,
+    assign_component_ids,
+)
+from agents.prompts import get_system_details_message, get_cfg_details_message, get_details_message
+from agents.cluster_methods_mixin import ClusterMethodsMixin
+from agents.validation import (
+    ValidationContext,
+    validate_cluster_coverage,
+    validate_component_relationships,
+    validate_key_entities,
+    validate_relation_component_names,
+)
+from monitoring import trace
+from static_analyzer.analysis_result import StaticAnalysisResults
+from static_analyzer.cluster_helpers import get_all_cluster_ids
+
+logger = logging.getLogger(__name__)
+
+
+class DetailsAgent(ClusterMethodsMixin, CodeBoardingAgent):
+    def __init__(
+        self,
+        repo_dir: Path,
+        static_analysis: StaticAnalysisResults,
+        project_name: str,
+        meta_context: MetaAnalysisInsights,
+        agent_llm: BaseChatModel,
+        parsing_llm: BaseChatModel,
+    ):
+        super().__init__(repo_dir, static_analysis, get_system_details_message(), agent_llm, parsing_llm)
+        self.project_name = project_name
+        self.meta_context = meta_context
+
+        self.prompts = {
+            "group_clusters": PromptTemplate(
+                template=get_cfg_details_message(),
+                input_variables=["project_name", "cfg_str", "component", "meta_context", "project_type"],
+            ),
+            "final_analysis": PromptTemplate(
+                template=get_details_message(),
+                input_variables=["insight_so_far", "component", "meta_context", "project_type"],
+            ),
+        }
+
+    @trace
+    def step_cluster_grouping(
+        self, component: Component, subgraph_cluster_str: str, subgraph_cluster_results: dict
+    ) -> ClusterAnalysis:
+        """
+        Group clusters within the component's subgraph into logical sub-components.
+
+        Args:
+            component: The component being analyzed
+            subgraph_cluster_str: String representation of the component's CFG subgraph
+            subgraph_cluster_results: Cluster results for the subgraph (from _create_strict_component_subgraph)
+
+        Returns:
+            ClusterAnalysis with grouped clusters for this component
+        """
+        logger.info(f"[DetailsAgent] Grouping clusters for component: {component.name}")
+        meta_context_str = self.meta_context.llm_str() if self.meta_context else "No project context available."
+        project_type = self.meta_context.project_type if self.meta_context else "unknown"
+
+        prompt = self.prompts["group_clusters"].format(
+            project_name=self.project_name,
+            cfg_str=subgraph_cluster_str,
+            component=component.llm_str(),
+            meta_context=meta_context_str,
+            project_type=project_type,
+        )
+
+        # Build validation context using subgraph cluster results
+        context = ValidationContext(
+            cluster_results=subgraph_cluster_results,
+            expected_cluster_ids=get_all_cluster_ids(subgraph_cluster_results),
+        )
+
+        cluster_analysis = self._validation_invoke(
+            prompt, ClusterAnalysis, validators=[validate_cluster_coverage], context=context
+        )
+        return cluster_analysis
+
+    @trace
+    def step_final_analysis(
+        self, component: Component, cluster_analysis: ClusterAnalysis, subgraph_cluster_results: dict
+    ) -> AnalysisInsights:
+        """
+        Generate detailed final analysis from grouped clusters.
+
+        Args:
+            component: The component being analyzed
+            cluster_analysis: The clustered structure from step_cluster_grouping
+            subgraph_cluster_results: Cluster results for the subgraph (for validation)
+
+        Returns:
+            AnalysisInsights with detailed component information
+        """
+        logger.info(f"[DetailsAgent] Generating final detailed analysis for: {component.name}")
+        meta_context_str = self.meta_context.llm_str() if self.meta_context else "No project context available."
+        project_type = self.meta_context.project_type if self.meta_context else "unknown"
+
+        cluster_str = cluster_analysis.llm_str() if cluster_analysis else "No cluster analysis available."
+
+        prompt = self.prompts["final_analysis"].format(
+            insight_so_far=cluster_str,
+            component=component.llm_str(),
+            meta_context=meta_context_str,
+            project_type=project_type,
+        )
+
+        # Build validation context with subgraph CFG graphs for edge checking
+        context = ValidationContext(
+            cluster_results=subgraph_cluster_results,
+            cfg_graphs={lang: self.static_analysis.get_cfg(lang) for lang in self.static_analysis.get_languages()},
+        )
+
+        return self._validation_invoke(
+            prompt,
+            AnalysisInsights,
+            validators=[validate_relation_component_names, validate_component_relationships, validate_key_entities],
+            context=context,
+        )
+
+    def run(self, component: Component):
+        """
+        Analyze a component in detail by creating a subgraph and analyzing its structure.
+
+        This follows the same pattern as AbstractionAgent but operates on a component-level
+        subgraph instead of the full codebase.
+
+        Args:
+            component: Component to analyze in detail
+
+        Returns:
+            Tuple of (AnalysisInsights, cluster_results dict) with detailed component information
+        """
+        logger.info(f"[DetailsAgent] Processing component: {component.name}")
+
+        # Step 1: Create subgraph from component's assigned files using strict filtering
+        subgraph_str, subgraph_cluster_results = self._create_strict_component_subgraph(component)
+
+        # Step 2: Group clusters within the subgraph
+        cluster_analysis = self.step_cluster_grouping(component, subgraph_str, subgraph_cluster_results)
+
+        # Step 3: Generate detailed analysis from grouped clusters
+        analysis = self.step_final_analysis(component, cluster_analysis, subgraph_cluster_results)
+
+        # Step 4: Sanitize cluster IDs (remove invalid ones) - use subgraph's cluster results
+        self._sanitize_component_cluster_ids(analysis, cluster_results=subgraph_cluster_results)
+
+        # Step 5: Assign files to components (deterministic + LLM-based with validation)
+        # Pass component's assigned files as scope to limit classification to this component
+        self.classify_files(analysis, subgraph_cluster_results, component.assigned_files)
+
+        # Step 6: Fix source code reference lines (resolves reference_file paths)
+        analysis = self.fix_source_code_reference_lines(analysis)
+
+        # Step 7: Ensure unique key entities across components
+        self._ensure_unique_key_entities(analysis)
+        # Step 8: Assign deterministic component IDs based on parent
+        assign_component_ids(analysis, parent_id=component.component_id)
+
+        return analysis, subgraph_cluster_results

agents/llm_config.py

@@ -0,0 +1,309 @@
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any, Type
+
+from langchain_anthropic import ChatAnthropic
+from langchain_aws import ChatBedrockConverse
+from langchain_cerebras import ChatCerebras
+from langchain_core.language_models import BaseChatModel
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain_ollama import ChatOllama
+from langchain_openai import ChatOpenAI
+
+from agents.constants import LLMDefaults
+from agents.prompts.prompt_factory import LLMType, initialize_global_factory
+from monitoring.callbacks import MonitoringCallback
+
+# Initialize global monitoring callback with its own stats container to avoid ContextVar dependency
+from monitoring.stats import RunStats
+
+MONITORING_CALLBACK = MonitoringCallback(stats_container=RunStats())
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Module-level model overrides – set once by the orchestrator (main.py) and
+# consumed by initialize_llms() without needing to thread the values through
+# every intermediate function signature.
+# ---------------------------------------------------------------------------
+_agent_model_override: str | None = None
+_parsing_model_override: str | None = None
+
+
+def configure_models(
+    agent_model: str | None = None,
+    parsing_model: str | None = None,
+    api_keys: dict[str, str] | None = None,
+) -> None:
+    """Set process-wide model and provider overrides.  Call this once at startup.
+
+    ``api_keys`` maps provider env-var names to values, e.g.::
+
+        configure_models(api_keys={"OPENAI_API_KEY": "sk-..."})
+
+    Keys already present in the shell environment are never overwritten, so
+    CI/CD pipelines that export keys directly retain full control.
+
+    Priority (highest to lowest):
+      1. Shell environment variables (set before the process starts)
+      2. ``api_keys`` passed here  /  values from ~/.codeboarding/config.toml
+      3. AGENT_MODEL / PARSING_MODEL environment variables (for model names)
+      4. Provider defaults defined in LLM_PROVIDERS
+    """
+    global _agent_model_override, _parsing_model_override
+    _agent_model_override = agent_model
+    _parsing_model_override = parsing_model
+    if api_keys:
+        for env_var, value in api_keys.items():
+            if value and not os.environ.get(env_var):
+                os.environ[env_var] = value
+
+
+@dataclass
+class LLMConfig:
+    """
+    Configuration for LLM providers.
+
+    Attributes:
+        agent_model: The "agent" model used for complex reasoning and agentic tasks.
+        parsing_model: The "parsing" model used for fast, cost-effective extraction and parsing tasks.
+        agent_temperature: Temperature for the agent model. Defaults to 0 for deterministic behavior
+                          which is crucial for code understanding and reasoning.
+        parsing_temperature: Temperature for the parsing model. Defaults to 0 for deterministic behavior
+                          which is crucial for structured output extraction.
+        llm_type: The LLMType enum value for prompt factory selection.
+    """
+
+    chat_class: Type[BaseChatModel]
+    api_key_env: str
+    agent_model: str
+    parsing_model: str
+    llm_type: LLMType
+    agent_temperature: float = LLMDefaults.DEFAULT_AGENT_TEMPERATURE
+    parsing_temperature: float = LLMDefaults.DEFAULT_PARSING_TEMPERATURE
+    extra_args: dict[str, Any] = field(default_factory=dict)
+    alt_env_vars: list[str] = field(default_factory=list)
+
+    def get_api_key(self) -> str | None:
+        return os.getenv(self.api_key_env)
+
+    def is_active(self) -> bool:
+        """Check if any of the environment variables (primary or alternate) are set."""
+        if os.getenv(self.api_key_env):
+            return True
+        return any(os.getenv(var) for var in self.alt_env_vars)
+
+    def get_resolved_extra_args(self) -> dict[str, Any]:
+        resolved = {}
+        for k, v in self.extra_args.items():
+            value = v() if callable(v) else v
+            if value is not None:
+                resolved[k] = value
+        return resolved
+
+
+# Define supported providers in priority order
+LLM_PROVIDERS = {
+    "openai": LLMConfig(
+        chat_class=ChatOpenAI,
+        api_key_env="OPENAI_API_KEY",
+        agent_model="gpt-4o",
+        parsing_model="gpt-4o-mini",
+        llm_type=LLMType.GPT4,
+        alt_env_vars=["OPENAI_BASE_URL"],
+        extra_args={
+            "base_url": lambda: os.getenv("OPENAI_BASE_URL"),
+            "max_tokens": None,
+            "timeout": None,
+            "max_retries": 0,
+        },
+    ),
+    "vercel": LLMConfig(
+        chat_class=ChatOpenAI,
+        api_key_env="VERCEL_API_KEY",
+        agent_model="google/gemini-3-flash",
+        parsing_model="openai/gpt-oss-120b",  # Use OpenAI model for parsing to avoid trustcall compatibility issues with Gemini
+        llm_type=LLMType.GEMINI_FLASH,
+        alt_env_vars=["VERCEL_BASE_URL"],
+        extra_args={
+            "base_url": lambda: os.getenv("VERCEL_BASE_URL", f"https://ai-gateway.vercel.sh/v1"),
+            "max_tokens": None,
+            "timeout": None,
+            "max_retries": 0,
+        },
+    ),
+    "anthropic": LLMConfig(
+        chat_class=ChatAnthropic,
+        api_key_env="ANTHROPIC_API_KEY",
+        agent_model="claude-3-7-sonnet-20250219",
+        parsing_model="claude-3-haiku-20240307",
+        llm_type=LLMType.CLAUDE,
+        extra_args={
+            "max_tokens": 8192,
+            "timeout": None,
+            "max_retries": 0,
+        },
+    ),
+    "google": LLMConfig(
+        chat_class=ChatGoogleGenerativeAI,
+        api_key_env="GOOGLE_API_KEY",
+        agent_model="gemini-3-flash",
+        parsing_model="gemini-3-flash",
+        llm_type=LLMType.GEMINI_FLASH,
+        extra_args={
+            "max_tokens": None,
+            "timeout": None,
+            "max_retries": 0,
+        },
+    ),
+    "aws": LLMConfig(
+        chat_class=ChatBedrockConverse,
+        api_key_env="AWS_BEARER_TOKEN_BEDROCK",  # Used for existence check
+        agent_model="us.anthropic.claude-3-7-sonnet-20250219-v1:0",
+        parsing_model="us.anthropic.claude-3-haiku-20240307-v1:0",
+        llm_type=LLMType.CLAUDE,
+        extra_args={
+            "max_tokens": 4096,
+            "region_name": lambda: os.getenv("AWS_DEFAULT_REGION", "us-east-1"),
+            "credentials_profile_name": None,
+        },
+    ),
+    "cerebras": LLMConfig(
+        chat_class=ChatCerebras,
+        api_key_env="CEREBRAS_API_KEY",
+        agent_model="gpt-oss-120b",
+        parsing_model="llama3.1-8b",
+        llm_type=LLMType.GPT4,
+        extra_args={
+            "max_tokens": None,
+            "timeout": None,
+            "max_retries": 0,
+        },
+    ),
+    "ollama": LLMConfig(
+        chat_class=ChatOllama,
+        api_key_env="OLLAMA_BASE_URL",  # Used for existence check
+        agent_model="qwen3:30b",
+        parsing_model="qwen2.5:7b",
+        llm_type=LLMType.GEMINI_FLASH,
+        agent_temperature=0.1,
+        parsing_temperature=0.1,
+        extra_args={
+            "base_url": lambda: os.getenv("OLLAMA_BASE_URL"),
+        },
+    ),
+    "deepseek": LLMConfig(
+        chat_class=ChatOpenAI,
+        api_key_env="DEEPSEEK_API_KEY",
+        agent_model="deepseek-chat",
+        parsing_model="deepseek-chat",
+        llm_type=LLMType.DEEPSEEK,
+        alt_env_vars=["DEEPSEEK_BASE_URL"],
+        extra_args={
+            "base_url": lambda: os.getenv("DEEPSEEK_BASE_URL", "https://api.deepseek.com/v1"),
+            "max_tokens": None,
+            "timeout": None,
+            "max_retries": 0,
+        },
+    ),
+    "glm": LLMConfig(
+        chat_class=ChatOpenAI,
+        api_key_env="GLM_API_KEY",
+        agent_model="glm-4-flash",
+        parsing_model="glm-4-flash",
+        llm_type=LLMType.GLM,
+        alt_env_vars=["GLM_BASE_URL"],
+        extra_args={
+            "base_url": lambda: os.getenv("GLM_BASE_URL", "https://open.bigmodel.cn/api/paas/v4"),
+            "max_tokens": None,
+            "timeout": None,
+            "max_retries": 0,
+        },
+    ),
+    "kimi": LLMConfig(
+        chat_class=ChatOpenAI,
+        api_key_env="KIMI_API_KEY",
+        agent_model="kimi-k2.5",
+        parsing_model="kimi-k2.5",
+        llm_type=LLMType.KIMI,
+        alt_env_vars=["KIMI_BASE_URL"],
+        extra_args={
+            "base_url": lambda: os.getenv("KIMI_BASE_URL", "https://api.moonshot.cn/v1"),
+            "max_tokens": None,
+            "timeout": None,
+            "max_retries": 0,
+        },
+    ),
+}
+
+
+def _initialize_llm(
+    model_override: str | None,
+    model_attr: str,
+    temperature_attr: str,
+    log_prefix: str,
+    init_factory: bool = False,
+) -> tuple[BaseChatModel, str]:
+    for name, config in LLM_PROVIDERS.items():
+        if not config.is_active():
+            continue
+
+        model_name = model_override or getattr(config, model_attr)
+
+        if init_factory:
+            detected_llm_type = LLMType.from_model_name(model_name)
+            initialize_global_factory(detected_llm_type)
+            logger.info(
+                f"Initialized prompt factory for {name} provider with model '{model_name}' "
+                f"-> {detected_llm_type.value} prompt factory"
+            )
+
+        logger.info(f"Using {name.title()} {log_prefix}LLM with model: {model_name}")
+
+        kwargs = {
+            "model": model_name,
+            "temperature": getattr(config, temperature_attr),
+        }
+        kwargs.update(config.get_resolved_extra_args())
+
+        if name not in ["aws", "ollama"]:
+            api_key = config.get_api_key()
+            kwargs["api_key"] = api_key or "no-key-required"
+
+        model = config.chat_class(**kwargs)  # type: ignore[call-arg, arg-type]
+        return model, model_name
+
+    required_vars = []
+    for config in LLM_PROVIDERS.values():
+        required_vars.append(config.api_key_env)
+        required_vars.extend(config.alt_env_vars)
+
+    raise ValueError(f"No valid LLM configuration found. Please set one of: {', '.join(sorted(set(required_vars)))}")
+
+
+def validate_api_key_provided() -> None:
+    """Raise ValueError if zero or more than one LLM provider key is configured."""
+    active = [name for name, config in LLM_PROVIDERS.items() if config.is_active()]
+    if not active:
+        required = sorted({config.api_key_env for config in LLM_PROVIDERS.values()})
+        raise ValueError(f"No LLM provider API key found. Set one of: {', '.join(required)}")
+    if len(active) > 1:
+        raise ValueError(f"Multiple LLM provider keys detected ({', '.join(active)}); please set only one.")
+
+
+def initialize_agent_llm(model_override: str | None = None) -> BaseChatModel:
+    model, model_name = _initialize_llm(model_override, "agent_model", "agent_temperature", "", init_factory=True)
+    MONITORING_CALLBACK.model_name = model_name
+    return model
+
+
+def initialize_parsing_llm(model_override: str | None = None) -> BaseChatModel:
+    model, _ = _initialize_llm(model_override, "parsing_model", "parsing_temperature", "Extractor ")
+    return model
+
+
+def initialize_llms() -> tuple[BaseChatModel, BaseChatModel]:
+    agent_llm = initialize_agent_llm(_agent_model_override or os.getenv("AGENT_MODEL"))
+    parsing_llm = initialize_parsing_llm(_parsing_model_override or os.getenv("PARSING_MODEL"))
+    return agent_llm, parsing_llm