Merge pull request #219 from AaronMT/vector-update

llm-cloud-run: Vector RAG Skeleton

Author: AaronMT

.github/workflows/deploy-cloudrun.yml

@@ -0,0 +1,70 @@
+name: Deploy to Cloud Run
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ "main" ]   # change if you deploy from a different branch
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    # IMPORTANT: set this to your GitHub Environment name (e.g., "dev", "prod", "vertex-hack")
+    environment: vertex-hack
+
+    env:
+      # Repo/global (or environment) variables
+      GCP_PROJECT_ID: ${{ vars.GCP_PROJECT_ID }}
+      GCP_REGION: ${{ vars.GCP_REGION }}
+      CLOUD_RUN_SERVICE: ${{ vars.CLOUD_RUN_SERVICE }}
+
+      # Image naming (Artifact Registry)
+      AR_REPO: ${{ vars.AR_REPO }}              # e.g. "llm"
+      AR_IMAGE: ${{ vars.AR_IMAGE }}            # e.g. "gemini-llm"
+      IMAGE_URI: ${{ vars.GCP_REGION }}-docker.p
+
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Authenticate to Google Cloud (JSON key)
+        uses: google-github-actions/auth@v3
+        with:
+          credentials_json: ${{ secrets.GCP_SA_VERTEX_AI }}
+
+      - name: Setup gcloud
+        uses: google-github-actions/setup-gcloud@v3
+        with:
+          project_id: ${{ env.GCP_PROJECT_ID }}
+
+      - name: Configure gcloud project
+        run: gcloud --quiet config set project "${GCP_PROJECT_ID}"
+
+      - name: Build container image with Cloud Build
+        run: |
+          set -euo pipefail
+          gcloud builds submit --tag "${IMAGE_URI}"
+
+      - name: Deploy to Cloud Run
+        run: |
+          set -euo pipefail
+
+          # Build env var string from GitHub Environment variables
+          ENV_VARS="PIPELINE_MODE=${{ vars.PIPELINE_MODE }},ENABLE_BQ_WRITE=${{ vars.ENABLE_BQ_WRITE }},BQ_DATASET=${{ vars.BQ_DATASET }},BQ_NOTES_TABLE=${{ vars.BQ_NOTES_TABLE }},VERTEX_LOCATION=${{ vars.VERTEX_LOCATION }},VERTEX_EMBEDDING_MODEL=${{ vars.VERTEX_EMBEDDING_MODEL }},VERTEX_LLM_MODEL=${{ vars.VERTEX_LLM_MODEL }},LOG_LEVEL=${{ vars.LOG_LEVEL }},DEBUG_RAG=${{ vars.DEBUG_RAG }}"
+
+          gcloud run deploy "${CLOUD_RUN_SERVICE}" \
+            --image "${IMAGE_URI}" \
+            --region "${GCP_REGION}" \
+            --platform managed \
+            --set-env-vars "${ENV_VARS}"
+
+      - name: Show service URL
+        run: |
+          set -euo pipefail
+          gcloud run services describe "${CLOUD_RUN_SERVICE}" \
+            --region "${GCP_REGION}" \
+            --format="value(status.url)"

llm-cloud-run/.dockerignore

@@ -1,7 +1,9 @@
-# Vim artifacts
-*.sw?
-.*.sw?
-*~ 
-4913
-
-.DS_Store
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+.venv
+venv
+.git
+.pytest_cache

llm-cloud-run/Dockerfile

@@ -1,13 +1,14 @@
-FROM python:3.13-slim
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
 
 WORKDIR /app
 
 COPY requirements.txt .
-
 RUN pip install --no-cache-dir -r requirements.txt
 
 COPY . .
 
-EXPOSE 8080
-
-CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]
+ENV PORT=8080
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

llm-cloud-run/common/__init__.py

