Skip to content

Runtime and Configuration Contract

Overview

This document outlines the strict runtime and configuration contract for the BacMR backend, enforced across all environments.

Runtime Baseline

  • Python Version: Python 3.12 (standardized via Dockerfile and slim images).

Configuration Contract

The application strictly defines and expects the following environment variables. In production, these are enforced via a preflight check during application startup.

Core Variables

  • ENV: The runtime environment (e.g., local, prod). If set to prod or production, strict validation is enforced.
  • OPENAI_API_KEY: Required for embeddings, reranking, and LLM completions.
  • SUPABASE_URL: Required for the PostgreSQL database connection and vector storage.
  • SUPABASE_SERVICE_ROLE_KEY (or SUPABASE_SERVICE_KEY): Required for backend administrative access to Supabase.
  • SUPABASE_JWT_SECRET: Required for validating client requests (can be optional depending on strict endpoints, but typically expected).

Optional / Defaulted Settings

  • AI Models: OPENAI_CHAT_MODEL, OPENAI_REASONING_MODEL, OPENAI_RERANK_MODEL, OPENAI_EMBEDDING_MODEL, EMBEDDING_DIMENSIONS.
  • RAG Parameters: CHUNK_SIZE, CHUNK_OVERLAP, RETRIEVAL_TOP_K, RERANK_TOP_N.
  • Translations: TRANSLATION_PROVIDER, GOOGLE_TRANSLATE_API_KEY, GOOGLE_TRANSLATE_PROJECT_ID.
  • Application Logic: BASE_CHAT_COST, TOKEN_BUFFER, STALE_JOB_TIMEOUT_MINUTES, CORS_ALLOWED_ORIGINS.

Preflight Checks

The app.core.config.Settings class utilizes a Pydantic model_validator to ensure that when ENV=prod, critical variables (OPENAI_API_KEY, SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY) are present and not set to placeholder dummy values (e.g., "your_openai_api_key"). If this validation fails, the application explicitly raises a ValueError during startup to fail fast and prevent silent misconfigurations.