feat(generator): add generator adapters with OpenAI, Ollama, and mock implementations

Author: kernelshard

app/core/config.py

@@ -1,6 +1,8 @@
 from pydantic import Field
 from pydantic_settings import BaseSettings
 
+from app.core.constants import GeneratorBackend
+
 
 class Settings(BaseSettings):
     APP_NAME: str = "rag_mastery"
@@ -9,12 +11,15 @@ class Settings(BaseSettings):
     LOG_LEVEL: str = Field(default="INFO", alias="LOG_LEVEL")
     HOST: str = Field(default="0.0.0.0", alias="HOST")
     PORT: int = Field(default=8000, alias="PORT")
+    USE_REAL_GENERATOR: bool = False
+    GENERATOR_BACKEND: GeneratorBackend = GeneratorBackend.Mock
 
     model_config = {
         "env_file": ".env",
         "env_file_encoding": "utf-8",
         "extra": "ignore",
         "populate_by_name": True,  # allowing alias mapping
+        "use_enum_values": True,  # store enum values directly
     }
 
 

app/core/constants.py

@@ -1,6 +1,7 @@
 from enum import StrEnum
 
 
+# Ingestion status constants used across the application
 class IngestionStatus(StrEnum):
     Accepted = "accepted"
     Processing = "processing"
@@ -9,3 +10,14 @@ class IngestionStatus(StrEnum):
 
 
 DefaultTopK: int = 5
+
+
+class GeneratorBackend(StrEnum):
+    """
+    Supported generator backends.
+    Reason: to avoid hardcoding strings across the codebase.
+    """
+
+    Mock = "mock"
+    OPENAI = "openai"
+    Ollama = "ollama"

app/core/metrics.py

@@ -1,7 +1,7 @@
 import os
 
 from fastapi import Response
-from prometheus_client import CONTENT_TYPE_LATEST, Counter, generate_latest
+from prometheus_client import CONTENT_TYPE_LATEST, Counter, generate_latest, Histogram
 
 # Identify which service (ingestion, retrieval, generation, etc.)
 APP_NAME = os.getenv("APP_NAME", "rag_architect")
@@ -19,6 +19,20 @@
     ["app_name", "method", "endpoint", "http_status"],  # metric dimensions
 )
 
+# Prompt build duration histogram
+APP_PROMPT_BUILD_SECONDS = Histogram(
+    "app_prompt_build_seconds",
+    "Time taken to build prompts",
+    ["app_name"],
+)
+
+# LLM generation latency histogram
+APP_GENERATION_LATENCY_SECONDS = Histogram(
+    "app_generation_latency_seconds",
+    "Time taken for LLM answer generation",
+    ["app_name"],
+)
+
 
 def record_request(method: str, endpoint: str, http_status: str):
     """

app/generation/adapters/ollama_adapter.py

@@ -0,0 +1,21 @@
+import asyncio
+from app.core.interfaces import BaseGenerator
+from app.core.logging import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class OllamaGenerator(BaseGenerator):
+    """
+    Async adapter for Ollama-style LLMs.
+    """
+
+    def __init__(self, model_name: str = "llama3"):
+        self.model_name = model_name
+
+    async def generate(self, prompt: str) -> str:
+        logger.debug(f"[OllamaGenerator] Would call model={self.model_name}")
+        await asyncio.sleep(0.5)  # simulate network delay
+        # Placeholder for actual Ollama API call
+        return f"[Simulated Ollama: {self.model_name} for prompt: {prompt[:60]}...]"

app/generation/adapters/openai_adapter.py

@@ -0,0 +1,21 @@
+import asyncio
+
+from app.core.interfaces import BaseGenerator
+from app.core.logging import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class OpenAIGenerator(BaseGenerator):
+    """
+    Async adapter for OpenAI-style LLMs.
+    """
+
+    def __init__(self, model_name: str = "gpt-4-turbo"):
+        self.model_name = model_name
+
+    async def generate(self, prompt: str) -> str:
+        logger.debug(f"[OpenAIGenerator] would call model={self.model_name}")
+        await asyncio.sleep(0.5)  # simulate network delay
+        return f"[Simulated OpenAI: {self.model_name} for prompt: {prompt[:60]}...]"

app/generation/api.py

@@ -1,8 +1,8 @@
 from fastapi import APIRouter, status, Depends
 
-from app.core.interfaces import BaseRetriever
+from app.core.interfaces import BaseGenerator, BaseRetriever
 from app.core.logging import get_logger
-from app.generation.deps import get_retriever
+from app.generation.deps import get_generator, get_retriever
 from app.generation.models import GenerationRequest, GenerationResponse
 from app.generation.service import generate_answer
 
@@ -18,9 +18,11 @@
     summary="Generate answer based on query and retrieved contexts",
 )
 async def generate_endpoint(
-    req: GenerationRequest, retriever: BaseRetriever = Depends(get_retriever)
+    req: GenerationRequest,
+    retriever: BaseRetriever = Depends(get_retriever),
+    generator: BaseGenerator = Depends(get_generator),
 ):
     logger.info(
         "Received generation request", query=req.query, context_size=req.context_size
     )
-    return await generate_answer(req, retriever)
+    return await generate_answer(req, retriever, generator)

app/generation/deps.py

@@ -1,8 +1,11 @@
+from app.core.constants import GeneratorBackend
 from app.core.interfaces import BaseRetriever
+from app.generation.adapters.ollama_adapter import OllamaGenerator
 from app.generation.mock_generator import MockGenerator
 from app.retrieval.models import RetrievalRequest
 from app.retrieval.service import retrieve_documents
 from app.core.repositories import global_vector_repo
+from app.core.config import settings
 
 
 class RetrievalAdapter(BaseRetriever):
@@ -35,6 +38,20 @@ def get_retriever() -> BaseRetriever:
     return _retriever
 
 
-async def get_generator():
-    # swap with real generator later
-    yield MockGenerator()
+async def get_generator(
+    use_real: bool = settings.USE_REAL_GENERATOR,
+    backend: GeneratorBackend = settings.GENERATOR_BACKEND,
+):
+    """
+    Returns a generator instance based on configuration.
+    """
+    # precedence wise use_real overrides backend
+    if not use_real:
+        yield MockGenerator()
+    else:
+        if backend == GeneratorBackend.Mock:
+            yield MockGenerator()
+        elif backend == GeneratorBackend.Ollama:
+            yield OllamaGenerator()
+        else:
+            yield OllamaGenerator()  # Default to OllamaGenerator for now

app/generation/models.py

@@ -20,7 +20,7 @@ class GenerateAnswer(BaseModel):
     """
 
     text: str
