shotgun-sh 0.7.3.dev1__tar.gz → 0.7.3.dev2__tar.gz

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shotgun-sh
-Version: 0.7.3.dev1
+Version: 0.7.3.dev2
 Summary: AI-powered research, planning, and task management CLI tool
 Project-URL: Homepage, https://shotgun.sh/
 Project-URL: Repository, https://github.com/shotgun-sh/shotgun

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "shotgun-sh"
-version = "0.7.3.dev1"
+version = "0.7.3.dev2"
 description = "AI-powered research, planning, and task management CLI tool"
 readme = "README.md"
 license = { text = "MIT" }

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/src/shotgun/agents/config/manager.py

@@ -704,17 +704,26 @@ class ConfigManager:
     def _get_provider_config(
         self, config: ShotgunConfig, provider: ProviderType
     ) -> Any:
-        """Retrieve the provider-specific configuration section."""
+        """Retrieve the provider-specific configuration section.
+
+        Returns None for OPENAI_COMPATIBLE since it uses environment variables
+        instead of config file.
+        """
         if provider == ProviderType.OPENAI:
             return config.openai
         if provider == ProviderType.ANTHROPIC:
             return config.anthropic
         if provider == ProviderType.GOOGLE:
             return config.google
+        if provider == ProviderType.OPENAI_COMPATIBLE:
+            # OPENAI_COMPATIBLE uses env vars (SHOTGUN_OPENAI_COMPAT_*), not config
+            return None
         raise ValueError(f"Unsupported provider: {provider}")
 
     def _provider_has_api_key(self, provider_config: Any) -> bool:
         """Return True if the provider config contains a usable API key."""
+        if provider_config is None:
+            return False
         api_key = getattr(provider_config, API_KEY_FIELD, None)
         if api_key is None:
             return False

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/src/shotgun/agents/config/models.py

@@ -13,6 +13,7 @@ class ProviderType(StrEnum):
     OPENAI = "openai"
     ANTHROPIC = "anthropic"
     GOOGLE = "google"
+    OPENAI_COMPATIBLE = "openai_compatible"
 
 
 class KeyProvider(StrEnum):
@@ -51,8 +52,8 @@ class ModelSpec(BaseModel):
 class ModelConfig(BaseModel):
     """A fully configured model with API key and settings."""
 
-    name: ModelName  # Model identifier
-    provider: ProviderType  # Actual LLM provider (openai, anthropic, google)
+    name: ModelName | str  # Model identifier (str for OpenAI-compatible endpoints)
+    provider: ProviderType  # Actual LLM provider (openai, anthropic, google, openai_compatible)
     key_provider: KeyProvider  # Authentication method (byok or shotgun)
     max_input_tokens: int
     max_output_tokens: int
@@ -77,15 +78,28 @@ class ModelConfig(BaseModel):
             )
         return self._model_instance
 
+    @property
+    def name_str(self) -> str:
+        """Get the model name as a string.
+
+        Handles both ModelName enum and plain string (for OpenAI-compatible).
+        """
+        if isinstance(self.name, str):
+            return self.name
+        return self.name.value
+
     @property
     def pydantic_model_name(self) -> str:
         """Compute the full Pydantic AI model identifier. For backward compatibility."""
+        if self.provider == ProviderType.OPENAI_COMPATIBLE:
+            # For OpenAI-compatible endpoints, use openai prefix with the model name
+            return f"openai:{self.name_str}"
         provider_prefix = {
             ProviderType.OPENAI: "openai",
             ProviderType.ANTHROPIC: "anthropic",
             ProviderType.GOOGLE: "google-gla",
         }
-        return f"{provider_prefix[self.provider]}:{self.name}"
+        return f"{provider_prefix[self.provider]}:{self.name_str}"
 
     @property
     def is_shotgun_account(self) -> bool:

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/src/shotgun/agents/config/provider.py

@@ -31,7 +31,60 @@ from .streaming_test import check_streaming_capability
 logger = get_logger(__name__)
 
 # Global cache for Model instances (singleton pattern)
