feat: OpenTelemetry LGTM observability, dev tooling, and memoir UX fixes (#31) (#32)

* add staging ios app build script

* feat(api): add OpenTelemetry LGTM stack for local observability

Wire OTel traces, metrics, and logs through a collector to Tempo,
Prometheus, and Loki, with custom LLM instrumentation, dev compose overlay,
Grafana provisioning, env templates, and development.sh auto-start.



* feat: expand observability, harden dev tooling, and fix expo staging UX

Add business and LLM Prometheus metrics with Grafana dashboards, alerting,
and a metrics verification script. Wire telemetry through adapters and core
LLM paths, and document the local LGTM workflow.

Fix development.sh for macOS bash 3.2, open Grafana and eval-web in Chrome,
and repair eval-web auto-open (unbound EVAL_WEB_BROWSER_SCHEDULED). Merge
internal-eval into the main dev script with improved compose handling.

Require EXPO_PUBLIC_* at build time, improve iOS HTTP ATS for staging IPs,
show memoir empty state instead of load errors when no chapters exist, and
add jest env setup plus chapter list response normalization.



* chore: enable Grafana Assistant Cursor plugin



* fix: memoir empty state and repair withdrawn 0020_chapters_book_id stamp

Show empty memoir UI when the chapter list succeeds with no items; treat auth/404 as non-fatal. Extend alembic revision repair so local dev DBs stamped with the removed 0020_chapters_book_id migration can roll back and upgrade to 0019.



---------

Co-authored-by: Kevin <kevin@brighteng.org>
Co-authored-by: Cursor <cursoragent@cursor.com>

api/app/adapters/asr/tencent_asr.py

@@ -3,6 +3,7 @@
 import asyncio
 import base64
 
+from app.core.business_telemetry import business_span
 from app.core.logging import get_logger
 from app.ports.asr import ASRTranscriptionError
 
@@ -39,6 +40,10 @@ class TencentASRProvider:
         return bool(self._secret_id and self._secret_key and self._get_client())
 
     async def transcribe(self, audio: bytes, format: str = "m4a") -> str:
+        with business_span("asr.transcribe", provider="tencent"):
+            return await self._transcribe_inner(audio, format)
+
+    async def _transcribe_inner(self, audio: bytes, format: str) -> str:
         client = self._get_client()
         if not client:
             raise ASRTranscriptionError(

api/app/adapters/asr/whisper_local.py

@@ -8,6 +8,7 @@ import re
 import tempfile
 from typing import Any, Iterable
 
+from app.core.business_telemetry import business_span
 from app.core.logging import get_logger
 from app.ports.asr import ASRTranscriptionError
 
@@ -102,6 +103,10 @@ class WhisperASRProvider:
         return self._load_model()
 
     async def transcribe(self, audio: bytes, format: str = "m4a") -> str:
+        with business_span("asr.transcribe", provider="whisper"):
+            return await self._transcribe_inner(audio, format)
+
+    async def _transcribe_inner(self, audio: bytes, format: str) -> str:
         # 与 v1.1.0 相同的单次 transcribe；推理放线程池，避免阻塞 asyncio（tag 上为同步调用）。
         self._load_model()
         if not self._model:

api/app/adapters/embedding/zhipu.py

@@ -6,6 +6,7 @@ import asyncio
 
 from zai import ZhipuAiClient
 
+from app.core.business_telemetry import business_span
 from app.core.embedding import MEMORY_EMBEDDING_DIMENSION
 from app.core.logging import get_logger
 
@@ -57,12 +58,13 @@ class ZhipuEmbeddingProvider:
     async def embed_texts(self, texts: list[str]) -> list[list[float]]:
         if not self._client or not texts:
             return []
-        out: list[list[float]] = []
-        for i in range(0, len(texts), _EMBED_BATCH_SIZE):
-            batch = texts[i : i + _EMBED_BATCH_SIZE]
-            part = await asyncio.to_thread(self._create_vectors_sync, batch)
-            out.extend(part)
-        return out
+        with business_span("embedding.zhipu.embed", batch_size=len(texts)):
+            out: list[list[float]] = []
+            for i in range(0, len(texts), _EMBED_BATCH_SIZE):
+                batch = texts[i : i + _EMBED_BATCH_SIZE]
+                part = await asyncio.to_thread(self._create_vectors_sync, batch)
+                out.extend(part)
+            return out
 
     def embed_text_sync(self, text: str) -> list[float]:
         vecs = self.embed_texts_sync([text])
@@ -71,8 +73,9 @@ class ZhipuEmbeddingProvider:
     def embed_texts_sync(self, texts: list[str]) -> list[list[float]]:
         if not self._client or not texts:
             return []
-        out: list[list[float]] = []
-        for i in range(0, len(texts), _EMBED_BATCH_SIZE):
-            batch = texts[i : i + _EMBED_BATCH_SIZE]
-            out.extend(self._create_vectors_sync(batch))
-        return out
+        with business_span("embedding.zhipu.embed", batch_size=len(texts)):
+            out: list[list[float]] = []
+            for i in range(0, len(texts), _EMBED_BATCH_SIZE):
+                batch = texts[i : i + _EMBED_BATCH_SIZE]
+                out.extend(self._create_vectors_sync(batch))
+            return out

api/app/adapters/llm/deepseek.py

@@ -4,6 +4,8 @@ from collections.abc import AsyncIterator
 
 from langchain_openai import ChatOpenAI
 
+from app.core.llm_telemetry import langchain_invoke_span, observe_astream
+
 
 class DeepSeekLLMProvider:
     """LangChain-based LLM adapter for DeepSeek and OpenAI-compatible APIs.
@@ -56,7 +58,15 @@ class DeepSeekLLMProvider:
     ) -> str:
         llm = self._get_llm(temperature, model, max_tokens)
         lc_messages = _to_langchain_messages(messages)
-        result = await llm.ainvoke(lc_messages)
+        resolved_model = model or self._default_model
+        with langchain_invoke_span(
+            agent="deepseek.complete",
+            provider="deepseek",
+            model=resolved_model,
+            call_type="chat",
+        ) as tel:
+            result = await llm.ainvoke(lc_messages)
+            tel["response"] = result
         return str(result.content)
 
     async def stream(
@@ -69,7 +79,14 @@ class DeepSeekLLMProvider:
     ) -> AsyncIterator[str]:
         llm = self._get_llm(temperature, model, max_tokens)
         lc_messages = _to_langchain_messages(messages)
-        async for chunk in llm.astream(lc_messages):
+        resolved_model = model or self._default_model
+        async for chunk in observe_astream(
+            llm,
+            lc_messages,
+            agent="deepseek.stream",
+            provider="deepseek",
+            model=resolved_model,
+        ):
             if chunk.content:
                 yield str(chunk.content)
 

api/app/adapters/sms/tencent.py

@@ -7,6 +7,7 @@ from tencentcloud.common.exception.tencent_cloud_sdk_exception import (
 from tencentcloud.sms.v20210111 import models as sms_models
 from tencentcloud.sms.v20210111 import sms_client
 
+from app.core.business_telemetry import business_span
 from app.core.logging import get_logger
 
 logger = get_logger(__name__)
@@ -32,6 +33,10 @@ class TencentSmsSender:
         self._template_param_count = template_param_count
 
     def send_verification_code(self, phone: str, code: str) -> bool:
+        with business_span("sms.tencent.send"):
+            return self._send_verification_code_inner(phone, code)
+
+    def _send_verification_code_inner(self, phone: str, code: str) -> bool:
         if not self._secret_id or not self._secret_key:
             logger.error("Tencent SMS credentials not configured")
             return False

api/app/adapters/tts/openai_tts.py

@@ -5,6 +5,7 @@ from io import BytesIO
 
 from openai import OpenAI
 
+from app.core.business_telemetry import business_span
 from app.core.logging import get_logger
 
 logger = get_logger(__name__)
@@ -35,6 +36,10 @@ class OpenAITTSProvider:
         *,
         language: str = "zh",  # noqa: ARG002 — OpenAI TTS auto-detects language
     ) -> bytes:
+        with business_span("tts.synthesize", provider="openai"):
+            return await self._synthesize_api(text, voice)
+
+    async def _synthesize_api(self, text: str, voice: str) -> bytes:
         if not self._client:
             return b""
         try:

api/app/adapters/tts/tencent_tts.py

@@ -5,6 +5,7 @@ import base64
 import re
 import uuid
 
+from app.core.business_telemetry import business_span
 from app.core.logging import get_logger
 
 logger = get_logger(__name__)
@@ -180,6 +181,16 @@ class TencentTTSProvider:
         voice: str = "alloy",
         *,
         language: str = "zh",
+    ) -> bytes:
+        with business_span("tts.synthesize", provider="tencent"):
+            return await self._synthesize_inner(text, voice, language=language)
+
+    async def _synthesize_inner(
+        self,
+        text: str,
+        voice: str = "alloy",
+        *,
+        language: str = "zh",
     ) -> bytes:
         if not self._secret_id or not self._secret_key:
             logger.error(