feat: add local LLM summarization via OpenAI-compatible endpoints (#8)

- Implemented `OpenAIBatchSummarizer` using `httpx` to query local endpoints.
- Placed local LLMs as the fallback after Anthropic and Gemini options.
- Added support for `OPENAI_API_BASE`, `OPENAI_API_KEY`, and `OPENAI_MODEL` environment variables.
- Configured a dynamic HTTP request timeout via `OPENAI_TIMEOUT` (default: 60s).
- Wrote full unit tests including mock HTTP server resolution and timeout configuration.
- Standardized documentation and fallback defaults to `qwen3-coder`.
- Promoted local LLMs guidelines structurally above the Env Vars reference in `README.md`.

Author: eresende

README.md

@@ -290,13 +290,42 @@ See SECURITY.md for details.
 
 ---
 
+## Local LLMs (Ollama / LM Studio)
+
+You can use local, privacy-preserving AI models to generate summaries by providing an OpenAI-compatible endpoint.
+
+For **Ollama**, run a model locally, then configure the MCP server:
+```json
+"env": {
+  "OPENAI_API_BASE": "http://localhost:11434/v1",
+  "OPENAI_MODEL": "qwen3-coder"
+}
+```
+
+For **LM Studio**, ensure the Local Server is running (usually on port 1234):
+```json
+"env": {
+  "OPENAI_API_BASE": "http://127.0.0.1:1234/v1",
+  "OPENAI_MODEL": "openai/gpt-oss-20b"
+}
+```
+
+> [!TIP]
+> **Performance Note:** Local models can be slow to load into memory on their first request, potentially causing the MCP server to time out and fall back to generic signature summaries. It is highly recommended to **pre-load the model** in Ollama or LM Studio before starting the server, or increase the `OPENAI_TIMEOUT` environment variable (e.g., to `"120.0"`) to allow more time for generation.
+
+---
+
 ## Environment Variables
 
 | Variable                    | Purpose                   | Required |
 | --------------------------- | ------------------------- | -------- |
 | `GITHUB_TOKEN`              | GitHub API auth           | No       |
 | `ANTHROPIC_API_KEY`         | Symbol summaries via Claude Haiku (takes priority) | No       |
 | `GOOGLE_API_KEY`            | Symbol summaries via Gemini Flash | No       |
+| `OPENAI_API_BASE`           | Base URL for local LLMs (e.g. `http://localhost:11434/v1`) | No |
+| `OPENAI_API_KEY`            | API key for local LLMs (default: `local-llm`) | No |
+| `OPENAI_MODEL`              | Model name for local LLMs (default: `qwen3-coder`) | No |
+| `OPENAI_TIMEOUT`            | Timeout in seconds for local requests (default: `60.0`) | No |
 | `CODE_INDEX_PATH`           | Custom cache path         | No       |
 | `JCODEMUNCH_SHARE_SAVINGS`  | Set to `0` to disable anonymous community token savings reporting | No       |
 

src/jcodemunch_mcp/summarizer/__init__.py

@@ -3,6 +3,7 @@
 from .batch_summarize import (
     BatchSummarizer,
     GeminiBatchSummarizer,
+    OpenAIBatchSummarizer,
     extract_summary_from_docstring,
     signature_fallback,
     summarize_symbols_simple,
@@ -12,6 +13,7 @@
 __all__ = [
     "BatchSummarizer",
     "GeminiBatchSummarizer",
+    "OpenAIBatchSummarizer",
     "extract_summary_from_docstring",
     "signature_fallback",
     "summarize_symbols_simple",

src/jcodemunch_mcp/summarizer/batch_summarize.py

@@ -270,10 +270,139 @@ def _parse_response(self, text: str, expected_count: int) -> list[str]:
         return summaries
 
 
+@dataclass
+class OpenAIBatchSummarizer:
+    """AI-based batch summarization using OpenAI-compatible endpoints (Tier 2).
+    
+    Ideal for local LLMs like Ollama (http://localhost:11434/v1) or LM Studio.
+    """
+
+    model: str = "qwen3-coder"
+    max_tokens_per_batch: int = 500
+
+    def __post_init__(self):
+        self.client = None
+        self.api_base = os.environ.get("OPENAI_API_BASE")
+        if self.api_base:
+            # Strip trailing slash if present
+            self.api_base = self.api_base.rstrip("/")
+            self.model = os.environ.get("OPENAI_MODEL", self.model)
+            self._init_client()
+
+    def _init_client(self):
+        """Initialize HTTP client for OpenAI requests."""
+        try:
+            import httpx
+            
+            timeout_str = os.environ.get("OPENAI_TIMEOUT", "60.0")
+            try:
+                timeout = float(timeout_str)
+            except ValueError:
+                timeout = 60.0
+                
+            api_key = os.environ.get("OPENAI_API_KEY", "local-llm")
+            headers = {"Authorization": f"Bearer {api_key}"}
+            self.client = httpx.Client(timeout=timeout, headers=headers)
+        except ImportError:
+            self.client = None
+
+    def summarize_batch(self, symbols: list[Symbol], batch_size: int = 10) -> list[Symbol]:
+        """Summarize a batch of symbols using OpenAI compatible endpoint."""
+        if not self.client or not self.api_base:
+            for sym in symbols:
+                if not sym.summary:
+                    sym.summary = signature_fallback(sym)
+            return symbols
+
+        to_summarize = [s for s in symbols if not s.summary and not s.docstring]
+
+        if not to_summarize:
+            return symbols
+
+        for i in range(0, len(to_summarize), batch_size):
+            batch = to_summarize[i:i + batch_size]
+            self._summarize_one_batch(batch)
+
+        return symbols
+
+    def _summarize_one_batch(self, batch: list[Symbol]):
+        """Summarize one batch of symbols via HTTP POST."""
+        prompt = self._build_prompt(batch)
+
+        try:
+            payload = {
+                "model": self.model,
+                "messages": [{"role": "user", "content": prompt}],
+                "max_tokens": self.max_tokens_per_batch,
+                "temperature": 0.0,
+            }
+            
+            response = self.client.post(f"{self.api_base}/chat/completions", json=payload)
+            response.raise_for_status()
+            
+            data = response.json()
+            # Extract content from the first choice
+            text = data["choices"][0]["message"]["content"]
+            summaries = self._parse_response(text, len(batch))
+
+            for sym, summary in zip(batch, summaries):
+                if summary:
+                    sym.summary = summary
+                else:
+                    sym.summary = signature_fallback(sym)
+
+        except Exception:
+            for sym in batch:
+                if not sym.summary:
+                    sym.summary = signature_fallback(sym)
+
+    def _build_prompt(self, symbols: list[Symbol]) -> str:
+        """Build summarization prompt for a batch."""
+        lines = [
+            "Summarize each code symbol in ONE short sentence (max 15 words).",
+            "Focus on what it does, not how.",
+            "",
+            "Input:",
+        ]
+
+        for i, sym in enumerate(symbols, 1):
+            lines.append(f"{i}. {sym.kind}: {sym.signature}")
+
+        lines.extend([
+            "",
+            "Output format: NUMBER. SUMMARY",
+            "Example: 1. Authenticates users with username and password.",
+            "",
+            "Summaries:",
+        ])
+
+        return "\n".join(lines)
+
+    def _parse_response(self, text: str, expected_count: int) -> list[str]:
+        """Parse numbered summaries from response."""
+        summaries = [""] * expected_count
+
+        for line in text.split("\n"):
+            line = line.strip()
+            if not line:
+                continue
+
+            if "." in line:
+                parts = line.split(".", 1)
+                try:
+                    num = int(parts[0].strip())
+                    if 1 <= num <= expected_count:
+                        summaries[num - 1] = parts[1].strip()
+                except ValueError:
+                    continue
+
+        return summaries
+
+
 def _create_summarizer() -> Optional[BatchSummarizer]:
     """Return the appropriate summarizer based on available API keys.
 
-    Priority: Anthropic > Google Gemini.
+    Priority: Anthropic > Google Gemini > OpenAI/Local.
     Returns None if no API keys are configured.
     """
     if os.environ.get("ANTHROPIC_API_KEY"):
@@ -285,6 +414,11 @@ def _create_summarizer() -> Optional[BatchSummarizer]:
         s = GeminiBatchSummarizer()
         if s.client:
             return s
+            
+    if os.environ.get("OPENAI_API_BASE"):
+        s = OpenAIBatchSummarizer()
+        if s.client:
+            return s
 
     return None
 
@@ -313,14 +447,14 @@ def summarize_symbols(symbols: list[Symbol], use_ai: bool = True) -> list[Symbol
     """Full three-tier summarization.
 
     Tier 1: Docstring extraction (free)
-    Tier 2: AI batch summarization (Claude Haiku or Gemini Flash, auto-detected)
+    Tier 2: AI batch summarization (Claude Haiku, Gemini Flash, or Local LLM)
     Tier 3: Signature fallback (always works)
 
-    Provider selection (Tier 2):
-      - ANTHROPIC_API_KEY set → Claude Haiku
-      - GOOGLE_API_KEY set    → Gemini Flash
-      - Both set              → Anthropic takes priority
-      - Neither set           → skip to Tier 3
+    Provider selection (Tier 2 priority):
+      1. ANTHROPIC_API_KEY set → Claude Haiku
+      2. GOOGLE_API_KEY set    → Gemini Flash
+      3. OPENAI_API_BASE set   → Local LLM via OpenAI compatible endpoint
+      - None set               → skip to Tier 3
     """
     # Tier 1: Extract from docstrings
     for sym in symbols:

tests/test_summarizer.py

@@ -8,6 +8,7 @@
     signature_fallback,
     summarize_symbols_simple,
     GeminiBatchSummarizer,
+    OpenAIBatchSummarizer,
 )
 
 
@@ -155,3 +156,76 @@ def test_gemini_summarizer_with_mock_client():
     summarizer.summarize_batch(symbols)
     assert symbols[0].summary == "Computes the sum of two integers."
 
+
+def test_openai_summarizer_no_api_base():
+    """OpenAIBatchSummarizer falls back to signature when no API base is set."""
+    with patch.dict("os.environ", {}, clear=True):
+        summarizer = OpenAIBatchSummarizer()
+        assert summarizer.client is None
+
+    symbols = [
+        Symbol(
+            id="test::bar",
+            file="test.py",
+            name="bar",
+            qualified_name="bar",
+            kind="function",
+            language="python",
+            signature="def bar():",
+        )
+    ]
+    summarizer.summarize_batch(symbols)
+    assert symbols[0].summary == "def bar():"
+
+
+def test_openai_summarizer_with_mock_client():
+    """OpenAIBatchSummarizer parses the response from OpenAI compatible endpoints."""
+    mock_response = MagicMock()
+    mock_response.json.return_value = {
+        "choices": [
+            {
+                "message": {"content": "1. Multiplies two integers together."}
+            }
+        ]
+    }
+
+    mock_client = MagicMock()
+    mock_client.post.return_value = mock_response
+
+    with patch.dict("os.environ", {"OPENAI_API_BASE": "http://localhost:11434/v1", "OPENAI_MODEL": "qwen3-coder"}, clear=True):
+        summarizer = OpenAIBatchSummarizer()
+        summarizer.client = mock_client
+
+    symbols = [
+        Symbol(
+            id="test::multiply",
+            file="test.py",
+            name="multiply",
+            qualified_name="multiply",
+            kind="function",
+            language="python",
+            signature="def multiply(a: int, b: int) -> int:",
+        )
+    ]
+    summarizer.summarize_batch(symbols)
+    
+    # Verify the endpoint URL used
+    mock_client.post.assert_called_once()
+    assert mock_client.post.call_args[0][0] == "http://localhost:11434/v1/chat/completions"
+    assert symbols[0].summary == "Multiplies two integers together."
+
+@pytest.mark.asyncio
+async def test_openai_summarizer_timeout_config():
+    """OpenAIBatchSummarizer configures custom timeouts via OPENAI_TIMEOUT."""
+    # Test valid float parsing
+    with patch.dict("os.environ", {"OPENAI_API_BASE": "http://test", "OPENAI_TIMEOUT": "120.5"}, clear=True):
+        summarizer = OpenAIBatchSummarizer()
+        assert summarizer.client is not None
+        assert summarizer.client.timeout.read == 120.5
+
+    # Test invalid string fallback
+    with patch.dict("os.environ", {"OPENAI_API_BASE": "http://test", "OPENAI_TIMEOUT": "invalid"}, clear=True):
+        summarizer = OpenAIBatchSummarizer()
+        assert summarizer.client is not None
+        assert summarizer.client.timeout.read == 60.0
+