-_model_cache: dict[tuple[ProviderType, KeyProvider, ModelName, str], Model] = {}
+_model_cache: dict[tuple[ProviderType, KeyProvider, ModelName | str, str], Model] = {}
+
+# Module-level model override for OpenAI-compatible mode (set via --model CLI flag)
+_openai_compat_model_override: str | None = None
+
+# Default model for OpenAI-compatible endpoints
+OPENAI_COMPAT_DEFAULT_MODEL = "gpt-5.2"
+
+
+def set_openai_compat_model(model: str | None) -> None:
+    """Set the model override for OpenAI-compatible endpoints.
+
+    This is called by the CLI when --model is specified.
+
+    Args:
+        model: Model name to use, or None to use the default.
+    """
+    global _openai_compat_model_override
+    _openai_compat_model_override = model
+
+
+def _create_openai_compat_model(
+    api_key: str, model_name: str, max_tokens: int
+) -> Model:
+    """Create a model for OpenAI-compatible endpoints.
+
+    Uses the SHOTGUN_OPENAI_COMPAT_BASE_URL from settings to configure
+    the LiteLLM provider with a custom base URL.
+
+    Args:
+        api_key: API key for the endpoint
+        model_name: Name of the model to use
+        max_tokens: Maximum output tokens
+
+    Returns:
+        Configured OpenAI-compatible Model instance
+    """
+    from shotgun.settings import settings
+
+    base_url = settings.openai_compat.base_url
+    if not base_url:
+        raise ValueError(
+            "SHOTGUN_OPENAI_COMPAT_BASE_URL is required for OpenAI-compatible mode"
+        )
+
+    # Use OpenAI provider with custom base_url
+    openai_provider = OpenAIProvider(api_key=api_key, base_url=base_url)
+
+    # Use OpenAIChatModel for broad compatibility with OpenAI-compatible APIs
+    return OpenAIChatModel(
+        model_name,
+        provider=openai_provider,
+        settings=ModelSettings(max_tokens=max_tokens),
+    )
 
 
 def get_default_model_for_provider(config: ShotgunConfig) -> ModelName:
@@ -65,7 +118,7 @@ def get_default_model_for_provider(config: ShotgunConfig) -> ModelName:
 def get_or_create_model(
     provider: ProviderType,
     key_provider: "KeyProvider",
-    model_name: ModelName,
+    model_name: ModelName | str,
     api_key: str,
 ) -> Model:
     """Get or create a singleton Model instance.
@@ -92,8 +145,8 @@ def get_or_create_model(
             model_name,
         )
 
-        # Get max_tokens from MODEL_SPECS
-        if model_name in MODEL_SPECS:
+        # Get max_tokens from MODEL_SPECS (only for known models)
+        if isinstance(model_name, ModelName) and model_name in MODEL_SPECS:
             max_tokens = MODEL_SPECS[model_name].max_output_tokens
         else:
             # Fallback defaults based on provider
@@ -101,9 +154,24 @@ def get_or_create_model(
                 ProviderType.OPENAI: 16_000,
                 ProviderType.ANTHROPIC: 32_000,
                 ProviderType.GOOGLE: 64_000,
+                ProviderType.OPENAI_COMPATIBLE: 16_000,
             }.get(provider, 16_000)
 
+        # Handle OpenAI-compatible endpoints (uses settings for base_url)
+        if provider == ProviderType.OPENAI_COMPATIBLE:
+            _model_cache[cache_key] = _create_openai_compat_model(
+                api_key, str(model_name), max_tokens
+            )
+            return _model_cache[cache_key]
+
         # Use LiteLLM proxy for Shotgun Account, native providers for BYOK
+        # At this point, model_name must be a ModelName (string handled above via OPENAI_COMPATIBLE)
+        if not isinstance(model_name, ModelName):
+            raise ValueError(
+                f"Unknown model name: {model_name}. "
+                "For custom models, set SHOTGUN_OPENAI_COMPAT_BASE_URL."
+            )
+
         if key_provider == KeyProvider.SHOTGUN:
             # Shotgun Account uses LiteLLM proxy with native model types where possible
             if model_name in MODEL_SPECS:
@@ -192,7 +260,38 @@ async def get_provider_model(
 
     Raises:
         ValueError: If provider is not configured properly or model not found
+
+    Note:
+        When SHOTGUN_OPENAI_COMPAT_BASE_URL is set, this function bypasses all
+        other provider configuration and uses the OpenAI-compatible endpoint.
+        The model name comes from SHOTGUN_OPENAI_COMPAT_DEFAULT_MODEL (default: gpt-4).
     """
