feat: add LiteLLM fallback, Playwright tests, and remove OpenAI hard dependency

- LiteLLM is now the default LLM backend (no .env or API key needed)
- Multistage model fallback chain: claude-sonnet-4 → gpt-4o → gpt-4o-mini
- OpenAI SDK still used when OPENAI_API_KEY is explicitly set
- agents.py and workbench service use ChatLiteLLM when no OpenAI key
- Added csv_ticket_stats and csv_sla_breach_tickets to agent tools
- Added KBA Drafter to Playwright nav tests and menu screenshots
- Added e2e tests: publish, delete, status filter, ticket viewer
- 32 unit tests + 5 live integration tests for LLM service
- Updated .env.example with LiteLLM-first documentation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: abossard

.env.example

@@ -1,19 +1,21 @@
-# OpenAI Configuration
-# Get your API key from: https://platform.openai.com/api-keys
+# LiteLLM Configuration (Default LLM backend)
+# Works out of the box with GitHub Copilot — no API keys needed.
+# Supports 100+ providers: GitHub Copilot, Ollama, Anthropic, etc.
+# Docs: https://docs.litellm.ai/docs/providers
 
-OPENAI_API_KEY=your-openai-api-key-here
-OPENAI_MODEL=gpt-4o-mini
-# Optional override
-# OPENAI_BASE_URL=https://api.openai.com/v1
+# Primary model (default: github_copilot/gpt-4o)
+# LITELLM_MODEL=github_copilot/gpt-4o
 
-# Ollama Configuration (for KBA Drafter)
-# Install Ollama: curl -fsSL https://ollama.com/install.sh | sh
-# Pull model: ollama pull llama3.2:1b
-# Start server: ollama serve
+# Fallback chain (comma-separated, tried in order if primary fails)
+# LITELLM_FALLBACK_MODELS=github_copilot/claude-sonnet-4,github_copilot/gpt-4o,github_copilot/gpt-4o-mini
 
-OLLAMA_BASE_URL=http://localhost:11434
-OLLAMA_MODEL=llama3.2:1b
-OLLAMA_TIMEOUT=60
+# OpenAI Configuration (Optional — overrides LiteLLM when set)
+# Get your API key from: https://platform.openai.com/api-keys
+# If set, uses OpenAI SDK directly with beta.chat.completions.parse()
+
+# OPENAI_API_KEY=your-openai-api-key-here
+# OPENAI_MODEL=gpt-4o-mini
+# OPENAI_BASE_URL=https://api.openai.com/v1
 
 # Knowledge Base Publishing Configuration (for KBA Drafter)
 # FileSystem Adapter (MVP - writes markdown files)

backend/agent_workbench/service.py

@@ -75,13 +75,21 @@ def on_tool_error(self, error: BaseException, *, run_id: Any, **kwargs: Any) ->
 # ============================================================================
 
 def _build_llm(model: str, api_key: str, base_url: str = "") -> Any:
-    from langchain_openai import ChatOpenAI
-    return ChatOpenAI(
-        model=model,
-        api_key=api_key,
-        base_url=base_url or None,
-        temperature=0.0,
-    )
+    if api_key:
+        from langchain_openai import ChatOpenAI
+        return ChatOpenAI(
+            model=model,
+            api_key=api_key,
+            base_url=base_url or None,
+            temperature=0.0,
+        )
+    else:
+        from langchain_litellm import ChatLiteLLM
+        litellm_model = os.getenv("LITELLM_MODEL", "github_copilot/gpt-4o")
+        return ChatLiteLLM(
+            model=litellm_model,
+            temperature=0.0,
+        )
 
 
 def _build_react_agent(llm: Any, tools: list[Any], system_prompt: str) -> Any:
@@ -147,11 +155,6 @@ def __init__(
     @property
     def llm(self) -> Any:
         if self._llm is None:
-            if not self._api_key:
-                raise ValueError(
-                    "OPENAI_API_KEY is required to run agents. "
-                    "Set it via environment variable or pass openai_api_key."
-                )
             self._llm = _build_llm(self._model, self._api_key, self._base_url)
         return self._llm
 

backend/agents.py

@@ -84,8 +84,7 @@ def _env_int(name: str, default: int) -> int:
 from langchain_core.callbacks import BaseCallbackHandler
 from langchain_core.tools import StructuredTool
 
-# Third-party - LangChain and LangGraph
-from langchain_openai import ChatOpenAI
+# Third-party - LangGraph
 from langgraph.prebuilt import create_react_agent
 
 # Third-party - Pydantic for validation
@@ -173,12 +172,13 @@ class AgentResponse(BaseModel):
 
 
 # ============================================================================
-# CONFIGURATION - OpenAI settings
+# CONFIGURATION - LLM settings (LiteLLM default, OpenAI optional)
 # ============================================================================
 
 OPENAI_API_KEY = os.getenv("OPENAI_API_KEY", "")
 OPENAI_MODEL = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
 OPENAI_BASE_URL = os.getenv("OPENAI_BASE_URL", "")  # optional override
+LITELLM_MODEL = os.getenv("LITELLM_MODEL", "github_copilot/gpt-4o")
 OPENAI_CALL_LOGGING_ENABLED = _env_flag("OPENAI_CALL_LOGGING_ENABLED", "true")
 AGENT_EFFICIENCY_MODE = _env_flag("AGENT_EFFICIENCY_MODE", "true")
 AGENT_TRACE_ENABLED = _env_flag("AGENT_TRACE_ENABLED", "false")
@@ -409,28 +409,27 @@ class AgentService:
 
     def __init__(self):
         """
-        Initialize the agent service with OpenAI.
+        Initialize the agent service.
         
-        Validates that required environment variables are set and creates
-        the LLM client for agent execution.
-        
-        Raises:
-            ValueError: If OpenAI configuration is incomplete
+        Uses OpenAI when OPENAI_API_KEY is set, otherwise falls back
+        to LiteLLM (supports GitHub Copilot, Ollama, etc.).
         """
-        # Validate configuration
-        if not OPENAI_API_KEY:
-            raise ValueError(
-                "OpenAI API key not set. "
-                "Please set OPENAI_API_KEY environment variable."
+        if OPENAI_API_KEY:
+            from langchain_openai import ChatOpenAI
+            self.llm = ChatOpenAI(
+                model=OPENAI_MODEL,
+                api_key=OPENAI_API_KEY,
+                base_url=OPENAI_BASE_URL or None,
+                temperature=0.0,
             )
-        
-        # Initialize ChatOpenAI
-        self.llm = ChatOpenAI(
-            model=OPENAI_MODEL,
-            api_key=OPENAI_API_KEY,
-            base_url=OPENAI_BASE_URL or None,
-            temperature=0.0,
-        )
+            logger.info(f"AgentService using OpenAI: {OPENAI_MODEL}")
+        else:
+            from langchain_litellm import ChatLiteLLM
+            self.llm = ChatLiteLLM(
+                model=LITELLM_MODEL,
+                temperature=0.0,
+            )
+            logger.info(f"AgentService using LiteLLM: {LITELLM_MODEL}")
 
         # CSV tools only (do not expose operations or external MCP)
         self.tools = self._build_csv_tools()
@@ -561,6 +560,27 @@ def _csv_ticket_fields() -> str:
             from tickets import Ticket
             return json.dumps(list(Ticket.model_fields.keys()))
 
+        def _csv_ticket_stats() -> str:
+            """Get aggregated statistics for CSV tickets."""
+            from collections import Counter
+            tickets = service.list_tickets()
+            by_status = Counter(t.status.value for t in tickets)
+            by_priority = Counter(t.priority.value for t in tickets)
+            by_group = Counter(t.assigned_group for t in tickets if t.assigned_group)
+            unassigned = sum(1 for t in tickets if t.assignee is None and t.assigned_group is not None)
+            return json.dumps({
+                "total": len(tickets), "unassigned": unassigned,
+                "by_status": dict(by_status), "by_priority": dict(by_priority),
+                "by_group": dict(by_group.most_common(10)),
+            }, default=str)
+
+        def _csv_sla_breach_tickets(unassigned_only: bool = True, include_ok: bool = False) -> str:
+            """Return tickets at SLA breach risk with pre-computed age and status."""
+            from tickets import get_sla_breach_report
+            tickets = service.list_tickets(has_assignee=False if unassigned_only else None)
+            report = get_sla_breach_report(tickets, reference_time=None, include_ok=include_ok)
+            return json.dumps(report.model_dump() if hasattr(report, 'model_dump') else report, default=str)
+
         return [
             StructuredTool.from_function(
                 func=_csv_list_tickets,
@@ -604,6 +624,21 @@ def _csv_ticket_fields() -> str:
                 name="csv_ticket_fields",
                 description="List available ticket fields (schema) as JSON array of field names.",
             ),
+            StructuredTool.from_function(
+                func=_csv_ticket_stats,
+                name="csv_ticket_stats",
+                description="Get aggregated statistics: total, unassigned, by_status, by_priority, by_group. Returns JSON.",
+            ),
+            StructuredTool.from_function(
+                func=_csv_sla_breach_tickets,
+                name="csv_sla_breach_tickets",
+                description=(
+                    "Return tickets at SLA breach risk. Pre-computed age_hours, sla_threshold_hours, breach_status. "
+                    "SLA thresholds: critical=4h, high=24h, medium=72h, low=120h. "
+                    "unassigned_only (default true) filters to group-assigned but no individual. "
+                    "include_ok (default false) adds tickets within SLA window. Returns JSON."
+                ),
+            ),
         ]
 
     async def run_agent(self, request: AgentRequest) -> AgentResponse: