feat: add OpenRouter support for LLM provider and update documentation

VTvito · VTvito · commit 5c5968d145fa · 2026-03-02T14:11:10.000+01:00
diff --git a/.env.example b/.env.example
@@ -15,3 +15,7 @@ HF_MODELS_PATH=./hf_models
 LLM_PROVIDER=openai
 OPENAI_API_KEY=
 OPENAI_MODEL=gpt-4o-mini
+
+# ── OpenRouter (free alternative — https://openrouter.ai/keys) ──
+OPENROUTER_API_KEY=
+OPENROUTER_MODEL=meta-llama/llama-3.1-8b-instruct:free
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -136,7 +136,7 @@ etl_microservices/
 │
 ├── ai_agent/
 │   ├── __init__.py
-│   ├── llm_provider.py            # Abstract LLMProvider + OpenAIProvider + LocalProvider
+│   ├── llm_provider.py            # Abstract LLMProvider + OpenAIProvider + OpenRouterProvider + LocalProvider
 │   ├── pipeline_agent.py          # NL → YAML pipeline generation + validation
 │   └── pipeline_compiler.py       # Parallel pipeline execution via Preparator SDK (dispatch registry + topological layering)
 │
@@ -326,7 +326,7 @@ Every service's `create_app()` now includes:
 
 | Module | Purpose |
 |---|---|
-| `ai_agent/llm_provider.py` | Abstract `LLMProvider` + `OpenAIProvider` (GPT-4o-mini default) + `LocalProvider` (calls text-completion-llm-service) |
+| `ai_agent/llm_provider.py` | Abstract `LLMProvider` + `OpenAIProvider` (GPT-4o-mini default) + `OpenRouterProvider` (200+ models, free tier) + `LocalProvider` (calls text-completion-llm-service) |
 | `ai_agent/pipeline_agent.py` | `PipelineAgent`: builds system prompt from `service_registry.json`, calls LLM to generate YAML, validates structure + services + params + dependencies. Standalone `validate_pipeline()` module-level function enables validation-only use without instantiating the agent (e.g., Streamlit UI). |
 | `ai_agent/pipeline_compiler.py` | `PipelineCompiler`: executes validated pipeline definitions via Preparator SDK with **parallel execution** of independent steps (topological layering via Kahn’s algorithm + `ThreadPoolExecutor`). Uses a **dispatch registry** (`_build_dispatch_registry()`) for extensibility—add new services via `register_service()` without if/elif chains. Returns `PipelineResult` with per-step metrics + `correlation_id`. Supports `join_datasets` (2 `depends_on` entries). Exposes `last_step_outputs` dict for UI data preview. |
 | `schemas/service_registry.json` | Complete metadata for all 11 services: name, type, description, endpoint, input/output formats, params with types/required/defaults/enums |
@@ -368,6 +368,7 @@ pipeline:
 ### LLM Provider Configuration
 
 - `LLM_PROVIDER=openai` → uses OpenAI API (requires `OPENAI_API_KEY`)
+- `LLM_PROVIDER=openrouter` → uses OpenRouter API gateway (requires `OPENROUTER_API_KEY`). Supports 200+ models including free ones (e.g., `meta-llama/llama-3.1-8b-instruct:free`). OpenAI-compatible API via `openai` Python package with custom `base_url`. Get a free key at https://openrouter.ai/keys.
 - `LLM_PROVIDER=local` → uses the local HuggingFace text-completion-llm-service
 - Factory: `create_llm_provider(provider=None)` reads env var if not specified
 
@@ -443,7 +444,7 @@ Single bridge network `etl-network`. Services reference each other by container
 | Volume | Mount | Purpose |
 |---|---|---|
 | `etl-containers-shared-data` | `/app/data` | Shared datasets, metadata, XCom files |
-| `etl-data-airflow` | `/opt/airflow` | Airflow persistence |
+| `etl-airflow-data` | `/opt/airflow` | Airflow persistence |
 | `etl-postgres-data` | PostgreSQL data dir | Airflow metadata DB |
 | `etl-grafana-data` | Grafana data dir | Dashboards |
 | `etl-prometheus-data` | Prometheus data dir | TSDB |
@@ -459,9 +460,11 @@ Single bridge network `etl-network`. Services reference each other by container
 | `ETL_DATA_ROOT` | `/app/data` | Base directory for datasets/metadata path resolution |
 | `ALLOW_PRIVATE_API_URLS` | `false` | Allow private/local API targets in `extract-api` |
 | `HF_MODELS_PATH` | `./hf_models` | Local HuggingFace model cache |
-| `LLM_PROVIDER` | `openai` | AI agent provider (`openai` or `local`) |
+| `LLM_PROVIDER` | `openai` | AI agent provider (`openai`, `openrouter`, or `local`) |
 | `OPENAI_API_KEY` | — | OpenAI API key |
 | `OPENAI_MODEL` | `gpt-4o-mini` | OpenAI model name |
+| `OPENROUTER_API_KEY` | — | OpenRouter API key (free at https://openrouter.ai/keys) |
+| `OPENROUTER_MODEL` | `meta-llama/llama-3.1-8b-instruct:free` | OpenRouter model identifier |
 
 ---
 
diff --git a/ai_agent/llm_provider.py b/ai_agent/llm_provider.py
@@ -1,9 +1,10 @@
 """
 LLM Provider Abstraction Layer.
 
-Supports two backends:
+Supports three backends:
   1. OpenAI API (GPT-4o / configurable model)
-  2. Local HuggingFace model via the existing text-completion-llm-service
+  2. OpenRouter API gateway (200+ models, including free ones — https://openrouter.ai)
+  3. Local HuggingFace model via the existing text-completion-llm-service
 
 Usage:
     provider = create_llm_provider()  # reads LLM_PROVIDER env var
@@ -67,6 +68,66 @@ def name(self) -> str:
         return f"OpenAI ({self.model})"
 
 
+class OpenRouterProvider(LLMProvider):
+    """OpenRouter API provider — OpenAI-compatible gateway to 200+ models (including free ones).
+
+    OpenRouter (https://openrouter.ai) aggregates LLMs from multiple providers
+    behind a single API key.  It exposes an OpenAI-compatible ``/chat/completions``
+    endpoint, so we reuse the ``openai`` Python package with a custom ``base_url``.
+
+    Free models (no credit required):
+        - meta-llama/llama-3.1-8b-instruct:free
+        - google/gemma-2-9b-it:free
+        - mistralai/mistral-7b-instruct:free
+        - qwen/qwen-2.5-7b-instruct:free
+
+    Set OPENROUTER_API_KEY in your environment (get one at https://openrouter.ai/keys).
+    """
+
+    OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+
+    def __init__(self, model: str = None, api_key: str = None):
+        try:
+            import openai
+        except ImportError:
+            raise ImportError("openai package not installed. Run: pip install openai")
+
+        self.model = model or os.getenv("OPENROUTER_MODEL", "meta-llama/llama-3.1-8b-instruct:free")
+        api_key = api_key or os.getenv("OPENROUTER_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "OPENROUTER_API_KEY environment variable is required for OpenRouter provider. "
+                "Get a free key at https://openrouter.ai/keys"
+            )
+
+        self.client = openai.OpenAI(
+            api_key=api_key,
+            base_url=self.OPENROUTER_BASE_URL,
+            default_headers={
+                "HTTP-Referer": "https://github.com/VTvito/arrowflow",
+                "X-Title": "ArrowFlow ETL Platform",
+            },
+        )
+        logger.info(f"OpenRouter provider initialized with model: {self.model}")
+
+    def generate(self, prompt: str, system_prompt: str = "", temperature: float = 0.3, max_tokens: int = 2048) -> str:
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": prompt})
+
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+        return response.choices[0].message.content
+
+    def name(self) -> str:
+        return f"OpenRouter ({self.model})"
+
+
 class LocalProvider(LLMProvider):
     """Local HuggingFace provider via the text-completion-llm-service."""
 
@@ -135,14 +196,17 @@ def create_llm_provider(provider: str = None, **kwargs) -> LLMProvider:
     Factory function to create an LLM provider.
 
     Args:
-        provider: "openai" or "local". Defaults to LLM_PROVIDER env var, then "openai".
+        provider: "openai", "openrouter", or "local".
+                  Defaults to LLM_PROVIDER env var, then "openai".
         **kwargs: Additional arguments passed to the provider constructor.
     """
     provider = provider or os.getenv("LLM_PROVIDER", "openai")
 
     if provider == "openai":
         return OpenAIProvider(**kwargs)
+    elif provider == "openrouter":
+        return OpenRouterProvider(**kwargs)
     elif provider == "local":
         return LocalProvider(**kwargs)
     else:
-        raise ValueError(f"Unknown LLM provider: '{provider}'. Supported: 'openai', 'local'")
+        raise ValueError(f"Unknown LLM provider: '{provider}'. Supported: 'openai', 'openrouter', 'local'")
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -33,7 +33,7 @@ services:
         condition: service_started
     volumes:
       - etl-containers-shared-data:/app/data         # Shared Volume between containers for data
-      - etl-data-airflow:/opt/airflow                # Volume for persistence of Airflow data
+      - etl-airflow-data:/opt/airflow                # Volume for persistence of Airflow data
       - ./airflow/dags:/opt/airflow/dags             # Mount the local folder 'dags' in the container
       - ./preparator:/opt/airflow/preparator         # Mount the local folder 'preparator' in the container
     ports:
@@ -280,6 +280,8 @@ services:
       - LLM_PROVIDER=${LLM_PROVIDER:-openai}
       - OPENAI_API_KEY=${OPENAI_API_KEY:-}
       - OPENAI_MODEL=${OPENAI_MODEL:-gpt-4o-mini}
+      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY:-}
+      - OPENROUTER_MODEL=${OPENROUTER_MODEL:-meta-llama/llama-3.1-8b-instruct:free}
     volumes:
       - etl-containers-shared-data:/app/data
     ports:
@@ -300,6 +302,6 @@ networks:
 volumes:
   etl-containers-shared-data:
   etl-postgres-data:
-  etl-data-airflow:
+  etl-airflow-data:
   etl-grafana-data:
   etl-prometheus-data:
diff --git a/streamlit_app/Dockerfile b/streamlit_app/Dockerfile
@@ -2,6 +2,8 @@ FROM python:3.9-slim
 
 WORKDIR /app
 
+RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
+
 # Install dependencies
 COPY streamlit_app/requirements.txt /app/requirements.txt
 RUN pip install --no-cache-dir -r requirements.txt
diff --git a/streamlit_app/app.py b/streamlit_app/app.py
@@ -80,15 +80,44 @@ def render_sidebar():
         # LLM Provider selector
         provider = st.selectbox(
             "LLM Provider",
-            ["openai", "local"],
-            help="OpenAI requires OPENAI_API_KEY env var. Local uses the HuggingFace service.",
+            ["openai", "openrouter", "local"],
+            help=(
+                "**OpenAI**: requires OPENAI_API_KEY (paid).  \n"
+                "**OpenRouter**: gateway to 200+ models, including free ones — "
+                "get a key at https://openrouter.ai/keys.  \n"
+                "**Local**: uses the HuggingFace text-completion-llm-service (requires model download)."
+            ),
         )
 
         if provider == "openai":
             api_key = st.text_input("OpenAI API Key", type="password", value=os.getenv("OPENAI_API_KEY", ""))
             if api_key:
                 os.environ["OPENAI_API_KEY"] = api_key
 
+        elif provider == "openrouter":
+            or_key = st.text_input(
+                "OpenRouter API Key", type="password",
+                value=os.getenv("OPENROUTER_API_KEY", ""),
+                help="Free key at https://openrouter.ai/keys",
+            )
+            if or_key:
+                os.environ["OPENROUTER_API_KEY"] = or_key
+
+            or_model = st.selectbox(
+                "Model",
+                [
+                    "meta-llama/llama-3.1-8b-instruct:free",
+                    "google/gemma-2-9b-it:free",
+                    "mistralai/mistral-7b-instruct:free",
+                    "qwen/qwen-2.5-7b-instruct:free",
+                    "meta-llama/llama-3.3-70b-instruct",
+                    "anthropic/claude-3.5-sonnet",
+                    "openai/gpt-4o-mini",
+                ],
+                help="Models ending in `:free` require no credits.",
+            )
+            os.environ["OPENROUTER_MODEL"] = or_model
+
         st.divider()
 
         # Chat messages