+    from shotgun.settings import settings
+
+    # PRIORITY 0: Check for OpenAI-compatible mode
+    # When both SHOTGUN_OPENAI_COMPAT_BASE_URL and API_KEY are set, bypass all other providers
+    if settings.openai_compat.base_url and settings.openai_compat.api_key:
+        compat_api_key = settings.openai_compat.api_key
+
+        # Use CLI override if set, otherwise use hardcoded default
+        model_name = _openai_compat_model_override or OPENAI_COMPAT_DEFAULT_MODEL
+
+        logger.info(
+            "Using OpenAI-compatible endpoint: %s with model: %s",
+            settings.openai_compat.base_url,
+            model_name,
+        )
+
+        return ModelConfig(
+            name=model_name,
+            provider=ProviderType.OPENAI_COMPATIBLE,
+            key_provider=KeyProvider.BYOK,
+            max_input_tokens=128_000,  # Reasonable default for OpenAI-compatible
+            max_output_tokens=16_000,
+            api_key=compat_api_key,
+            supports_streaming=True,
+        )
+
     config_manager = get_config_manager()
     # Use cached config for read-only access (performance)
     config = await config_manager.load(force_reload=False)

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/src/shotgun/agents/context_analyzer/analyzer.py

@@ -414,7 +414,7 @@ class ContextAnalyzer:
             total_messages=total_messages,
             context_window=self.model_config.max_input_tokens,
             agent_context_tokens=agent_context_tokens,
-            model_name=self.model_config.name.value,
+            model_name=self.model_config.name_str,
             max_usable_tokens=max_usable_tokens,
             free_space_tokens=free_space_tokens,
         )

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/src/shotgun/agents/conversation/history/compaction.py

@@ -53,7 +53,7 @@ async def apply_persistent_compaction(
                 {
                     "tokens_saved_estimate": tokens_saved,
                     "retention_window": 3,
-                    "model_name": deps.llm_model.name.value,
+                    "model_name": deps.llm_model.name_str,
                 },
             )
 
@@ -98,7 +98,7 @@ async def apply_persistent_compaction(
                     if hasattr(deps, "agent_mode") and deps.agent_mode
                     else "unknown",
                     # Model and provider info (no computation needed)
-                    "model_name": deps.llm_model.name.value,
+                    "model_name": deps.llm_model.name_str,
                     "provider": deps.llm_model.provider.value,
                     "key_provider": deps.llm_model.key_provider.value,
                 },

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/src/shotgun/agents/conversation/history/history_processors.py

@@ -449,7 +449,7 @@ async def token_limit_compactor(
                 if hasattr(deps, "agent_mode") and deps.agent_mode
                 else "unknown",
                 # Model and provider info (no computation needed)
-                "model_name": deps.llm_model.name.value,
+                "model_name": deps.llm_model.name_str,
                 "provider": deps.llm_model.provider.value,
                 "key_provider": deps.llm_model.key_provider.value,
             },
@@ -614,7 +614,7 @@ async def _full_compaction(
             if hasattr(deps, "agent_mode") and deps.agent_mode
             else "unknown",
             # Model and provider info (no computation needed)
-            "model_name": deps.llm_model.name.value,
+            "model_name": deps.llm_model.name_str,
             "provider": deps.llm_model.provider.value,
             "key_provider": deps.llm_model.key_provider.value,
         },
@@ -686,7 +686,7 @@ async def _chunked_compaction(
                 1 for s in chunk_summaries if not s.startswith("[Chunk")
             ),
             "retention_window_size": len(retained_messages),
-            "model_name": deps.llm_model.name.value,
+            "model_name": deps.llm_model.name_str,
             "provider": deps.llm_model.provider.value,
         },
     )

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/src/shotgun/agents/conversation/history/token_counting/utils.py

@@ -54,6 +54,10 @@ def get_token_counter(model_config: ModelConfig) -> TokenCounter:
     counter: TokenCounter
     if model_config.provider == ProviderType.OPENAI:
         counter = OpenAITokenCounter(model_config.name)
+    elif model_config.provider == ProviderType.OPENAI_COMPATIBLE:
+        # Use OpenAI token counter for OpenAI-compatible endpoints
+        # Fall back to a reasonable default model for tokenization
+        counter = OpenAITokenCounter(str(model_config.name))
     elif model_config.provider == ProviderType.ANTHROPIC:
         counter = AnthropicTokenCounter(
             model_config.name, model_config.api_key, model_config.key_provider

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/src/shotgun/agents/tools/web_search/__init__.py

@@ -4,6 +4,7 @@ Provides web search capabilities for multiple LLM providers:
 - OpenAI: Uses Responses API with web_search tool
 - Anthropic: Uses Messages API with web_search_20250305 tool
 - Gemini: Uses grounding with Google Search via Pydantic AI
+- OpenAI-compatible: Uses Responses API via custom endpoint (e.g., LiteLLM proxy)
 
 Web search uses the provider matching the user's selected model for consistency.
 """
@@ -13,10 +14,12 @@ from collections.abc import Awaitable, Callable
 from shotgun.agents.config.manager import get_config_manager
 from shotgun.agents.config.models import MODEL_SPECS, ProviderType
 from shotgun.logging_config import get_logger
+from shotgun.settings import settings
 
 from .anthropic import anthropic_web_search_tool
 from .gemini import gemini_web_search_tool
 from .openai import openai_web_search_tool
+from .openai_compatible import openai_compatible_web_search_tool
 from .utils import is_provider_available
 
 logger = get_logger(__name__)
@@ -29,6 +32,7 @@ _PROVIDER_WEB_SEARCH_TOOLS: dict[ProviderType, WebSearchTool] = {
     ProviderType.OPENAI: openai_web_search_tool,
     ProviderType.ANTHROPIC: anthropic_web_search_tool,
     ProviderType.GOOGLE: gemini_web_search_tool,
+    ProviderType.OPENAI_COMPATIBLE: openai_compatible_web_search_tool,
 }
 
 
@@ -41,7 +45,12 @@ async def get_available_web_search_tools() -> list[WebSearchTool]:
     Returns:
         List containing the preferred web search tool, or empty if none available
     """
-    logger.debug("🔍 Checking available web search tools")
+    logger.debug("Checking available web search tools")
+
+    # Priority 0: Check for OpenAI-compatible mode
+    if settings.openai_compat.base_url and settings.openai_compat.api_key:
+        logger.info("Using OpenAI-compatible web search (openai_compat mode enabled)")
+        return [openai_compatible_web_search_tool]
 
     # Get user's selected model to determine preferred provider
     config_manager = get_config_manager()
@@ -60,18 +69,21 @@ async def get_available_web_search_tools() -> list[WebSearchTool]:
     if preferred_provider and await is_provider_available(preferred_provider):
         tool = _PROVIDER_WEB_SEARCH_TOOLS[preferred_provider]
         logger.info(
-            "🔍 Using %s web search (matches selected model)", preferred_provider.value
+            "Using %s web search (matches selected model)", preferred_provider.value
         )
         return [tool]
 
     # Fall back to any available provider
     for provider in ProviderType:
+        if provider == ProviderType.OPENAI_COMPATIBLE:
+            # Skip OPENAI_COMPATIBLE in fallback - it's handled above
+            continue
         if await is_provider_available(provider):
             tool = _PROVIDER_WEB_SEARCH_TOOLS[provider]
-            logger.info("🔍 Using %s web search (fallback)", provider.value)
+            logger.info("Using %s web search (fallback)", provider.value)
             return [tool]
 
-    logger.warning("⚠️ No web search tools available - no API keys configured")
+    logger.warning("No web search tools available - no API keys configured")
     return []
 
 
@@ -79,6 +91,7 @@ __all__ = [
     "openai_web_search_tool",
     "anthropic_web_search_tool",
     "gemini_web_search_tool",
+    "openai_compatible_web_search_tool",
     "get_available_web_search_tools",
     "is_provider_available",
     "WebSearchTool",

shotgun_sh-0.7.3.dev2/src/shotgun/agents/tools/web_search/openai_compatible.py

@@ -0,0 +1,136 @@
+"""OpenAI-compatible endpoint web search tool implementation."""
+
+import asyncio
+
+from openai import AsyncOpenAI
+from opentelemetry import trace
+
+from shotgun.agents.tools.registry import ToolCategory, register_tool
+from shotgun.logging_config import get_logger
+from shotgun.prompts import PromptLoader
+from shotgun.settings import settings
+from shotgun.utils.datetime_utils import get_datetime_context
+
+logger = get_logger(__name__)
+
+# Global prompt loader instance
+prompt_loader = PromptLoader()
+
+# Timeout for web search API call (in seconds)
+WEB_SEARCH_TIMEOUT = 120  # 2 minutes
+
+# Default model for web search if not configured
+DEFAULT_WEB_SEARCH_MODEL = "openai/gpt-5.2"
+
+
+@register_tool(
+    category=ToolCategory.WEB_RESEARCH,
+    display_text="Searching web",
+    key_arg="query",
+)
+async def openai_compatible_web_search_tool(query: str) -> str:
+    """Perform a web search using an OpenAI-compatible endpoint.
+
+    This tool uses OpenAI's Responses API with web_search capabilities
+    via the configured OpenAI-compatible endpoint (e.g., LiteLLM proxy).
+
+    Args:
+        query: The search query
+
+    Returns:
+        Search results as a formatted string
+    """
+    logger.debug("Invoking OpenAI-compatible web_search_tool with query: %s", query)
+
+    span = trace.get_current_span()
+    span.set_attribute("input.value", f"**Query:** {query}\n")
+
+    try:
+        base_url = settings.openai_compat.base_url
+        api_key = settings.openai_compat.api_key
+
+        if not base_url or not api_key:
+            error_msg = "OpenAI-compatible endpoint not configured"
+            logger.error(error_msg)
+            span.set_attribute("output.value", f"**Error:**\n {error_msg}\n")
+            return error_msg
+
+        # Get datetime context for the search prompt
+        dt_context = get_datetime_context()
+
+        # Render search prompt from template
+        prompt = prompt_loader.render(
+            "tools/web_search.j2",
+            query=query,
+            current_datetime=dt_context.datetime_formatted,
+            timezone_name=dt_context.timezone_name,
+            utc_offset=dt_context.utc_offset,
+        )
+
+        # Use configured web search model or default
+        web_search_model = (
+            settings.openai_compat.web_search_model or DEFAULT_WEB_SEARCH_MODEL
+        )
+
+        logger.debug(
+            "Using OpenAI-compatible endpoint for web search: %s with model %s",
+            base_url,
+            web_search_model,
+        )
+
+        client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+
+        # Wrap API call with timeout to prevent indefinite hangs
+        try:
+            response = await asyncio.wait_for(
+                client.responses.create(
+                    model=web_search_model,
+                    input=[
+                        {
+                            "role": "user",
+                            "content": [{"type": "input_text", "text": prompt}],
+                        }
+                    ],
+                    text={
+                        "format": {"type": "text"},
+                        "verbosity": "high",
+                    },
+                    reasoning={"effort": "medium", "summary": "auto"},
+                    tools=[
+                        {
+                            "type": "web_search",
+                            "user_location": {"type": "approximate"},
+                            "search_context_size": "high",
+                        }
+                    ],
+                    store=False,
+                    include=[
+                        "reasoning.encrypted_content",
+                        "web_search_call.action.sources",  # pyright: ignore[reportArgumentType]
+                    ],
+                ),
+                timeout=WEB_SEARCH_TIMEOUT,
+            )
+        except asyncio.TimeoutError:
+            error_msg = f"Web search timed out after {WEB_SEARCH_TIMEOUT} seconds"
+            logger.warning(error_msg)
+            span.set_attribute("output.value", f"**Error:**\n {error_msg}\n")
+            return error_msg
+
+        result_text = response.output_text or "No content returned"
+
+        logger.debug("Web search result: %d characters", len(result_text))
+        logger.debug(
+            "Result preview: %s...",
+            result_text[:100] if result_text else "No result",
+        )
+
+        span.set_attribute("output.value", f"**Results:**\n {result_text}\n")
+
+        return result_text
+    except Exception as e:
+        error_msg = f"Error performing web search: {str(e)}"
+        logger.error("Web search failed: %s", str(e))
+        logger.debug("Full error details: %s", error_msg)
+        span.set_attribute("output.value", f"**Error:**\n {error_msg}\n")
+        return error_msg

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/src/shotgun/cli/context.py

@@ -96,7 +96,7 @@ async def analyze_context() -> ContextAnalysisOutput:
     model_config = await get_provider_model()
 
     # Debug: Log the model being used
-    logger.debug(f"Using model: {model_config.name.value}")
+    logger.debug(f"Using model: {model_config.name_str}")
     logger.debug(f"Provider: {model_config.provider.value}")
     logger.debug(f"Key provider: {model_config.key_provider.value}")
     logger.debug(f"Max input tokens: {model_config.max_input_tokens}")

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/src/shotgun/cli/run.py

@@ -37,6 +37,14 @@ def run(
         ProviderType | None,
         typer.Option("--provider", "-p", help="AI provider to use (overrides default)"),
     ] = None,
+    model: Annotated[
+        str | None,
+        typer.Option(
+            "--model",
+            "-m",
+            help="Model name to use (requires SHOTGUN_OPENAI_COMPAT_BASE_URL to be set)",
+        ),
+    ] = None,
 ) -> None:
     """Execute a prompt using the Router agent in drafting mode.
 
@@ -45,6 +53,12 @@ def run(
     """
     logger.info("Running prompt: %s", prompt[:100])
 
+    # If --model is specified, set it for OpenAI-compatible mode
+    if model:
+        from shotgun.agents.config.provider import set_openai_compat_model
+
+        set_openai_compat_model(model)
+
     try:
         asyncio.run(async_run(prompt, non_interactive, provider))
     except Exception as e:

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/src/shotgun/main.py

@@ -165,6 +165,14 @@ def main(
             help="Force re-indexing of codebase (ignores existing index)",
         ),
     ] = False,
