fix: replace OpenAI SDK with raw HTTP to avoid Cloudflare WAF blocking, broaden exception handling, align vector dimensions at startup

Problem
- The OpenAI Python SDK (AsyncOpenAI) injects x-stainless-* telemetry headers into
  every request. Cloudflare-proxied OpenAI-compatible endpoints block these, causing
  embedding generation to fail with PermissionDeniedError. These exceptions are not
  ValueError subclasses, so they bypassed the except ValueError handler and became
  unhandled HTTP 500 errors.
- pgvector column dimension mismatch between migration default (1536) and runtime
  config caused unhandled DataError on insert.
- Missing broad exception catch around embedding calls in document CRUD.

Changes
- src/embedding_client.py: Replace AsyncOpenAI with raw httpx.AsyncClient POST
  requests, sending only Authorization and Content-Type headers.
- src/crud/document.py: Add DataError alongside IntegrityError; add broad
  except Exception catch around embedding call → ValidationException (422).
- docker/entrypoint.sh: Add scripts/configure_embeddings.py --yes step after
  migration to auto-align pgvector dimensions to current config.
- tests/: Update all hardcoded 1536-dimension test vectors to use
  settings.EMBEDDING.VECTOR_DIMENSIONS across 6 test files (47 occurrences).

Testing
- Manual: create conclusion with session_id, without session_id, self-conclusion
  all return HTTP 201 instead of 500.
- Unit: 27/27 conclusion route tests pass.
- CI: ruff check, basedpyright, pytest pass.

Author: hungcuong9125

docker/entrypoint.sh

@@ -4,5 +4,9 @@ set -e
 echo "Running database migrations..."
 /app/.venv/bin/python scripts/provision_db.py
 
+# Align vector dimensions after migration (migration hardcodes Vector(1536))
+echo "Configuring embedding dimensions..."
+/app/.venv/bin/python scripts/configure_embeddings.py --yes
+
 echo "Starting API server..."
 exec /app/.venv/bin/fastapi run --host 0.0.0.0 src/main.py

src/crud/document.py

@@ -5,7 +5,7 @@
 
 from sqlalchemy import delete, select, update
 from sqlalchemy.engine import CursorResult
-from sqlalchemy.exc import IntegrityError
+from sqlalchemy.exc import DataError, IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.sql import Select
 from sqlalchemy.sql.functions import func
