Python: generate-title + conversations count (#5302 Day 3) (#5382)

## Summary
Sub-PR A for #5302 Day 3: Python backend endpoints needed by desktop
app.

**Endpoints added:**
- `POST /v2/chat/generate-title` — LLM-powered chat session title
generation with graceful fallback
- `GET /v1/conversations/count` — Firestore aggregation count with
stream fallback

**Database layer:**
- `count_conversations()` — Firestore count() aggregation
- `stream_conversations()` — generator for unbounded counting fallback

## Test plan
- 23 unit tests across 2 test files (12 generate-title + 11
conversations-count)
- Both files in `test.sh`
- Coverage: success paths, auth, LLM fallback, boundary truncation
(50/100/500 chars), status parsing/normalization, aggregation fallback
parity, validation (empty, too many statuses)
- All 23 tests passing

## Review cycle
- CP7 reviewer: approved (3 rounds — fixed mutable default arg, statuses
validation, stream fallback)
- CP8 tester: approved (4 boundary tests added for coverage gaps)

Closes part of #5302

Author: beastoin

backend/database/conversations.py

@@ -219,6 +219,30 @@ def get_conversations(
     return conversations
 
 
+def count_conversations(uid: str, statuses: Optional[List[str]] = None) -> int:
+    """Count conversations matching status filters without fetching full documents."""
+    if statuses is None:
+        statuses = []
+    conversations_ref = db.collection('users').document(uid).collection(conversations_collection)
+    conversations_ref = conversations_ref.where(filter=FieldFilter('discarded', '==', False))
+    if statuses:
+        conversations_ref = conversations_ref.where(filter=FieldFilter('status', 'in', statuses))
+    count_query = conversations_ref.count()
+    results = count_query.get()
+    return results[0][0].value
+
+
+def stream_conversations(uid: str, statuses: Optional[List[str]] = None):
+    """Yield conversation docs as a stream for counting without loading all into memory."""
+    if statuses is None:
+        statuses = []
+    conversations_ref = db.collection('users').document(uid).collection(conversations_collection)
+    conversations_ref = conversations_ref.where(filter=FieldFilter('discarded', '==', False))
+    if statuses:
+        conversations_ref = conversations_ref.where(filter=FieldFilter('status', 'in', statuses))
+    yield from conversations_ref.stream()
+
+
 @prepare_for_read(decrypt_func=_prepare_conversation_for_read)
 def get_conversations_without_photos(
     uid: str,

backend/routers/chat.py

@@ -33,6 +33,7 @@
     resolve_voice_message_language,
     transcribe_voice_message_segment,
 )
+from utils.llm.clients import llm_mini
 from utils.llm.persona import initial_persona_chat_message
 from utils.llm.chat import initial_chat_message
 from utils.llm.goals import extract_and_update_goal_progress
@@ -695,6 +696,50 @@ def rate_message(
     return StatusResponse(status='ok')
 
 
+class TitleMessageInput(BaseModel):
+    text: str
+    sender: str
+
+
+class GenerateTitleRequest(BaseModel):
+    session_id: str
+    messages: List[TitleMessageInput]
+
+
+class GenerateTitleResponse(BaseModel):
+    title: str
+
+
+@router.post('/v2/chat/generate-title', response_model=GenerateTitleResponse, tags=['chat'])
+def generate_chat_title(
+    request: GenerateTitleRequest,
+    uid: str = Depends(auth.get_current_user_uid),
+):
+    """Desktop: generate a short title for a chat session from its messages."""
+    if not request.messages:
+        raise HTTPException(status_code=400, detail="messages list cannot be empty")
+
+    transcript = '\n'.join(f'{m.sender}: {m.text[:500]}' for m in request.messages[:10])
+    prompt = (
+        'Generate a short chat session title (max 6 words) summarising this conversation. '
+        'Return ONLY the title text, no quotes or punctuation.\n\n' + transcript
+    )
+    try:
+        result = llm_mini.invoke(prompt)
+        title = result.content.strip().strip('"\'')[:100]
+    except Exception as e:
+        logger.warning(f'generate_chat_title LLM failed: {e}')
+        title = request.messages[0].text[:50]
+
+    # Update session title if session exists
+    try:
+        chat_db.update_chat_session(uid, request.session_id, {'title': title, 'updated_at': datetime.now(timezone.utc)})
+    except Exception as e:
+        logger.warning(f'generate_chat_title update session failed: {e}')
+
+    return GenerateTitleResponse(title=title)
+
+
 # CLEANUP: Remove after new app goes to prod ----------------------------------------------------------
 
 

backend/routers/conversations.py

@@ -249,6 +249,23 @@ def get_conversations(
     return conversations
 
 
+@router.get('/v1/conversations/count', tags=['conversations'])
+def get_conversations_count(
+    statuses: Optional[str] = Query("processing,completed"),
+    uid: str = Depends(auth.get_current_user_uid),
+):
+    """Count conversations matching optional status filters."""
+    status_list = [s.strip() for s in statuses.split(',') if s.strip()] if statuses else []
+    if len(status_list) > 10:
+        raise HTTPException(status_code=400, detail="Too many status values (max 10)")
+    try:
+        count = conversations_db.count_conversations(uid, statuses=status_list)
+    except Exception as e:
+        logger.warning(f'count_conversations aggregation fallback: {e}')
+        count = sum(1 for _ in conversations_db.stream_conversations(uid, statuses=status_list))
+    return {'count': count}
+
+
 @router.get("/v1/conversations/{conversation_id}", response_model=Conversation, tags=['conversations'])
 def get_conversation_by_id(conversation_id: str, uid: str = Depends(auth.get_current_user_uid)):
     logger.info(f'get_conversation_by_id {uid} {conversation_id}')

backend/test.sh

@@ -42,3 +42,5 @@ pytest tests/unit/test_assistant_settings_ai_profile.py -v
 pytest tests/unit/test_focus_sessions.py -v
 pytest tests/unit/test_advice.py -v
 pytest tests/unit/test_staged_tasks.py -v
+pytest tests/unit/test_chat_generate_title.py -v
+pytest tests/unit/test_conversations_count.py -v

backend/tests/unit/test_chat_generate_title.py

@@ -0,0 +1,209 @@
+import sys
+from datetime import datetime, timezone
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+for mod_name in [
+    'firebase_admin',
+    'firebase_admin.auth',
+    'firebase_admin.firestore',
+    'firebase_admin.messaging',
+    'google.cloud',
+    'google.cloud.exceptions',
+    'google.cloud.firestore',
+    'google.cloud.firestore_v1',
+    'google.cloud.firestore_v1.base_query',
+    'google.cloud.firestore_v1.query',
+    'google.cloud.storage',
+    'google.cloud.storage.blob',
+    'google.cloud.storage.bucket',
+    'google.auth',
+    'google.auth.transport',
+    'google.auth.transport.requests',
+    'google.oauth2',
+    'google.oauth2.service_account',
+    'pinecone',
+    'typesense',
+    'openai',
+    'langchain_openai',
+]:
+    sys.modules.setdefault(mod_name, MagicMock())
+
+# Mock llm_mini before importing the router
+mock_llm = MagicMock()
+mock_llm.invoke.return_value = MagicMock(content='Project Discussion')
+sys.modules.setdefault('utils.llm.clients', MagicMock(llm_mini=mock_llm))
+
+from routers.chat import router
+
+from fastapi import FastAPI, HTTPException
+from fastapi.testclient import TestClient
+
+
+@pytest.fixture
+def client():
+    with patch('routers.chat.auth.get_current_user_uid', return_value='uid-1'):
+        app = FastAPI()
+        app.include_router(router)
+        with TestClient(app) as c:
+            yield c
+
+
+@pytest.fixture
+def client_no_auth():
+    app = FastAPI()
+    app.include_router(router)
+    with TestClient(app) as c:
+        yield c
+
+
+AUTH = {"Authorization": "Bearer 123testuser"}
+
+
+class TestGenerateChatTitle:
+    def test_generate_title_success(self, client):
+        data = {
+            "session_id": "sess-1",
+            "messages": [
+                {"text": "How do I deploy to production?", "sender": "human"},
+                {"text": "You can use the CI/CD pipeline.", "sender": "ai"},
+            ],
+        }
+        with patch('routers.chat.llm_mini') as mock_llm:
+            mock_llm.invoke.return_value = MagicMock(content='Production Deployment')
+            with patch('routers.chat.chat_db.update_chat_session'):
+                resp = client.post("/v2/chat/generate-title", json=data, headers=AUTH)
+        assert resp.status_code == 200
+        assert resp.json()["title"] == "Production Deployment"
+
+    def test_generate_title_strips_quotes(self, client):
+        data = {
+            "session_id": "sess-1",
+            "messages": [{"text": "Hello", "sender": "human"}],
+        }
+        with patch('routers.chat.llm_mini') as mock_llm:
+            mock_llm.invoke.return_value = MagicMock(content='"Greeting Chat"')
+            with patch('routers.chat.chat_db.update_chat_session'):
+                resp = client.post("/v2/chat/generate-title", json=data, headers=AUTH)
+        assert resp.status_code == 200
+        assert resp.json()["title"] == "Greeting Chat"
+
+    def test_generate_title_empty_messages_returns_400(self, client):
+        data = {"session_id": "sess-1", "messages": []}
+        resp = client.post("/v2/chat/generate-title", json=data, headers=AUTH)
+        assert resp.status_code == 400
+
+    def test_generate_title_no_messages_field_returns_422(self, client):
+        data = {"session_id": "sess-1"}
+        resp = client.post("/v2/chat/generate-title", json=data, headers=AUTH)
+        assert resp.status_code == 422
+
+    def test_generate_title_llm_fallback(self, client):
+        data = {
+            "session_id": "sess-1",
+            "messages": [{"text": "What about the budget proposal?", "sender": "human"}],
+        }
+        with patch('routers.chat.llm_mini') as mock_llm:
+            mock_llm.invoke.side_effect = Exception("LLM down")
+            with patch('routers.chat.chat_db.update_chat_session'):
+                resp = client.post("/v2/chat/generate-title", json=data, headers=AUTH)
+        assert resp.status_code == 200
+        assert resp.json()["title"] == "What about the budget proposal?"
+
+    def test_generate_title_updates_session(self, client):
+        data = {
+            "session_id": "sess-1",
+            "messages": [{"text": "Hello", "sender": "human"}],
+        }
+        with patch('routers.chat.llm_mini') as mock_llm:
+            mock_llm.invoke.return_value = MagicMock(content='Greeting')
+            with patch('routers.chat.chat_db.update_chat_session') as mock_update:
+                resp = client.post("/v2/chat/generate-title", json=data, headers=AUTH)
+        assert resp.status_code == 200
+        mock_update.assert_called_once()
+        call_args = mock_update.call_args[0]
+        assert call_args[1] == 'sess-1'
+        assert call_args[2]['title'] == 'Greeting'
+
+    def test_generate_title_session_update_failure_still_returns(self, client):
+        data = {
+            "session_id": "sess-1",
+            "messages": [{"text": "Hello", "sender": "human"}],
+        }
+        with patch('routers.chat.llm_mini') as mock_llm:
+            mock_llm.invoke.return_value = MagicMock(content='Greeting')
+            with patch('routers.chat.chat_db.update_chat_session', side_effect=Exception("DB err")):
+                resp = client.post("/v2/chat/generate-title", json=data, headers=AUTH)
+        assert resp.status_code == 200
+        assert resp.json()["title"] == "Greeting"
+
+    def test_generate_title_truncates_long_title(self, client):
+        data = {
+            "session_id": "sess-1",
+            "messages": [{"text": "Hello", "sender": "human"}],
+        }
+        with patch('routers.chat.llm_mini') as mock_llm:
+            mock_llm.invoke.return_value = MagicMock(content='A' * 200)
+            with patch('routers.chat.chat_db.update_chat_session'):
+                resp = client.post("/v2/chat/generate-title", json=data, headers=AUTH)
+        assert resp.status_code == 200
+        assert len(resp.json()["title"]) <= 100
+
+    def test_generate_title_no_auth_returns_401(self, client_no_auth):
+        data = {
+            "session_id": "sess-1",
+            "messages": [{"text": "Hello", "sender": "human"}],
+        }
+        with patch(
+            'routers.chat.auth.get_current_user_uid',
+            side_effect=HTTPException(status_code=401, detail='Not authenticated'),
+        ):
+            resp = client_no_auth.post("/v2/chat/generate-title", json=data)
+        assert resp.status_code == 401
+
+    def test_generate_title_limits_messages(self, client):
+        """Only first 10 messages should be sent to LLM."""
+        data = {
+            "session_id": "sess-1",
+            "messages": [{"text": f"Message {i}", "sender": "human"} for i in range(20)],
+        }
+        with patch('routers.chat.llm_mini') as mock_llm:
+            mock_llm.invoke.return_value = MagicMock(content='Long Chat')
+            with patch('routers.chat.chat_db.update_chat_session'):
+                resp = client.post("/v2/chat/generate-title", json=data, headers=AUTH)
+        assert resp.status_code == 200
+        prompt = mock_llm.invoke.call_args[0][0]
+        assert 'Message 9' in prompt
+        assert 'Message 10' not in prompt
+
+    def test_generate_title_fallback_truncates_to_50_chars(self, client):
+        """When LLM fails, fallback title is truncated to 50 chars."""
+        long_text = 'A' * 100
+        data = {
+            "session_id": "sess-1",
+            "messages": [{"text": long_text, "sender": "human"}],
+        }
+        with patch('routers.chat.llm_mini') as mock_llm:
+            mock_llm.invoke.side_effect = Exception("LLM down")
+            with patch('routers.chat.chat_db.update_chat_session'):
+                resp = client.post("/v2/chat/generate-title", json=data, headers=AUTH)
+        assert resp.status_code == 200
+        assert len(resp.json()["title"]) == 50
+
+    def test_generate_title_truncates_message_text_to_500_chars(self, client):
+        """Each message text is truncated to 500 chars in the transcript sent to LLM."""
+        long_text = 'B' * 1000
+        data = {
+            "session_id": "sess-1",
+            "messages": [{"text": long_text, "sender": "human"}],
+        }
+        with patch('routers.chat.llm_mini') as mock_llm:
+            mock_llm.invoke.return_value = MagicMock(content='Title')
+            with patch('routers.chat.chat_db.update_chat_session'):
+                resp = client.post("/v2/chat/generate-title", json=data, headers=AUTH)
+        assert resp.status_code == 200
+        prompt = mock_llm.invoke.call_args[0][0]
+        # The transcript line should contain exactly 500 B's, not 1000
+        assert 'B' * 500 in prompt
+        assert 'B' * 501 not in prompt