+    model: Annotated[
+        str | None,
+        typer.Option(
+            "--model",
+            "-m",
+            help="Model name to use (requires SHOTGUN_OPENAI_COMPAT_BASE_URL to be set)",
+        ),
+    ] = None,
 ) -> None:
     """Shotgun - AI-powered CLI tool."""
     logger.debug("Starting shotgun CLI application")
@@ -174,6 +182,12 @@ def main(
         perform_auto_update_async(no_update_check=no_update_check)
 
     if ctx.invoked_subcommand is None and not ctx.resilient_parsing:
+        # If --model is specified, set it for OpenAI-compatible mode
+        if model:
+            from shotgun.agents.config.provider import set_openai_compat_model
+
+            set_openai_compat_model(model)
+
         if web:
             logger.debug("Launching shotgun TUI as web application")
             try:
@@ -184,6 +198,7 @@ def main(
                     no_update_check=no_update_check,
                     continue_session=continue_session,
                     force_reindex=force_reindex,
+                    model_override=model,  # Passed to construct command line for spawned process
                 )
             finally:
                 # Ensure PostHog is shut down cleanly even if server exits unexpectedly

{shotgun_sh-0.7.3.dev1 → shotgun_sh-0.7.3.dev2}/src/shotgun/settings.py

@@ -241,6 +241,39 @@ class IndexingSettings(BaseSettings):
         return bool(v)
 
 
+class OpenAICompatSettings(BaseSettings):
+    """OpenAI-compatible endpoint settings.
+
+    When base_url is set, Shotgun bypasses normal provider configuration
+    and uses the specified endpoint directly for all LLM requests.
+
+    Environment variables:
+        SHOTGUN_OPENAI_COMPAT_BASE_URL: The base URL of the OpenAI-compatible endpoint
+        SHOTGUN_OPENAI_COMPAT_API_KEY: API key for authentication
+        SHOTGUN_OPENAI_COMPAT_WEB_SEARCH_MODEL: Model to use for web search (optional)
+    """
+
+    base_url: str | None = Field(
+        default=None,
+        description="Base URL for OpenAI-compatible endpoint (e.g., https://api.example.com/v1)",
+    )
+    api_key: str | None = Field(
+        default=None,
+        description="API key for the OpenAI-compatible endpoint",
+    )
+    web_search_model: str | None = Field(
+        default=None,
+        description="Model to use for web search (defaults to openai/gpt-5.2 if not set)",
+    )
+
+    model_config = SettingsConfigDict(
+        env_prefix="SHOTGUN_OPENAI_COMPAT_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+
 class Settings(BaseSettings):
     """Main application settings with SHOTGUN_ prefix.
 
@@ -276,6 +309,7 @@ class Settings(BaseSettings):
     api: ApiSettings = Field(default_factory=ApiSettings)
     dev: DevelopmentSettings = Field(default_factory=DevelopmentSettings)
     indexing: IndexingSettings = Field(default_factory=IndexingSettings)
+    openai_compat: OpenAICompatSettings = Field(default_factory=OpenAICompatSettings)
 
     model_config = SettingsConfigDict(
         env_prefix="SHOTGUN_",