@@ -0,0 +1,53 @@
+import os
+from dataclasses import dataclass
+
+
+def _env(name: str, default: str | None = None) -> str | None:
+    v = os.getenv(name)
+    if v is None or v == "":
+        return default
+    return v
+
+
+@dataclass(frozen=True)
+class Settings:
+    # GCP / Vertex
+    gcp_project: str | None = _env("GCP_PROJECT") or _env("GOOGLE_CLOUD_PROJECT")
+    gcp_location: str = _env("GCP_LOCATION", "us-central1") or "us-central1"
+
+    # BigQuery
+    bq_project: str | None = _env("BQ_PROJECT")  # optional; defaults to gcp_project
+    bq_dataset: str = _env("BQ_DATASET", "vertex_rag_demo") or "vertex_rag_demo"
+    bq_notes_table: str = _env("BQ_NOTES_TABLE", "demo_Notes") or "demo_Notes"
+    bq_embeddings_table: str = _env("BQ_EMBEDDINGS_TABLE", "demo_NoteEmbeddings") or "demo_NoteEmbeddings"
+
+    # Column names (override if your schema differs)
+    notes_id_col: str = _env("NOTES_ID_COL", "note_id") or "note_id"
+    notes_content_col: str = _env("NOTES_CONTENT_COL", "content") or "content"
+    notes_source_col: str = _env("NOTES_SOURCE_COL", "source") or "source"
+    notes_created_col: str = _env("NOTES_CREATED_COL", "created_at") or "created_at"
+
+    emb_id_col: str = _env("EMB_ID_COL", "note_id") or "note_id"
+    emb_vector_col: str = _env("EMB_VECTOR_COL", "embedding") or "embedding"  # ARRAY<FLOAT64>
+    emb_model_col: str = _env("EMB_MODEL_COL", "model") or "model"
+    emb_updated_col: str = _env("EMB_UPDATED_COL", "updated_at") or "updated_at"
+
+    # RAG settings
+    rag_top_k: int = int(_env("RAG_TOP_K", "3") or "3")
+    snippet_chars: int = int(_env("RAG_SNIPPET_CHARS", "800") or "800")
+
+    # LLM + Embeddings
+    gemini_model: str = _env("GEMINI_MODEL", "gemini-2.5-flash-lite") or "gemini-2.5-flash-lite"
+    embedding_model: str = _env("EMBEDDING_MODEL", "text-embedding-004") or "text-embedding-004"
+
+    # Optional: cap how many notes to load into memory cache
+    bq_max_notes: int = int(_env("BQ_MAX_NOTES", "5000") or "5000")
+
+    @property
+    def effective_bq_project(self) -> str | None:
+        return self.bq_project or self.gcp_project
+
+    def require_project(self) -> str:
+        if not self.gcp_project:
+            raise RuntimeError("GCP_PROJECT / GOOGLE_CLOUD_PROJECT not set.")
+        return self.gcp_project

llm-cloud-run/common/config.py

@@ -0,0 +1,10 @@
+import logging
+import os
+
+
+def setup_logging() -> None:
+    level = os.getenv("LOG_LEVEL", "INFO").upper()
+    logging.basicConfig(
+        level=getattr(logging, level, logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s - %(message)s",
+    )

llm-cloud-run/common/logging_utils.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import List
+from vertexai.language_models import TextEmbeddingModel
+
+from common.config import Settings
+from llm.vertex_init import init_vertex
+
+_MODEL: TextEmbeddingModel | None = None
+
+
+def embed_text(settings: Settings, text: str) -> List[float]:
+    """Return an embedding vector for given text using Vertex Embeddings."""
+    global _MODEL
+    init_vertex(settings)
+    if _MODEL is None:
+        _MODEL = TextEmbeddingModel.from_pretrained(settings.embedding_model)
+    return _MODEL.get_embeddings([text])[0].values

llm-cloud-run/llm/__init__.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from vertexai.preview.generative_models import GenerativeModel, Part
+
+from common.config import Settings
+from llm.vertex_init import init_vertex
+
+
+def generate(
+    settings: Settings,
+    parts: list[Part] | Part,
+    *,
+    temperature: float = 0.3,
+    max_output_tokens: int = 1024,
+) -> str:
+    """
+    Generate text using a Gemini model on Vertex AI.
+
+    `parts` can be:
+      - a single Part (text or image)
+      - a list of Parts (multimodal prompt)
+    """
+    init_vertex(settings)
+
+    model = GenerativeModel(settings.gemini_model)
+
+    response = model.generate_content(
+        parts,
+        generation_config={
+            "temperature": temperature,
+            "max_output_tokens": max_output_tokens,
+        },
+    )
+
+    # Vertex responses expose `.text` for convenience
+    return getattr(response, "text", "") or ""

llm-cloud-run/llm/embeddings.py

@@ -0,0 +1,21 @@
+import logging
+import vertexai
+from common.config import Settings
+
+_INITIALIZED = False
+
+
+def init_vertex(settings: Settings) -> None:
+    """Initialize Vertex AI once per process."""
+    global _INITIALIZED
+    if _INITIALIZED:
+        return
+
+    project = settings.require_project()
+    vertexai.init(project=project, location=settings.gcp_location)
+    logging.getLogger(__name__).info(
+        "Vertex AI initialized (project=%s, location=%s).",
+        project,
+        settings.gcp_location,
+    )
+    _INITIALIZED = True