feat(api): pre-wire otel genai instrumentation

Add OpenTelemetry GenAI semantic-convention instrumentation (semconv
2026-Q2, Development status) to the API template:

- src/lib/ai/telemetry.py: guarded auto-instrumentation for the official
  OpenAI/Google GenAI SDKs plus a manual genai_span() helper emitting
  spec-compliant spans and gen_ai.client.* metrics for custom providers
- src/lib/telemetry.py: add Meter and Logger providers (was traces-only),
  set GenAI semconv stability/content env defaults, move resource to
  deployment.environment.name
- config + .env.example: OTEL_GENAI_CAPTURE_MESSAGE_CONTENT (PII-safe off)
- pyproject: optional, mutually-exclusive genai-openai/genai-google extras

Co-Authored-By: First Fluke <our.first.fluke@gmail.com>

Author: gracefullight

apps/api/.env.example

@@ -19,10 +19,16 @@ JWE_SECRET_KEY=your-super-secret-jwe-encryption-key-change-in-production
 # Redis (optional)
 REDIS_URL=redis://localhost:6379
 
-# OpenTelemetry (optional - for production tracing)
+# OpenTelemetry (optional - for production tracing & metrics)
 # OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
 # OTEL_SERVICE_NAME=fullstack-starter-api
 
+# OpenTelemetry GenAI (LLM observability - OTel GenAI semconv).
+# Prompt/completion content is PII-sensitive: "off" records only metadata
+# (model, token usage, latency). Set to span_only/event_only/span_and_event to
+# capture message content. Auto-enables OTEL_SEMCONV_STABILITY_OPT_IN.
+# OTEL_GENAI_CAPTURE_MESSAGE_CONTENT=off
+
 # AI (optional)
 AI_PROVIDER=gemini
 GOOGLE_CLOUD_PROJECT=

apps/api/pyproject.toml

@@ -27,6 +27,15 @@ dependencies = [
     "bcrypt>=5.0.0",
 ]
 
+# Optional GenAI SDK auto-instrumentation (OTel GenAI semconv).
+# Install the one matching AI_PROVIDER, e.g. `uv sync --extra genai-openai`.
+# NOTE: as of 2026-Q2 these two cannot be installed together — openai-v2 pins
+# opentelemetry-util-genai>=0.4b0 while google-genai pins <0.4b0. The runtime
+# (src/lib/ai/telemetry.py) import-guards both, so absence is a safe no-op.
+[project.optional-dependencies]
+genai-openai = ["opentelemetry-instrumentation-openai-v2>=2.4b0"]
+genai-google = ["opentelemetry-instrumentation-google-genai>=0.7b1"]
+
 [dependency-groups]
 dev = [
     "ruff>=0.15.16",
@@ -41,6 +50,9 @@ dev = [
 
 [tool.uv]
 managed = true
+# openai-v2 and google-genai pin incompatible opentelemetry-util-genai ranges
+# (2026-Q2); declare them mutually exclusive so each resolves independently.
+conflicts = [[{ extra = "genai-openai" }, { extra = "genai-google" }]]
 
 [tool.poe.tasks]
 dev = "fastapi dev src/main.py --port 8000"
@@ -88,3 +100,11 @@ ignore_missing_imports = true
 [[tool.mypy.overrides]]
 module = ["jwcrypto.*"]
 ignore_missing_imports = true
+
+# Optional GenAI auto-instrumentation packages (installed via extras only).
+[[tool.mypy.overrides]]
+module = [
+    "opentelemetry.instrumentation.openai_v2.*",
+    "opentelemetry.instrumentation.google_genai.*",
+]
+ignore_missing_imports = true

apps/api/src/lib/ai/__init__.py

@@ -0,0 +1,25 @@
+"""AI provider abstraction and OTel GenAI instrumentation helpers."""
+
+from src.lib.ai.base import AIProvider
+from src.lib.ai.telemetry import (
+    GenAIAttr,
+    GenAIOperation,
+    GenAIProvider,
+    GenAISpanHandle,
+    genai_span,
+    init_genai_metrics,
+    instrument_genai_sdks,
+    provider_name,
+)
+
+__all__ = [
+    "AIProvider",
+    "GenAIAttr",
+    "GenAIOperation",
+    "GenAIProvider",
+    "GenAISpanHandle",
+    "genai_span",
+    "init_genai_metrics",
+    "instrument_genai_sdks",
+    "provider_name",
+]