-    used_contexts: list[dict[str, Any]]
+    used_context: list[dict[str, Any]]
 
 
 class GenerationResponse(BaseModel):

app/generation/service.py

@@ -1,15 +1,19 @@
+import time
 from app.core.logging import get_logger
+from app.core.metrics import APP_NAME, APP_PROMPT_BUILD_SECONDS
 from app.generation.models import GenerateAnswer, GenerationRequest, GenerationResponse
 from app.generation.prompt_builder import build_prompt
 
-from app.core.interfaces import BaseRetriever
+from app.core.interfaces import BaseGenerator, BaseRetriever
 
 
 logger = get_logger(__name__)
 
 
 async def generate_answer(
-    req: GenerationRequest, retriever: BaseRetriever
+    req: GenerationRequest,
+    retriever: BaseRetriever,
+    generator: BaseGenerator,
 ) -> GenerationResponse:
     """
     generate handles the text generation process by retrieving relevant documents
@@ -36,20 +40,22 @@ async def generate_answer(
     """
     logger.debug(f"Retrieved {len(retrieved_chunks)} chunks")
 
-    _ = build_prompt(req.query, retrieved_chunks)
+    # prompt build metrics
+    t0 = time.monotonic()
+    prompt = build_prompt(req.query, retrieved_chunks)
+    APP_PROMPT_BUILD_SECONDS.labels(app_name=APP_NAME).observe(time.monotonic() - t0)
 
-    synthesized = (
-        " ".join(chunk["doc_id"] for chunk in retrieved_chunks) or "No context found."
-    )
+    # Generation latency metrics
+    t1 = time.monotonic()
+    answer_text = await generator.generate(prompt=prompt)
+    APP_PROMPT_BUILD_SECONDS.labels(app_name=APP_NAME).observe(time.monotonic() - t1)
 
-    logger.info(
-        f"Generated answer for query='{req.query}' using {len(retrieved_chunks)}"
-    )
+    logger.info(f"Generated answer for query='{req.query}'")
 
     return GenerationResponse(
         query=req.query,
         answer=GenerateAnswer(
-            text=f"Mock answer: {synthesized}",
-            used_contexts=retrieved_chunks,
+            text=answer_text,
+            used_context=retrieved_chunks,
         ),
     )

tests/generation/test_deps.py

@@ -0,0 +1,34 @@
+from app.core.constants import GeneratorBackend
+from app.generation.adapters.ollama_adapter import OllamaGenerator
+from app.generation.deps import get_generator
+from app.generation.mock_generator import MockGenerator
+
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_get_generator_returns_mock_when_use_real_false_but_backend_not_provided():
+    """
+    When use_real is False and no backend is provided, should return MockGenerator.
+    """
+    gen = await anext(get_generator(use_real=False))
+    assert isinstance(gen, MockGenerator)
+
+
+@pytest.mark.asyncio
+async def test_get_generator_returns_mock_when_use_real_true_and_backend_mock():
+    """
+    When use_real is True and backend is Mock, should return MockGenerator.
+    """
+    gen = await anext(get_generator(use_real=True, backend=GeneratorBackend.Mock))
+    assert isinstance(gen, MockGenerator)
+
+
+@pytest.mark.asyncio
+async def test_get_generator_returns_ollama_when_use_real_false_and_backend_ollama():
+    """
+    When use_real is True and backend is Ollama, should return OllamaGenerator.
+    """
+    gen = await anext(get_generator(use_real=True, backend=GeneratorBackend.Ollama))
+    assert isinstance(gen, OllamaGenerator)