@@ -893,6 +893,10 @@ async def create_observations(
         embeddings = await embedding_client.simple_batch_embed(contents)
     except ValueError as e:
         raise ValidationException(str(e)) from e
+    except Exception as e:
+        raise ValidationException(
+            f"Failed to generate embeddings: {e}"
+        ) from e
 
     # Create document objects and track embeddings for vector store
     honcho_documents: list[models.Document] = []
@@ -1039,10 +1043,10 @@ async def create_observations(
                     )
                     await db.commit()
 
-    except IntegrityError as e:
+    except (DataError, IntegrityError) as e:
         await db.rollback()
         raise ValidationException(
-            "Failed to create observations due to integrity constraint violation"
+            "Failed to create observations due to a data or integrity constraint violation"
         ) from e
 
     logger.debug(

src/embedding_client.py

@@ -6,11 +6,11 @@
 from collections.abc import Awaitable, Callable
 from typing import Any, Literal, NamedTuple, TypeVar
 
+import httpx
 import tiktoken
 from google import genai
 from google.genai import types as genai_types
 from nanoid import generate as generate_nanoid
-from openai import AsyncOpenAI
 
 from .config import EmbeddingModelConfig, resolve_embedding_model_config, settings
 
@@ -187,7 +187,7 @@ def __init__(
                 if config.base_url
                 else None
             )
-            self.client: genai.Client | AsyncOpenAI = genai.Client(
+            self.client: genai.Client | httpx.AsyncClient = genai.Client(
                 api_key=config.api_key,
                 http_options=http_options,
             )
@@ -198,9 +198,12 @@ def __init__(
         else:  # openai
             if not config.api_key:
                 raise ValueError("OpenAI API key is required")
-            self.client = AsyncOpenAI(
-                api_key=config.api_key,
-                base_url=config.base_url,
+            if not config.base_url:
+                raise ValueError("OpenAI base URL is required")
+            self._openai_api_key: str = config.api_key
+            self._openai_base_url: str = config.base_url.rstrip("/")
+            self.client = httpx.AsyncClient(
+                timeout=httpx.Timeout(120.0, connect=30.0),
             )
             self.max_embedding_tokens = max_input_tokens
             self.max_batch_size = 2048  # OpenAI batch limit
@@ -257,14 +260,26 @@ async def _call_gemini() -> list[float]:
                 fn=_call_gemini,
             )
 
-        openai_client = self.client
+        http_client: httpx.AsyncClient = self.client  # type: ignore[assignment]
 
         async def _call_openai() -> list[float]:
-            openai_kwargs: dict[str, Any] = {"model": self.model, "input": [query]}
+            payload: dict[str, Any] = {"model": self.model, "input": [query]}
             if self.send_dimensions:
-                openai_kwargs["dimensions"] = self.vector_dimensions
-            response = await openai_client.embeddings.create(**openai_kwargs)
-            return self._validate_embedding_dimensions(response.data[0].embedding)
+                payload["dimensions"] = self.vector_dimensions
+            resp = await http_client.post(
+                f"{self._openai_base_url}/embeddings",
+                json=payload,
+                headers={
+                    "Authorization": f"Bearer {self._openai_api_key}",
+                    "Content-Type": "application/json",
+                },
+            )
+            if not resp.is_success:
+                raise RuntimeError(
+                    f"Embedding API error: {resp.status_code} {resp.text}"
+                )
+            data = resp.json()
+            return self._validate_embedding_dimensions(data["data"][0]["embedding"])
 
         return await _emit_embedding_call(
             provider=self.transport,
@@ -460,16 +475,29 @@ async def _call_provider() -> dict[str, dict[int, list[float]]]:
                                 self._validate_embedding_dimensions(embedding.values)
                             )
             else:  # openai
-                openai_kwargs: dict[str, Any] = {
+                http_client: httpx.AsyncClient = self.client  # type: ignore[assignment]
+                payload: dict[str, Any] = {
                     "model": self.model,
                     "input": [item.text for item in batch],
                 }
                 if self.send_dimensions:
-                    openai_kwargs["dimensions"] = self.vector_dimensions
-                response = await self.client.embeddings.create(**openai_kwargs)
-                for item, embedding_data in zip(batch, response.data, strict=True):
+                    payload["dimensions"] = self.vector_dimensions
+                resp = await http_client.post(
+                    f"{self._openai_base_url}/embeddings",
+                    json=payload,
+                    headers={
+                        "Authorization": f"Bearer {self._openai_api_key}",
+                        "Content-Type": "application/json",
+                    },
+                )
+                if not resp.is_success:
+                    raise RuntimeError(
+                        f"Embedding API error: {resp.status_code} {resp.text}"
+                    )
+                resp_data = resp.json()
+                for item, emb in zip(batch, resp_data["data"], strict=True):
                     result[item.text_id][item.chunk_index] = (
-                        self._validate_embedding_dimensions(embedding_data.embedding)
+                        self._validate_embedding_dimensions(emb["embedding"])
                     )
             return result
 

tests/alembic/revisions/test_b8183c5ffb48_codify_document_level_and_times_derived.py

@@ -7,6 +7,7 @@
 from nanoid import generate as generate_nanoid
 from sqlalchemy import text
 
+from src.config import settings
 from tests.alembic.registry import register_after_upgrade, register_before_upgrade
 from tests.alembic.verifier import MigrationVerifier
 
@@ -95,7 +96,7 @@ def prepare_codify_document_level_and_times_derived(
             "id": generate_nanoid(),
             "content": "Document with explicit level and times_derived=3",
             "metadata": json.dumps({"level": "explicit", "times_derived": 3}),
-            "embedding": [0.1] * 1536,
+            "embedding": [0.1] * settings.EMBEDDING.VECTOR_DIMENSIONS,
             "observer": OBSERVER_NAME,
             "observed": OBSERVED_NAME,
             "ws_name": WORKSPACE_NAME,
@@ -114,7 +115,7 @@ def prepare_codify_document_level_and_times_derived(
             "id": generate_nanoid(),
             "content": "Document with deductive level and times_derived=5",
             "metadata": json.dumps({"level": "deductive", "times_derived": 5}),
-            "embedding": [0.2] * 1536,
+            "embedding": [0.2] * settings.EMBEDDING.VECTOR_DIMENSIONS,
             "observer": OBSERVER_NAME,
             "observed": OBSERVED_NAME,
             "ws_name": WORKSPACE_NAME,
@@ -133,7 +134,7 @@ def prepare_codify_document_level_and_times_derived(
             "id": generate_nanoid(),
             "content": "Document without level or times_derived fields",
             "metadata": json.dumps({"other_field": "value"}),
-            "embedding": [0.3] * 1536,
+            "embedding": [0.3] * settings.EMBEDDING.VECTOR_DIMENSIONS,
             "observer": OBSERVER_NAME,
             "observed": OBSERVED_NAME,
             "ws_name": WORKSPACE_NAME,
@@ -152,7 +153,7 @@ def prepare_codify_document_level_and_times_derived(
             "id": generate_nanoid(),
             "content": "Document with only level field",
             "metadata": json.dumps({"level": "explicit"}),
-            "embedding": [0.4] * 1536,
+            "embedding": [0.4] * settings.EMBEDDING.VECTOR_DIMENSIONS,
             "observer": OBSERVER_NAME,
             "observed": OBSERVED_NAME,
             "ws_name": WORKSPACE_NAME,
@@ -171,7 +172,7 @@ def prepare_codify_document_level_and_times_derived(
             "id": generate_nanoid(),
             "content": "Document with only times_derived field",
             "metadata": json.dumps({"times_derived": 7}),
-            "embedding": [0.5] * 1536,
+            "embedding": [0.5] * settings.EMBEDDING.VECTOR_DIMENSIONS,
             "observer": OBSERVER_NAME,
             "observed": OBSERVED_NAME,
             "ws_name": WORKSPACE_NAME,
@@ -292,7 +293,7 @@ def verify_codify_document_level_and_times_derived(verifier: MigrationVerifier)
             "id": new_doc_id,
             "content": "New document after migration",
             "metadata": json.dumps({}),
-            "embedding": [0.6] * 1536,
+            "embedding": [0.6] * settings.EMBEDDING.VECTOR_DIMENSIONS,
             "observer": OBSERVER_NAME,
             "observed": OBSERVED_NAME,
             "ws_name": WORKSPACE_NAME,